In short: class attributes cannot have doc strings in the way that classes and functions have.
To avoid confusion, the term property has a specific meaning in python. What you're talking about is what we call class attributes. Since they are always acted upon through their class, I find that it makes sense to document them within the class' doc string. Something like this:
class Albatross(object):
"""A bird with a flight speed exceeding that of an unladen swallow.
Attributes:
flight_speed The maximum speed that such a bird can attain.
nesting_grounds The locale where these birds congregate to reproduce.
"""
flight_speed = 691
nesting_grounds = "Throatwarbler Man Grove"
I think that's a lot easier on the eyes than the approach in your example. If I really wanted a copy of the attribute values to appear in the doc string, I would put them beside or below the description of each attribute.
Keep in mind that in Python, doc strings are actual members of the objects they document, not merely source code annotations. Since class attribute variables are not objects themselves but references to objects, they have no way of holding doc strings of their own. I guess you could make a case for doc strings on references, perhaps to describe "what should go here" instead of "what is actually here", but I find it easy enough to do that in the containing class doc string.
Answer from ʇsәɹoɈ on Stack OverflowIn short: class attributes cannot have doc strings in the way that classes and functions have.
To avoid confusion, the term property has a specific meaning in python. What you're talking about is what we call class attributes. Since they are always acted upon through their class, I find that it makes sense to document them within the class' doc string. Something like this:
class Albatross(object):
"""A bird with a flight speed exceeding that of an unladen swallow.
Attributes:
flight_speed The maximum speed that such a bird can attain.
nesting_grounds The locale where these birds congregate to reproduce.
"""
flight_speed = 691
nesting_grounds = "Throatwarbler Man Grove"
I think that's a lot easier on the eyes than the approach in your example. If I really wanted a copy of the attribute values to appear in the doc string, I would put them beside or below the description of each attribute.
Keep in mind that in Python, doc strings are actual members of the objects they document, not merely source code annotations. Since class attribute variables are not objects themselves but references to objects, they have no way of holding doc strings of their own. I guess you could make a case for doc strings on references, perhaps to describe "what should go here" instead of "what is actually here", but I find it easy enough to do that in the containing class doc string.
The other answers are very outdated. PEP-257 describes how you can use docstrings for attributes. They come after the attribute, weirdly:
String literals occurring elsewhere in Python code may also act as documentation. They are not recognized by the Python bytecode compiler and are not accessible as runtime object attributes (i.e. not assigned to __doc__), but two types of extra docstrings may be extracted by software tools:
- String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called “attribute docstrings”.
class C:
"class C doc-string"
a = 1
"attribute C.a doc-string (1)"
b = 2
"attribute C.b doc-string (2)"
It also works for type annotations like this:
class C:
"class C doc-string"
a: int
"attribute C.a doc-string (1)"
b: str
"attribute C.b doc-string (2)"
VSCode supports showing these.
The method of documentation I learned in school is to list a function name, description, parameters, return type, and exceptions. It's serviceable, but a tad verbose and prone to redundancy. What do you recommend?
I am documenting the code for my new password manager. Here is the source on Github.
When authoring OOP code, it is very common to have a file that only contains one class, and nothing else.
This is common in some languages, and may be enforced, like in Java. However, it has very little to do with OOP and more to do with the fact that Java is a popular OOP language. I write/modify several classes in a single file every day (I'm a Python dev), it's a pretty common practice.
PEP8 says that all modules and all classes should have docstrings outlining what they do. But in this case, the module is simply a container for the class. If you put a description of the class, then the information is duplicated
Yes it would be duplicated if you're following a one class per file rule. You have some choices:
Stop following the rule and allow multiple classes per file (especially if you're only following it because it is a perceived best practice)
Just put the docstring in the class and forget the module level docstring. If it's only one class per module (and you strictly follow OOP), then everything will be in the class, so the module docstring will be fairly meaningless. It's perfectly okay to not follow PEP8 to the letter, and in general, it's better to just do what's best for your particular situation than blindly/dogmatically following a standard or best practice.
HTH.
P.S. If a linter is complaining, and this in turn is ruining your builds, there's usually options to turn off certain PEP8 requirements. For example, ignoring E501 (line length greater than 80 chars) is a common one I see that teams choose to ignore (if the pep8 module is your linter, you can do pep8 --ignore=E501, for instance)
Style guides like PEP-8 are not absolute laws that must be followed, but only guides:
However, know when to be inconsistent -- sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!
— PEP 8
Where a module only contains one class, a module-level docstring is not helpful and you should probably leave it out. If you use a linter that requires this superfluous docstring, disable that linter policy for the current file.
If we read PEP-8 more closely, it recommends “docstrings for all public modules”. A module that only contains one class is usually not part of the public interface, you would instead re-export the class through an __init__.py file. Nevertheless, one class per module layouts are fairly rare in Python. You will likely have non-public helper functions or other closely related classes in the same file.