装饰器的文档字符串放在哪里

Question

我正在尝试记录装饰器，但不确定文档字符串应该放在哪里。从技术上讲，它是包含我要记录的参数的内部包装器，但用户将应用外部函数名称作为装饰器。

例如，

def change_case(func):
    """Does the doc string go here
    """
    def _wrapper(s, case=None):
        """Or, does the doc string go here?
        """
        if case == 'Upper':
            s = s.upper()
        elif case == 'Lower':
            s = s.lower()
        return func(s)

    return _wrapper

@change_case
def echo(s):
    return s

echo('Test', case='Upper')

在上面，文档字符串是在 change_case() 还是 _wrapper() 之后。我倾向于前者。

Answer 1

将实际装饰器的文档放在顶级装饰器函数中。当用户试图使用你的装饰器时，他们会希望在这里找到它的文档。例如，从标准库中获取 functools.singledispatch 装饰器：

>>> from functools import singledispatch
>>>
>>> print(singledispatch.__doc__) # the decorator has it's documentation in the actually decorator function
Single-dispatch generic function decorator.

    Transforms a function into a generic function, which can have different
    behaviours depending upon the type of its first argument. The decorated
    function acts as the default implementation, and additional
    implementations can be registered using the register() attribute of the
    generic function.


>>>

但是，您还应该使用 functools.wraps 将 decorated 函数中包含的任何文档传输到包装函数：

>>> from functools import wraps
>>>
>>> def dec(func):
...     @wraps(func)
...     def wrap(*args, **kwargs):
...         return func(*args, **kwargs)
...     return wrap
...
>>> @dec
... def func():
...     """Docstring here"""
...
>>> print(func.__doc__)
Docstring here
>>>

装饰器的文档字符串放在哪里

Where to put the doc string for a decorator

python

docstring

decorator

python-3.x

python-decorators