Где поставить строку документации для декоратора

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')

Inвыше, строка документа идет после 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 для передачи любой документации, содержащейся в функция для функции оболочки:

>>> 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
>>>