docstring-inheritance

PyPI - Python Version PyPI Conda (channel only) Code Style Codecov branch

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.

Features

Licenses

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.

Installation

Install with pip:

pip install docstring-inheritance

Or with conda:

conda install -c conda-forge docstring-inheritance

Basic Usage

Inheriting docstrings for classes

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.

Use the GoogleDocstringInheritanceMeta metaclass to inherit docstrings in google format.

from docstring_inheritance import NumpyDocstringInheritanceMeta


class Parent(metaclass=NumpyDocstringInheritanceMeta):
    def meth(self, x, y=None):
        """Parent summary.

        Parameters
        ----------
        x:
           Description for x.
        y:
           Description for y.

        Notes
        -----
        Parent notes.
        """


class Child(Parent):
    def meth(self, x, z):
        """
        Parameters
        ----------
        z:
           Description for z.

        Returns
        -------
        Something.

        Notes
        -----
        Child notes.
        """


# The inherited docstring is
Child.meth.__doc__ = """Parent summary.

Parameters
----------
x:
   Description for x.
z:
   Description for z.

Returns
-------
Something.

Notes
-----
Child notes.
"""

Inheriting docstrings for functions

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.
"""

Docstring inheritance specification

Sections order

The sections of an inherited docstring are sorted according to order defined in the NumPy docstring format specification:

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.

Sections with items

Those sections are:

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.

Sections documenting signatures

Those sections are:

In addition to the inheritance behavior described above:

from docstring_inheritance import GoogleDocstringInheritanceMeta


class Parent(metaclass=GoogleDocstringInheritanceMeta):
    def meth(self, w, x, y):
        """
        Args:
            w: Description for w
            x: Description for x
            y: Description for y
        """


class Child(Parent):
    def meth(self, w, y, z):
        """
        Args:
            z: Description for z
            y: Overridden description for y
        """


# The inherited docstring is
Child.meth.__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.

Advanced usage

Abstract base class

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

Similar projects

custom_inherit: docstring-inherit started as fork of this project before being re-written, we thank its author.