Yes just drop the methods section from the class docstring. I've never ever seen something like that used.(It is used in few places in the standard library.) The class docstring needs to just describe the class and the docstring of individual methods then handle describing themselves.
Also the wording in the PEP to me means that the class docstring "should" list the public methods, but not describe them in any other way.(This is also how the above standard library example does it.) But as said, I would never even do that, since the code speaks for itself and that kind of listing is bound to get out-of-date.
Final note: I personally prefer to use the Google docstring style, because to me it's the clearest and cleanest.
Answer from ruohola on Stack OverflowYes just drop the methods section from the class docstring. I've never ever seen something like that used.(It is used in few places in the standard library.) The class docstring needs to just describe the class and the docstring of individual methods then handle describing themselves.
Also the wording in the PEP to me means that the class docstring "should" list the public methods, but not describe them in any other way.(This is also how the above standard library example does it.) But as said, I would never even do that, since the code speaks for itself and that kind of listing is bound to get out-of-date.
Final note: I personally prefer to use the Google docstring style, because to me it's the clearest and cleanest.
example:
class Animal:
"""
A class used to represent an Animal
...
Attributes
----------
says_str : str
a formatted string to print out what the animal says
name : str
the name of the animal
sound : str
the sound that the animal makes
num_legs : int
the number of legs the animal has (default 4)
Methods
-------
says(sound=None)
Prints the animals name and what sound it makes
"""
says_str = "A {name} says {sound}"
def __init__(self, name, sound, num_legs=4):
"""
Parameters
----------
name : str
The name of the animal
sound : str
The sound the animal makes
num_legs : int, optional
The number of legs the animal (default is 4)
"""
self.name = name
self.sound = sound
self.num_legs = num_legs
def says(self, sound=None):
"""Prints what the animals name is and what sound it makes.
If the argument `sound` isn't passed in, the default Animal
sound is used.
Parameters
----------
sound : str, optional
The sound the animal makes (default is None)
Raises
------
NotImplementedError
If no sound is set for the animal or passed in as a
parameter.
"""
if self.sound is None and sound is None:
raise NotImplementedError("Silent Animals are not supported!")
out_sound = self.sound if sound is None else sound
print(self.says_str.format(name=self.name, sound=out_sound))
Yep, listing methods in the class docstring, then each method again documented, according to this standard. I reccomend using sphinx, though: https://www.sphinx-doc.org/en/master/contents.html
Advice on writing some docstrings
python - How should docstrings be used in modules with one class? - Software Engineering Stack Exchange
Should I use docstrings for __init__ and __repr__?
What's the best guide/model to writing good docstrings for modules/classes/methods?
I need to write docstrings for every method and property in this file:
https://github.com/golemfactory/yapapi/blob/master/yapapi/services/service_runner.py
A couple questions.
Should you write a docstring for an init method? I suppose it depends? This one seems self explanatory. Should I just state what the code does? “ServiceRunner class is initialized with four parameters: job, instance, instance_tasks, and stopped.”
I could explain what each of those do. I actually have some questions about them. “Job” is clearly passed the string “job”, so I don’t understand the later call “job.id” - the string returns an ID?
As for: self._instances: List[Service] = [] - how can you pass an entire statement as an attribute? They convert “Service” to a list but then assign it as an empty list… will the result be the list of services or the empty list?
Just that for now. Please let me know if you understand this a bit better than I do.
Thanks very much
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.