functools.wraps
Что делает functools.wraps?
functools.wraps - это удобный интерфейс для functools.update_wrapper, который автоматически переносит ключевую метаинформацию от вызываемого объекта (функции или класса) к его обёртке. Обычно обёртка - это функция, но это может быть любой вызываемый объект, например, класс.
Помимо параметра wrapped, который принимает вызываемый объект, есть ещё два аргумента:
@functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
Параметр assigned указывает, какие атрибуты следует перенести от оригинального объекта к обёртке. Значение по умолчанию WRAPPER_ASSIGNMENTS включает следующие атрибуты:
- __module__: Имя модуля, в котором объявлен объект
- __name__: Имя объекта
- __qualname__: Подробное имя объекта
- __doc__: Строка документации объекта
Параметр updated имеет значение по умолчанию ('__dict__',), указывающее, какие атрибуты обёртки должны быть обновлены значениями от оригинального объекта. По умолчанию, атрибут __dict__ обёртки обновляется парами ключ-значение из __dict__ оригинального объекта.
Также декоратор wraps добавляет новый атрибут __wrapped__, который хранит ссылку на обёрнутую функцию или класс. Это полезно для получения метаинформации об оригинальном объекте, которую functools.wraps не переносит автоматически, например, __defaults__.
Декораторы без functools.wraps
Рассмотрим функцию с декоратором без переноса метаинформации. Пример декоратора:
def example_decorator(func):
def wrapper(*args, **kwargs):
"""Wrapper function"""
return func(*args, **kwargs)
return wrapper
@example_decorator
def hello_world(planet: str = 'earth'):
"""Say hello to a world"""
print(f"Hello, {planet}!")
print(f'{hello_world.__name__ = }')
print(f'{hello_world.__doc__ = }')
print(f'{hello_world.__annotations__ = }')
print(f'{hello_world.__dict__ = }')
Вывод:
hello_world.__name__ = 'wrapper'
hello_world.__doc__ = 'Wrapper function'
hello_world.__annotations__ = {}
hello_world.__dict__ = {}
Метаданные не были перенесены на обёртку.
Декораторы с functools.wraps
Теперь добавим functools.wraps к декоратору:
from functools import wraps
def example_decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
"""Wrapper function"""
return func(*args, **kwargs)
return wrapper
@example_decorator
def hello_world(planet: str='earth'):
"""Say hello to a world"""
print(f"Hello, {planet}!")
print(f'{hello_world.__name__ = }')
print(f'{hello_world.__doc__ = }')
print(f'{hello_world.__annotations__ = }')
print(f'{hello_world.__dict__ = }')
Вывод:
hello_world.__name__ = 'hello_world'
hello_world.__doc__ = 'Say hello to a world'
hello_world.__annotations__ = {'planet': <class 'str'>}
hello_world.__dict__ = {'__wrapped__': <function hello_world at 0x7b49d5fccc10>}
Метаинформация была успешно перенесена.
Перенос дополнительной метаинформации
Можно передавать свои аргументы для переноса дополнительной метаинформации:
MORE_WRAPPER_ASSIGNMENTS = (
'__module__', '__name__',
'__qualname__', '__annotations__',
'__doc__', '__defaults__',
'__kwdefaults__'
)
def example_decorator(func):
@wraps(func, assigned=MORE_WRAPPER_ASSIGNMENTS)
def wrapper(*args, **kwargs):
"""Wrapper function"""
return func(*args, **kwargs)
return wrapper
Теперь метаинформация о значениях по умолчанию тоже будет перенесена:
print(f'{hello_world.__defaults__ = }')
Вывод:
hello_world.__defaults__ = ('earth',)
Заключение
Перенос метаинформации при использовании декораторов важен для упрощения отладки и интеграции с другими частями языка. functools.wraps помогает автоматически перенести ключевые атрибуты, но не все, так что будьте внимательны!
