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

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

Ответ 1

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

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 не имеет строки документации, и поэтому with_logging документации больше не будет там. Кроме того, если вы посмотрите на результат pydoc для этой функции, он не будет указан как принимающий один аргумент x; вместо этого он будет указан как *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'

Ответ 2

Я очень часто использую классы, а не функции, для моих декораторов. У меня были некоторые проблемы с этим, потому что у объекта не будет одинаковых атрибутов, ожидаемых от функции. Например, у объекта не будет атрибута __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)

Ответ 3

По состоянию на питоне 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 путаница между functools.wraps и декораторами, потому что очень частый вариант использования для разработки декораторов - это обертывание функций. Но оба являются совершенно независимыми понятиями. Если вам интересно понять разницу, я реализовал вспомогательные библиотеки для обоих: decopatch, чтобы легко писать декораторы, и makefun, чтобы обеспечить замену @wraps сохранением @wraps. Обратите внимание, что makefun использует тот же проверенный прием, что и знаменитая библиотека decorator.

Ответ 4

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

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)

Ответ 5

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

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

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

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

Поэтому декоратор @wraps на самом деле вызывает 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 вызывает функциюручный() и передает вашу функцию-обертку в качестве параметра. В конце функция Part() возвращает упрощенную версию, то есть объект объекта внутри функции оболочки, а не саму функцию оболочки.

Ответ 6

Короче говоря, 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, правую обертку, в качестве своего 1-го параметра. Проверяя последний шаг update_wrapper, можно увидеть, что возвращается правая оболочка с некоторыми атрибутами, измененными по мере необходимости.