Package: docstring-inheritance
docstring-inheritanceis 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.FeaturesHandle numpy and google docstring formats (i.e. sections based docstrings):NumPy docstring format specificationGoogle docstring format specificationHandle docstrings for functions, classes, methods, class methods, static methods, properties.Handle docstrings for classes with multiple or multi-level inheritance.Docstring sections are inherited individually,
like methods.For docstring sections documenting signatures,
the signature arguments are inherited individually.Minimum performance cost: the inheritance is performed at import time,
not for each call.Compatible with rendering the documentation withSphinx.Missing docstring sections for signature arguments can be notified by warnings
when the environment variableDOCSTRING_INHERITANCE_WARNSis set.Docstring sections can be compared to detect duplicated or similar contents that could be inherited.LicensesThe 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.md file.InstallationInstall with pip:pip install docstring-inheritanceOr with conda:conda install -c conda-forge docstring-inheritanceBasic UsageInheriting docstrings for classesdocstring-inheritanceprovidesmetaclassesto 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:classmethodsclassmethodsstaticmethodspropertiesUse theNumpyDocstringInheritanceMetametaclass 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 theNumpyDocstringInheritanceInitMetametaclass.Use theGoogleDocstringInheritanceMetametaclass 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 theGoogleDocstringInheritanceInitMetametaclass.fromdocstring_inheritanceimportNumpyDocstringInheritanceMetaclassParent(metaclass=NumpyDocstringInheritanceMeta):defmethod(self,x,y=None):"""Parent summary.Parameters----------x:Description for x.y:Description for y.Notes-----Parent notes."""classChild(Parent):defmethod(self,x,z):"""Parameters----------z:Description for z.Returns-------Something.Notes-----Child notes."""# The inherited docstring isChild.method.__doc__=="""Parent summary.Parameters----------x:Description for x.z:Description for z.Returns-------Something.Notes-----Child notes."""Inheriting docstrings for functionsdocstring-inheritanceprovides 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 theinherit_google_docstringfunction to inherit docstrings in google format.Use theinherit_numpy_docstringfunction to inherit docstrings in numpy format.fromdocstring_inheritanceimportinherit_google_docstringdefparent():"""Parent summary.Args:x: Description for x.y: Description for y.Notes:Parent notes."""defchild():"""Args:z: Description for z.Returns:Something.Notes:Child notes."""inherit_google_docstring(parent.__doc__,child)# The inherited docstring ischild.__doc__=="""Parent summary.Args:x: Description for x.z: Description for z.Returns:Something.Notes:Child notes."""Docstring inheritance specificationSections orderThe sections of an inherited docstring are sorted according to order defined in theNumPy docstring format specification:SummaryExtended summaryParametersfor the NumPy format orArgsfor the Google formatReturnsYieldsReceivesOther ParametersAttributesMethodsRaisesWarnsWarningsSee AlsoNotesReferencesExamplessections with other names come nextThis ordering is also used for the docstring written with theGoogle docstring format specificationeven though it does not define all of these sections.Sections with itemsThose sections are:Other ParametersMethodsAttributesThe inheritance is done at the key level,
i.e. a section of the inheritor will not fully override the parent one:the keys in the parent section and not in the child section are inherited,the keys in the child section and not in the parent section are kept,for keys that are both in the parent and child section,
the child ones are kept.This allows to only document the new keys in such a section of an inheritor.
For instance:fromdocstring_inheritanceimportNumpyDocstringInheritanceMetaclassParent(metaclass=NumpyDocstringInheritanceMeta):"""Attributes----------x:Description for xy:Description for y"""classChild(Parent):"""Attributes----------y:Overridden description for yz:Description for z"""# The inherited docstring isChild.__doc__=="""Attributes----------x:Description for xy:Overridden description for yz:Description for z"""Here the keys are the attribute names.
The description for the attributeyhas been overridden
and the description for the attributezhas been added.
The only remaining description from the parent is for the attributex.Sections documenting signaturesThose sections are:Parameters(numpy format only)Args(google format only)In addition to the inheritance behavior describedabove:the arguments not existing in the inheritor signature are removed,the arguments are sorted according the inheritor signature,the arguments with no description are provided with a dummy description.fromdocstring_inheritanceimportGoogleDocstringInheritanceMetaclassParent(metaclass=GoogleDocstringInheritanceMeta):defmethod(self,w,x,y):"""Args:w: Description for wx: Description for xy: Description for y"""classChild(Parent):defmethod(self,w,y,z):"""Args:z: Description for zy: Overridden description for y"""# The inherited docstring isChild.method.__doc__=="""Args:w: Description for wy: Overridden description for yz: Description for z"""Here the keys are the argument names.
The description for the argumentyhas been overridden
and the description for the argumentzhas been added.
The only remaining description from the parent is for the argumentw.Advanced usageAbstract base classTo create a parent class that both is abstract and has docstring inheritance,
an additional metaclass is required:importabcfromdocstring_inheritanceimportNumpyDocstringInheritanceMetaclassMeta(abc.ABCMeta,NumpyDocstringInheritanceMeta):passclassParent(metaclass=Meta):passDetecting similar docstringsDuplicated docstrings that could benefit from inheritance can be detected
by setting the environment variableDOCSTRING_INHERITANCE_SIMILARITY_RATIOto a value between0and1.
When set, the docstring sections of a child and its parent are compared and warnings are issued when the docstrings are
similar.
The docstring sections are compared withdifflib ratiofrom the standard library.
If the ratio is higher or equal to the value ofDOCSTRING_INHERITANCE_SIMILARITY_RATIO,
the docstring sections are considered similar.
Use a ratio of1to detect identical docstring sections.
Use a ratio lower than1to detect similar docstring sections.Similar projectscustom_inherit:docstring-inheritstarted as fork of this project before being re-written,
we thank its author.