将其他 methods/functions/objects 的 "porting" 文档字符串转换为 class 的正确方法？

Question

这是我正在做的事情：

class Foo:
    def __init__(self, **kwargs):
        """
        docstring of Foo.
        """
        self.sum = bar(**kwargs)
    __init__.__doc__ += bar.__doc__

def bar(a, b):
    """
    docstring of bar.
    a: int
    b: int
    """
    print(a+b)

我想做的事情： bar 中定义了一些计算。 class Foo 使用 bar。我想避免重复代码，即我想避免在 Foo 中编写例如 a: int。因此，我试图通过添加 __init__.__doc__ += bar.__doc__.

行将 bar 的文档字符串“移植”（这是正确的术语吗？）到 Foo

这是正确的方法吗？我在黑客攻击吗？假设 Foo 是 API 的一部分，而 bar 是后台子程序。向用户显示 bar 的文档字符串的正确方式是什么？

Answer 1

您需要在 Foo 之前定义 bar。在您当前的配置中，当执行 class 主体时，名称 bar 在全局命名空间中不存在。

您可以考虑在文档之间添加换行符或某种分隔符：

__init__.__doc__ += '\n' +  bar.__doc__

很少直接从文档字符串中读取文档。更好的答案是使用像 sphinx 这样的工具以像 HTML 或 PDF 这样的格式生成可用的文档。您可以 link 而不是将 bar 的文档复制并粘贴到 Foo.__init__ 的文档中。这样做的好处是您不需要重新排列全局命名空间中的对象。

流行的绘图库matplotlib is a great example of your exact usecase. It has many functions, like matplotlib.pyplot.subplots, which passes through is remaining arguments (fig_kw) to matplotlib.pyplot.figure. Looking at the source for the docstring，我们看到：

**fig_kw
    All additional keyword arguments are passed to the
    `.pyplot.figure` call.

反引号在狮身人面像中生成 link。您可以用类似的方式编写 Foo.__init__ 的文档字符串：

"""
docstring of Foo.

Parameters
----------
**kwargs
    Arguments passed through to `bar`.
"""

将其他 methods/functions/objects 的 "porting" 文档字符串转换为 class 的正确方法？

correct way to "porting" docstrings of other methods/functions/objects into a class?

python

oop

docstring