Python docstring 重复的参数文本

Question

在一个 Python 模块中（该模块旨在供技术水平较低的用户在 IPython Notebooks 中使用），我有几个功能：

load_this(dt, this_filter)
load_that(dt, that_filter)
load_the_other(dt, the_other_filter)

dt 参数的文档字符串对于每个函数都是相同的：

:param dt: date, date tuple, or datetime tuple. 
    date type args expand to start and end of day.
    eg.  date(2015, 9, 9) or
    (date(2015, 9, 9), date(2015, 9, 10)) or
    (datetime(2015, 9, 9, 12, 30), datetime(2015, 9, 9, 1))

但是，x_filter 参数的 docsring 在每种情况下都不同。

我尽量在我的代码中保持 DRY，所以重复的文档字符串有点刺耳。有没有办法在代码中交叉引用文档字符串参数，但仍然让 IPython 显示完整的文档字符串。

谢谢

Answer 1

您可以通过装饰器将文档添加到函数中

def mydoc(func):
    func.__doc__ = 'Here I am.'
    return func

@mydoc
def load_this(dt):
    pass

带有自定义文档的变体

def setdoc(docstring):
    def decor(func):
        func.__doc__ = docstring
        return func
    return decor

@setdoc('Here I am.')
def load_this(dt):
    pass

或者在定义函数后添加文档

docmessage = 'Here I am.'
def load_this(dt):
    pass
load_this.__doc__ = docmessage

Answer 2

不是以编程方式生成文档字符串（在我看来相当不合 Python），是什么阻止你只定义一个函数 load like

def load(dt, filter_):
    ... ...

并为它编写一个文档？我真的看不出需要 3 个单独的功能。

即使你有一些方法，你也可以在定义上面的函数load之后，通过partialing它们来创建它们。

---

编辑：在 OP 发表评论后，我认为您可以在其中一个函数（可能是最基本的“原型”函数）中简单地为 dt 编写文档，然后在其他函数中简单地说

"See the documentation of ___ for details about dt".

是的，你可以像这样巧妙地拼接文档字符串

some_function.__doc__ = some_function.__doc__ + "doc for dt"

或者比编写自己的文档生成元类生成器工厂框架更聪明，但是为什么呢？ ;)