How should I handle docstrings of subclass methods?

Question

I have an abstract class structured somewhat like this:

class AbstractQuery(object, zip_code):
 def execute(self):
 """
 Retrieve information about a zip code
 The information returned will depend on the subclass
 """
 url, params = self._build_query(zip_code)
 response = requests.get(url, params=params)
 if self._is_valid(response):
 # etc.
 def _build_query(self, zip_code):
 """
 Returns a tuple (url, params) where
 url is the url of the API to query and
 params are the query params for the API call
 """
 raise NotImplementedError
 def _is_valid(self, response):
 """
 Returns True if response contains information necessary
 to continue processing
 """
 raise NotImplementedError

_build_query for example is always going to do the same thing, there's just going to be minor implementation differences. Do I just keep the docstring in the base class? Or copy/paste it down and violate DRY? What would a user or maintainer of these classes want to see?

Answer 1

From PEP 257:

The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own docstring.

If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences. Use the verb "override" to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method (in addition to its own behavior).

So if you want to follow Python standards, use language indicating that the method is overriden in your subclass docstring.

• Tim Smith: Note that this amounts to a recommendation about the class docstring; PEP 257 is silent about docstrings on subclass methods.
• Olúwátóósìn Anímáṣahun: @TimSmith: How do you mean "silent", when this answer actually quotes PEP 257?

Answer 2

Do I just keep the docstring in the base class?

If your derived class has nothing to add to the description, this seems like the right choice - Python 3.5 and onwards will walk the inheritance to find a docstring:

import inspect
class Base:
 def method(self):
 """Do something"""
class Derived(Base):
 def method(self):
 pass
print(inspect.getdoc(Derived.method)) # prints "Do something"

Note that this does not work if Derived is defined in an interactive console, but that shouldn't matter.

• Olúwátóósìn Anímáṣahun: Here are two tenets from the Zen of Python (PEP 20) that I find to be in conflict with this answer: > 1. "In the face of ambiguity, refuse the temptation to guess." > 2. "Explicit is better than implicit." -- Therefore, I would go with the answer from @enderland referencing PEP 257.
• Eric: I don't understand where the "guessing" comes from here; you seem to be criticizing the addition of this behavior to Python 3.5, but I'd argue anything that passes core review takes precedence over the PEP20 (although you could of course file an issue against python asking for this behavior to be reverted). PEP257 seems silent on abstract methods, which neither "extend" nor "override"; they simply provide the implementation.