How should docstrings be used in modules with one class?

Question

When authoring OOP code, sometimes you have a file that only contains one class, and nothing else.

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:

"""
Contains a class for connecting to and communicating with a server.
"""

class Client:
    """
    Class for connecting to and communicating with a server.
    """
    def __init__(self):
        ...

So what should go in the docstrings? Perhaps the module docstring should say Contains Foo or something similar?

Answer 1

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:

1. Stop following the rule and allow multiple classes per file (especially if you're only following it because it is a perceived best practice)

2. 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)

Answer 2

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.