Python 文档字符串重复参数文本

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 参数的文档环在每种情况下都不同。

我尽量在我的代码中保持干爽，所以重复的文档字符串有点刺耳。有什么方法可以在代码中交叉引用文档字符串参数，但仍然 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

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

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

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

即使你有些怎么做，你总是可以创建它们，在定义上面的函数 load 之后，由 partialing 它们。

编辑：在 OP 的评论之后，我认为您可以简单地在其中一个函数（大概是最基本的 "prototype" 一个）和其他函数中为 dt 编写一次文档简单地说

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

是的，你可以像

一样巧妙地拼接文档字符串

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

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

Python 文档字符串重复参数文本

Python docstring repeated param text

python

docstring