Assuming we have different classes with methods that possess the exact same description, however execute code a bit differently for the same return type.
class Foo:
"""This is the Foo class Docstring. It is a type of Bar source."""
def getBar(self,pos):
"""
This is the Bar method.
It calculates and returns the Bar field effect generated
by this source based on `pos`
"""
effect = pos + 1
return effect
class Waldo:
"""This is the Waldo class Docstring. It's also a type of Bar source."""
def getBar(self,pos):
"""
This is the Bar method.
It calculates and returns the Bar field effect generated
by this source based on `pos`
"""
effect = pos + 2
return effect
This is a problem because, assuming there are many Bar sources, if one changes the description for getBar() they’ll have to repeat the change for all the sources.
How could one make it so there’s a single Docstring shared between both or more of these, having it so a change in Foo.getBar() would change the description of Waldo.getBar() for tooltips?
A way of restructuring or overriding in order to achieve the same effect would also be welcome.
I’ve tried the __doc__+=Foo.getBar().__doc__ approach in this question but it seems unreliable (using an environment like Spyder for instance, it recognizes it as a local variable).
Different tools access docstrings differently. For example, having a common base class that provides this docstring may be sufficient for some tools but not others.
The most general approach would be to define a functools.wraps() like decorator that copies the docstring of a function, e.g.:
def is_documented_by(original):
def wrapper(target):
target.__doc__ = original.__doc__
return target
return wrapper
class Waldo:
@is_documented_by(Foo.getBar)
def getBar():
...
But since this requires executing the Python code, static analyzers like Pylint may not like this. The best solution depends on the tools you are going to use.
The approach I’ve implemented for this was the following:
class Field_Sampler:
def getBar(self,pos):
"""
This is the Bar method.
It calculates and returns the Bar field effect generated
by this source based on `pos`
"""
import warnings
warnings.warn(
"called getBar method is not implemented in this class,"
"returning 0", RuntimeWarning)
return 0
class Foo(Field_Sampler):
"""This is the Foo class Docstring. It is a type of Bar source."""
def getBar(self,pos):
effect = pos + 1
return effect
class Waldo(Field_Sampler):
"""This is the Waldo class Docstring. It's also a type of Bar source."""
def getBar(self,pos):
effect = pos + 2
return effect
class Epsilon(Field_Sampler):
"""[WIP]This is the Epsilon class Docstring. It's also a type of Bar source."""
pass
A top class has the function prototype with the docstring. Classes inherit this and override the implementation definition of the method. If there’s no docstring on the overriden function, then the docstring of the parent is used by most doc interpreters, including Sphinx.
This allowed me to set up the numerous classes while retaining the structure (which included more methods) and stopping static analyzers from freaking out. In the event the method wasn’t implemented yet, we have it throw a warning if someone happens to call it.
1