docstring-inheritance
is a python package to avoid writing and maintaining duplicated python docstrings.
The typical usage is to enable the inheritance of the docstrings from a base class
such that its derived classes fully or partly inherit the docstrings.
The source code is distributed under the MIT license. The documentation is distributed under the CC BY 4.0 license. The dependencies, with their licenses, are given in the CREDITS.rst file.
Install with pip:
pip install docstring-inheritance
Or with conda:
conda install -c conda-forge docstring-inheritance
docstring-inheritance
provides
metaclasses
to enable the docstrings of a class to be inherited from its base classes.
This feature is automatically transmitted to its derived classes as well.
The docstring inheritance is performed for the docstrings of the:
Use the NumpyDocstringInheritanceMeta
metaclass to inherit docstrings in numpy format
if __init__
method is documented in its own docstring.
Otherwise, if __init__
method is documented in the class docstring,
use the NumpyDocstringInheritanceInitMeta
metaclass.
Use the GoogleDocstringInheritanceMeta
metaclass to inherit docstrings in google format.
if __init__
method is documented in its own docstring.
Otherwise, if __init__
method is documented in the class docstring,
use the GoogleDocstringInheritanceInitMeta
metaclass.
from docstring_inheritance import NumpyDocstringInheritanceMeta
class Parent(metaclass=NumpyDocstringInheritanceMeta):
def method(self, x, y=None):
"""Parent summary.
Parameters
----------
x:
Description for x.
y:
Description for y.
Notes
-----
Parent notes.
"""
class Child(Parent):
def method(self, x, z):
"""
Parameters
----------
z:
Description for z.
Returns
-------
Something.
Notes
-----
Child notes.
"""
# The inherited docstring is
Child.method.__doc__ == """Parent summary.
Parameters
----------
x:
Description for x.
z:
Description for z.
Returns
-------
Something.
Notes
-----
Child notes.
"""
docstring-inheritance
provides functions to inherit the docstring of a callable from a string.
This is typically used to inherit the docstring of a function from another function.
Use the inherit_google_docstring
function to inherit docstrings in google format.
Use the inherit_numpy_docstring
function to inherit docstrings in numpy format.
from docstring_inheritance import inherit_google_docstring
def parent():
"""Parent summary.
Args:
x: Description for x.
y: Description for y.
Notes:
Parent notes.
"""
def child():
"""
Args:
z: Description for z.
Returns:
Something.
Notes:
Child notes.
"""
inherit_google_docstring(parent.__doc__, child)
# The inherited docstring is
child.__doc__ == """Parent summary.
Args:
x: Description for x.
z: Description for z.
Returns:
Something.
Notes:
Child notes.
"""
The sections of an inherited docstring are sorted according to order defined in the NumPy docstring format specification:
Summary
Extended summary
Parameters
for the NumPy format or Args
for the Google formatReturns
Yields
Receives
Other Parameters
Attributes
Methods
Raises
Warns
Warnings
See Also
Notes
References
Examples
This ordering is also used for the docstring written with the Google docstring format specification even though it does not define all of these sections.
Those sections are:
Other Parameters
Methods
Attributes
The inheritance is done at the key level, i.e. a section of the inheritor will not fully override the parent one:
This allows to only document the new keys in such a section of an inheritor. For instance:
from docstring_inheritance import NumpyDocstringInheritanceMeta
class Parent(metaclass=NumpyDocstringInheritanceMeta):
"""
Attributes
----------
x:
Description for x
y:
Description for y
"""
class Child(Parent):
"""
Attributes
----------
y:
Overridden description for y
z:
Description for z
"""
# The inherited docstring is
Child.__doc__ == """
Attributes
----------
x:
Description for x
y:
Overridden description for y
z:
Description for z
"""
Here the keys are the attribute names.
The description for the attribute y
has been overridden
and the description for the attribute z
has been added.
The only remaining description from the parent is for the attribute x
.
Those sections are:
Parameters
(numpy format only)Args
(google format only)In addition to the inheritance behavior described above:
from docstring_inheritance import GoogleDocstringInheritanceMeta
class Parent(metaclass=GoogleDocstringInheritanceMeta):
def method(self, w, x, y):
"""
Args:
w: Description for w
x: Description for x
y: Description for y
"""
class Child(Parent):
def method(self, w, y, z):
"""
Args:
z: Description for z
y: Overridden description for y
"""
# The inherited docstring is
Child.method.__doc__ == """
Args:
w: Description for w
y: Overridden description for y
z: Description for z
"""
Here the keys are the argument names.
The description for the argument y
has been overridden
and the description for the argument z
has been added.
The only remaining description from the parent is for the argument w
.
To create a parent class that both is abstract and has docstring inheritance, an additional metaclass is required:
import abc
from docstring_inheritance import NumpyDocstringInheritanceMeta
class Meta(abc.ABCMeta, NumpyDocstringInheritanceMeta):
pass
class Parent(metaclass=Meta):
pass
custom_inherit:
docstring-inherit
started as fork of this project before being re-written,
we thank its author.