docstring-inheritance

3.0.0 verified Fri May 01 auth: no python

Avoid writing and maintaining duplicated docstrings by automatically inheriting and merging docstrings from parent classes. Current version 3.0.0, requires Python >=3.10 <4.0. Active development with infrequent releases.

pip install docstring-inheritance

Common errors

error ImportError: cannot import name 'inherit_docstring' from 'docstring_inheritance' ↓

cause Using the singular import name which was removed in version 3.0.0.

fix

Use 'from docstring_inheritance import inherit_docstrings' (plural).

error TypeError: 'NoneType' object is not callable ↓

cause Applying @inherit_docstrings to a method instead of a class. The decorator returns None when applied to a method.

fix

Apply the decorator to the class definition, e.g., @inherit_docstrings class Child(Base): ...

Warnings

breaking In version 3.0.0, the default behavior changed to not inherit docstrings automatically unless the @inherit_docstrings decorator is explicitly applied. Previously, in version 2.x, docstring inheritance happened automatically for all subclasses. Update your code to add the decorator. ↓

fix Apply @inherit_docstrings to each class that should inherit docstrings. Or set a global flag if supported (check docs).

deprecated The 'inherit_docstring' (singular) function was deprecated in favor of 'inherit_docstrings' (plural) in version 2.x and removed in 3.0.0. ↓

fix Use 'from docstring_inheritance import inherit_docstrings' instead.

gotcha The decorator only works on classes, not on individual methods. If you apply it to a method, it will be silently ignored or raise an error. ↓

fix Apply @inherit_docstrings to the class definition, not to individual methods.

Imports

inherit_docstrings

wrong

from docstring_inheritance import inherit_docstring

correct

from docstring_inheritance import inherit_docstrings

Function name is plural (inherit_docstrings), not singular.

Quickstart

Apply the @inherit_docstrings decorator to a class to inherit docstrings from parent classes. Child class methods will automatically merge the parent's docstring with any new content.

from docstring_inheritance import inherit_docstrings

class Base:
    def method(self, x: int, y: str) -> bool:
        """Do something.

        Parameters
        ----------
        x : int
            First parameter.
        y : str
            Second parameter.

        Returns
        -------
        bool
            Result.
        """
        return True

@inherit_docstrings
class Child(Base):
    def method(self, x: int, y: str) -> bool:
        # Only the extra information is added here; docstring is inherited.
        return True

print(Child.method.__doc__)