docstring-inheritance是一个 python 包，用于避免编写和维护重复的 python 文档字符串。典型的用法是允许从基类继承文档字符串，以便其派生类完全或部分继承文档字符串。

特征

• 处理 numpy 和 google 文档字符串格式（即基于部分的文档字符串）：
  • NumPy 文档字符串格式规范
  • 谷歌文档字符串格式规范
• 处理函数、类、方法、类方法、静态方法、属性的文档字符串。
• 处理具有多级或多级继承的类的文档字符串。
• 文档字符串部分是单独继承的，就像类的方法一样。
• 对于记录签名的文档字符串部分，签名参数是单独继承的。
• 最低性能成本：在导入时执行继承，而不是每次调用。
• 兼容使用Sphinx渲染文档。

许可证

源代码在 MIT 许可下分发。该文档在 CC BY-SA 4.0 许可下分发。CREDITS.rst 文件中给出了依赖项及其许可证。

安装

通过 pip 安装：

pip install docstring-inheritance

基本用法

继承类的文档字符串

docstring-inheritance提供 元类 以使类的文档字符串能够从其基类继承。此功能也会自动传输到其派生类。对以下文档字符串执行文档字符串继承：

• 班级
• 方法
• 类方法
• 静态方法
• 特性

使用NumpyDocstringInheritanceMeta元类继承 numpy 格式的文档字符串。

使用GoogleDocstringInheritanceMeta元类继承 google 格式的文档字符串。

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

继承函数的文档字符串

docstring-inheritance提供从字符串继承可调用文档字符串的函数。这通常用于从另一个函数继承一个函数的文档字符串。

使用该inherit_google_docstring函数继承 google 格式的文档字符串。

使用该inherit_numpy_docstring函数继承 numpy 格式的文档字符串。

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

文档字符串继承规范

部分顺序

继承的文档字符串的部分根据NumPy 文档字符串格式规范中定义的顺序进行排序 ：

• Summary
• Extended summary
• Parameters对于 NumPy 格式或ArgsGoogle 格式
• Returns
• Yields
• Receives
• Other Parameters
• Attributes
• Methods
• Raises
• Warns
• Warnings
• See Also
• Notes
• References
• Examples
• 接下来是其他名称的部分

此排序也用于使用 Google 文档字符串格式规范编写的文档字符串， 即使它没有定义所有这些部分。

有项目的部分

这些部分是：

• Other Parameters
• Methods
• Attributes

继承是在键级别完成的，即继承者的一部分不会完全覆盖父项：

• 父节而不是子节中的键是继承的，
• 保留子部分而不是父部分中的键，
• 对于同时位于父部分和子部分中的键，将保留子部分。

这允许仅记录继承者的此类部分中的新键。例如：

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

这里的键是属性名称。该属性的描述y已被覆盖，该属性的描述z已被添加。父级唯一剩下的描述是属性x。

记录签名的部分

这些部分是：

• Parameters（仅限 numpy 格式）
• Args（仅限谷歌格式）

除了上面描述的继承行为：

• 继承者签名中不存在的参数被删除，
• 参数根据继承者签名排序，
• 没有描述的参数提供了一个虚拟描述。

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

这里的键是参数名称。参数的描述y已被覆盖，并且z已添加参数的描述。父级唯一剩下的描述是参数w。

高级用法

抽象基类

要创建一个既是抽象又具有文档字符串继承的父类，需要一个额外的元类：

import abc
from docstring_inheritance import NumpyDocstringInheritanceMeta


class Meta(abc.ABCMeta, NumpyDocstringInheritanceMeta):
    pass


class Parent(metaclass=Meta):
    pass

类似项目

custom_inherit： docstring-inherit在重写之前作为这个项目的分支开始，我们感谢它的作者。