Что делает functools.wraps?

В комментарии к этому ответу на другой вопрос кто-то сказал, что они не уверены, что functools.wrapsделают. Итак, я задаю этот вопрос, чтобы в StackOverflow была запись об этом для дальнейшего использования: что именно делает functools.wraps?

Когда вы используете декоратор, вы заменяете одну функцию другой. Другими словами, если у вас есть декоратор

def logged(func):
    def with_logging(*args, **kwargs):
        print(func.__name__ + " was called")
        return func(*args, **kwargs)
    return with_logging

тогда, когда вы говорите

@logged
def f(x):
   """does some math"""
   return x + x * x

это точно так же, как сказать

def f(x):
    """does some math"""
    return x + x * x
f = logged(f)

и ваша функция fзаменяется на функцию with_logging. К сожалению, это означает, что если вы скажете

print(f.__name__)

он будет напечатан, with_loggingпотому что это имя вашей новой функции. На самом деле, если вы посмотрите на строку документации f, она будет пустой, потому with_loggingчто не содержит строки документации, и поэтому записанной вами строки документации больше не будет. Кроме того, если вы посмотрите на результат pydoc для этой функции, он не будет указан как принимающий один аргумент x; вместо этого он будет указан как take *argsи **kwargsпотому что это то, что принимает with_logging.

Если использование декоратора всегда означало потерю этой информации о функции, это было бы серьезной проблемой. Вот почему у нас есть functools.wraps. Это берет функцию, используемую в декораторе, и добавляет функциональность копирования по имени функции, строке документации, списку аргументов и т. Д. А так wrapsкак сам по себе декоратор, следующий код делает правильную вещь:

from functools import wraps
def logged(func):
    @wraps(func)
    def with_logging(*args, **kwargs):
        print(func.__name__ + " was called")
        return func(*args, **kwargs)
    return with_logging

@logged
def f(x):
   """does some math"""
   return x + x * x

print(f.__name__)  # prints 'f'
print(f.__doc__)   # prints 'does some math'

Я очень часто использую классы, а не функции, для своих декораторов. У меня были некоторые проблемы с этим, потому что объект не будет иметь все те же атрибуты, которые ожидаются от функции. Например, у объекта не будет атрибута __name__. У меня была конкретная проблема с этим, которую было довольно трудно отследить, когда Django сообщал об ошибке «У объекта нет атрибута __name__». К сожалению, для декораторов в стиле класса я не верю, что @wrap сделает эту работу. Вместо этого я создал базовый класс декоратора следующим образом:

class DecBase(object):
    func = None

    def __init__(self, func):
        self.__func = func

    def __getattribute__(self, name):
        if name == "func":
            return super(DecBase, self).__getattribute__(name)

        return self.func.__getattribute__(name)

    def __setattr__(self, name, value):
        if name == "func":
            return super(DecBase, self).__setattr__(name, value)

        return self.func.__setattr__(name, value)

Этот класс передает все вызовы атрибута для функции, которая оформляется. Итак, теперь вы можете создать простой декоратор, который проверяет, что 2 аргумента указаны примерно так:

class process_login(DecBase):
    def __call__(self, *args):
        if len(args) != 2:
            raise Exception("You can only specify two arguments")

        return self.func(*args)

Начиная с Python 3.5+:

@functools.wraps(f)
def g():
    pass

Псевдоним для g = functools.update_wrapper(g, f). Он делает ровно три вещи:

• он копирует __module__, __name__, __qualname__, __doc__, и __annotations__атрибуты fна g. Этот список по умолчанию находится в WRAPPER_ASSIGNMENTS, вы можете увидеть его в источнике functools .
• он обновляет __dict__из gвсех элементов f.__dict__. (см. WRAPPER_UPDATESв источнике)
• он устанавливает новый __wrapped__=fатрибутg

Следствием этого является то g, что оно имеет то же имя, строку документа, имя модуля и подпись, что и f. Единственная проблема заключается в том, что в отношении подписи это не совсем так: просто inspect.signatureпо умолчанию следует цепочке оберток. Вы можете проверить это с помощью, inspect.signature(g, follow_wrapped=False)как описано в документе . Это имеет неприятные последствия:

• код оболочки будет выполняться, даже если предоставленные аргументы недействительны.
• код оболочки не может легко получить доступ к аргументу, используя его имя из полученных * args, ** kwargs. Действительно, нужно обрабатывать все случаи (позиционные, ключевые слова, значения по умолчанию) и, следовательно, использовать что-то подобное Signature.bind().

Теперь существует немного путаницы между functools.wrapsдекораторами, потому что очень часто для разработки декораторов используется оболочка функций. Но оба являются совершенно независимыми понятиями. Если вам интересно понять разницу, я реализовал вспомогательные библиотеки для обоих: decopatch, чтобы легко писать декораторы, и makefun, чтобы обеспечить замену для сохранения сигнатур @wraps. Обратите внимание, что makefunопирается на тот же проверенный трюк, что и знаменитая decoratorбиблиотека.

это исходный код оберток:

WRAPPER_ASSIGNMENTS = ('__module__', '__name__', '__doc__')

WRAPPER_UPDATES = ('__dict__',)

def update_wrapper(wrapper,
                   wrapped,
                   assigned = WRAPPER_ASSIGNMENTS,
                   updated = WRAPPER_UPDATES):

    """Update a wrapper function to look like the wrapped function

       wrapper is the function to be updated
       wrapped is the original function
       assigned is a tuple naming the attributes assigned directly
       from the wrapped function to the wrapper function (defaults to
       functools.WRAPPER_ASSIGNMENTS)
       updated is a tuple naming the attributes of the wrapper that
       are updated with the corresponding attribute from the wrapped
       function (defaults to functools.WRAPPER_UPDATES)
    """
    for attr in assigned:
        setattr(wrapper, attr, getattr(wrapped, attr))
    for attr in updated:
        getattr(wrapper, attr).update(getattr(wrapped, attr, {}))
    # Return the wrapper so this can be used as a decorator via partial()
    return wrapper

def wraps(wrapped,
          assigned = WRAPPER_ASSIGNMENTS,
          updated = WRAPPER_UPDATES):
    """Decorator factory to apply update_wrapper() to a wrapper function

   Returns a decorator that invokes update_wrapper() with the decorated
   function as the wrapper argument and the arguments to wraps() as the
   remaining arguments. Default arguments are as for update_wrapper().
   This is a convenience function to simplify applying partial() to
   update_wrapper().
    """
    return partial(update_wrapper, wrapped=wrapped,
                   assigned=assigned, updated=updated)

1. Обязательное условие: Вы должны знать, как использовать декораторы, особенно с обертками. Этот комментарий объясняет это немного ясно, или эта ссылка также объясняет это довольно хорошо.

2. Всякий раз, когда мы используем For, например: @wraps, за которым следует наша собственная функция-обертка. Согласно данным, приведенным в этой ссылке , это говорит о том, что

functools.wraps - это удобная функция для вызова update_wrapper () в качестве декоратора функции при определении функции-оболочки.

Это эквивалентно частичному (update_wrapper, wrapped = wrapped, назначено = назначено, обновлено = обновлено).

Таким образом, @wraps decorator на самом деле вызывает functools.partial (func [, * args] [, ** ключевые слова]).

Определение functools.partial () говорит, что

Partical () используется для частичного применения функции, которая «замораживает» некоторую часть аргументов функции и / или ключевых слов, в результате чего создается новый объект с упрощенной подписью. Например, partal () может использоваться для создания вызываемого объекта, который ведет себя как функция int (), где базовый аргумент по умолчанию равен двум:

>>> from functools import partial
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'Convert base 2 string to an int.'
>>> basetwo('10010')
18

Что приводит меня к выводу, что @wraps вызывает функциюручный () и передает вашу функцию-обертку в качестве параметра. В конце концов функция PartAL () возвращает упрощенную версию, то есть объект того, что находится внутри функции-оболочки, а не саму функцию-оболочку.

Короче говоря, functools.wraps - это обычная функция. Давайте рассмотрим этот официальный пример . С помощью исходного кода мы можем увидеть более подробную информацию о реализации и выполняемых шагах следующим образом:

1. wraps (f) возвращает объект, скажем, O1 . Это объект класса Partial
2. Следующим шагом является @ O1 ... который является нотацией декоратора в python. Это значит

Обертка = О1 .__ вызов __ (обертка)

Проверяя реализацию __call__ , мы видим, что после этого шага (левая сторона) обертка становится объектом, результатом которого является self.func (* self.args, * args, ** newkeywords) Проверяя создание O1 в __new__ , мы знаю, что self.func - это функция update_wrapper . Он использует параметр * args , правую обертку , в качестве первого параметра. Проверяя последний шаг update_wrapper , можно увидеть, что возвращается правая оболочка с некоторыми атрибутами, измененными по мере необходимости.