docstring-inheritance是一个Python包，用于避免编写和维护重复的Python docstrings。典型用法是启用基类中docstrings的继承，以便其派生类完全或部分继承docstrings。

功能

• 处理NumPy和Google docstring格式（即基于部分的docstrings）
  • NumPy docstring格式规范
  • Google docstring格式规范
• 处理函数、类、方法、类方法、静态方法和属性的docstrings。
• 处理具有多或多层继承的类的docstrings。
• Docstring部分像方法一样单独继承。
• 对于文档签名部分的docstrings，签名参数可以单独继承。
• 最小性能成本：继承在导入时执行，而不是每个调用。
• 与使用Sphinx和mkdocs（见下文）渲染文档兼容。
• 当设置环境变量DOCSTRING_INHERITANCE_WARNS时，可以通过警告通知签名参数缺失的docstring部分。
• 可以通过比较来检测重复或类似的内容，这些内容可以继承。

许可证

源代码在MIT许可证下分发。文档在CC BY 4.0许可证下分发。依赖关系及其许可证在CREDITS.md文件中给出。

安装

使用pip安装

pip install docstring-inheritance

或使用conda

conda install -c conda-forge docstring-inheritance

基本用法

类文档字符串的继承

docstring-inheritance 提供了 元类，以允许类的文档字符串从其基类继承。此功能将自动传递到其派生类。文档字符串的继承适用于以下内容：

• 类
• 方法
• 类方法
• 静态方法
• 属性

使用 NumpyDocstringInheritanceMeta 元类在 __init__ 方法有自身文档字符串的情况下继承 numpy 格式的文档字符串。否则，如果 __init__ 方法在类文档字符串中进行了文档化，则使用 NumpyDocstringInheritanceInitMeta 元类。

使用 GoogleDocstringInheritanceMeta 元类在 __init__ 方法有自身文档字符串的情况下继承 google 格式的文档字符串。否则，如果 __init__ 方法在类文档字符串中进行了文档化，则使用 GoogleDocstringInheritanceInitMeta 元类。

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 提供了从字符串继承可调用对象文档字符串的函数。这通常用于从另一个函数继承函数的文档字符串。

使用 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 文档字符串格式规范 中定义的顺序排序

• 摘要
• 扩展摘要
• NumPy 格式的 Parameters 或 Google 格式的 Args
• 返回值
• 生成器
• 接收者
• 其他参数
• 属性
• 方法
• 抛出
• 警告
• 警告
• 另请参阅
• 备注
• 参考文献
• 示例
• 具有其他名称的章节随后

尽管 Google 文档字符串格式规范没有定义所有这些章节，但此顺序也用于编写文档字符串的规范。

具有条目的章节

这些章节是

• 其他参数
• 方法
• 属性

继承是在键级别进行的，即继承者的章节不会完全覆盖父类的一个章节

• 父类章节中的键继承，而不是子类章节中的键继承，
• 子类章节中的键保留，而不是父类章节中的键保留，
• 对于同时在父类和子类章节中都存在的键，保留子类中的键。

这允许仅在继承者的此类章节中仅记录新键。例如

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（仅限 google 格式）

除了上述描述的继承行为外

• 从继承者签名中删除不存在的参数，
• 根据继承者签名对参数进行排序，
• 为没有描述的参数提供模拟描述。

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

在这里，键是参数名称。参数 y 的描述已被覆盖，参数 z 的描述已被添加。仅保留来自父类的参数 w 的描述。

高级用法

抽象基类

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

import abc
from docstring_inheritance import NumpyDocstringInheritanceMeta


class Meta(abc.ABCMeta, NumpyDocstringInheritanceMeta):
  pass


class Parent(metaclass=Meta):
  pass

检测相似的文档字符串

可以通过设置环境变量 DOCSTRING_INHERITANCE_SIMILARITY_RATIO 为介于 0 和 1 之间的值来检测可以受益于继承的重复文档字符串。当设置时，子类及其父类的文档字符串部分将被比较，并且在文档字符串相似时发出警告。文档字符串部分使用标准库中的 difflib 比率 进行比较。如果比率高于或等于 DOCSTRING_INHERITANCE_SIMILARITY_RATIO 的值，则认为文档字符串部分是相似的。使用 1 的比率来检测完全相同的文档字符串部分。使用小于 1 的比率来检测相似的文档字符串部分。

Mkdocs

要使用 mkdocs 渲染文档，需要安装包 mkdocstring[python]，并推荐安装 griffe-inherited-docstrings 包，最后需要在 mkdocs.yml 中添加以下内容：

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          extensions:
            - griffe_inherited_docstrings
            - docstring_inheritance.griffe

类似项目

custom_inherit：docstring-inherit 最初是这个项目的分支，后来被重写，我们感谢其作者。