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

Question

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

Answer 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 не имеет строки документации, и поэтому записанной вами строки документации больше не будет. Кроме того, если вы посмотрите на результат 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'

Answer 2

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

Answer 3

1. Предположим, у нас есть это: простой декоратор, который берет вывод функции и помещает его в строку, за которой следуют три !!!!.

      def mydeco(func):
    def wrapper(*args, **kwargs):
        return f'{func(*args, **kwargs)}!!!'
    return wrapper

2. Давайте теперь украсим две разные функции с помощью «mydeco»:

      @mydeco
def add(a, b):
    '''Add two objects together, the long way'''
    return a + b

@mydeco
def mysum(*args):
    '''Sum any numbers together, the long way'''
    total = 0
    for one_item in args:
        total += one_item
    return total

3. при запуске add(10,20), mysum(1,2,3,4) это сработало!

      >>> add(10,20)
'30!!!'

>>> mysum(1,2,3,4)
'10!!!!'

4. Однако атрибут name , который дает нам имя функции, когда мы ее определяем,

      >>>add.__name__
'wrapper`

>>>mysum.__name__
'wrapper'

5. Худший

      >>> help(add)
Help on function wrapper in module __main__:
wrapper(*args, **kwargs)

>>> help(mysum)
Help on function wrapper in module __main__:
wrapper(*args, **kwargs)

6. мы можем исправить частично:

      def mydeco(func):
    def wrapper(*args, **kwargs):
        return f'{func(*args, **kwargs)}!!!'
    wrapper.__name__ = func.__name__
    wrapper.__doc__ = func.__doc__
    return wrapper

7. теперь мы снова выполняем шаг 5 (второй раз):

      >>> help(add)
Help on function add in module __main__:

add(*args, **kwargs)
     Add two objects together, the long way

>>> help(mysum)
Help on function mysum in module __main__:

mysum(*args, **kwargs)
    Sum any numbers together, the long way

8. но мы можем использовать functools.wraps (инструмент decotator)

      from functools import wraps

def mydeco(func):
    @wraps(func)
    def wrapper(*args, *kwargs):
        return f'{func(*args, **kwargs)}!!!'
    return wrapper

9. теперь выполните шаг 5 (3-й раз) снова

      >>> help(add)
Help on function add in module main:
add(a, b)
     Add two objects together, the long way

>>> help(mysum)
Help on function mysum in module main:
mysum(*args)
     Sum any numbers together, the long way

Ссылка

Answer 4

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

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

Answer 6

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

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)

Answer 7

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