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

651

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

Эли Кортрайт
источник

Ответы:

1070

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

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'
Эли Кортрайт
источник
7
Да, я предпочитаю избегать модуля decorator, так как functools.wraps является частью стандартной библиотеки и, следовательно, не вводит другую внешнюю зависимость. Но модуль декоратора действительно решает проблему справки, которая, мы надеемся, когда-нибудь также сделает functools.wraps.
Эли Кортрайт
6
Вот пример того, что может произойти, если вы не используете обертки: тесты doctools могут внезапно исчезнуть. это потому, что doctools не может найти тесты в декорированных функциях, если что-то вроде wraps () не скопировало их.
Эндрю Кук
88
зачем нам functools.wrapsэта работа, разве она не должна быть частью шаблона декоратора? когда бы вы не хотели использовать @wraps?
Вим
56
@wim: я написал несколько декораторов, которые делают свою собственную версию для @wrapsтого, чтобы выполнять различные типы изменений или аннотаций для скопированных значений. По сути, это расширение философии Python, которое явное лучше, чем неявное, и особые случаи не достаточно особенные, чтобы нарушать правила. (Код гораздо проще, а язык легче понять, если его @wrapsнужно предоставить вручную, а не с помощью какого-либо специального механизма отказа.)
ssokolow,
35
@LucasMalor Не все декораторы оборачивают функции, которые они украшают. Некоторые применяют побочные эффекты, такие как регистрация их в какой-то поисковой системе.
Соколов
22

Я очень часто использую классы, а не функции, для своих декораторов. У меня были некоторые проблемы с этим, потому что объект не будет иметь все те же атрибуты, которые ожидаются от функции. Например, у объекта не будет атрибута __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)
мистифицировать
источник
7
Как @wrapsсказано в документации от , @wrapsэто просто удобная функция для functools.update_wrapper(). В случае декоратора класса, вы можете вызвать update_wrapper()напрямую из вашего __init__()метода. Таким образом, вам не нужно создавать DecBaseна всех, вы можете просто включить на __init__()из process_loginлинии: update_wrapper(self, func). Это все.
Фабиано
15

Начиная с 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библиотека.

smarie
источник
3

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

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)
Baliang
источник
2
  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 () возвращает упрощенную версию, то есть объект того, что находится внутри функции-оболочки, а не саму функцию-оболочку.

3rdi
источник
-4

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

Ён Ян
источник