时间戳

首页 > 解决方案 > 将其他方法/函数/对象的文档字符串“移植”到类中的正确方法？

python - 将其他方法/函数/对象的文档字符串“移植”到类中的正确方法？

问题描述

这是我正在做的事情：

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. 该类Foo使用bar. 我想避免重复的代码，例如，我想避免a: int在Foo. 因此，我试图通过添加该行bar来“移植”（这是正确的术语吗？）的文档字符串。Foo__init__.__doc__ += bar.__doc__

这是正确的方法吗？我在窃听吗？ImagineFoo是 API 的一部分，而是bar后台子程序。向用户显示文档字符串的正确bar方法是什么？

标签： pythonoopdocstring

解决方案

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

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

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

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

流行的绘图库matplotlib是您的确切用例的一个很好的例子。它有很多函数，比如matplotlib.pyplot.subplots，它通过剩余的参数 ( fig_kw) 到matplotlib.pyplot.figure。查看docstring的源代码，我们看到：

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

反引号在 sphinx 中生成链接。Foo.__init__您可以以类似的方式编写文档字符串：

"""
docstring of Foo.

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

推荐阅读