Зачем нужен functools.wraps при написании декораторов?

Короткий ответ

functools.wraps — декоратор из стандартного модуля functools, который применяется к функции-обёртке внутри декоратора. Он копирует обёртке метаданные декорируемой функции, чтобы она сохраняла её имя, документацию и другие атрибуты.

Как это работает подробнее

• Проблема. Без wraps обёртка затирает метаданные: имя функции становится wrapper, пропадают __doc__, __module__ и другие атрибуты.
• Последствия. В стектрейсах и ошибках фигурирует внутренняя обёртка вместо реальной функции, что ломает интроспекцию, документаторы и инструменты.
• Решение. @wraps(func) копирует обёртке атрибуты декорируемой функции и обновляет её словарь __dict__, поэтому обёртка «выдаёт себя» за исходную функцию.
• Правило. Хорошим тоном считается всегда оборачивать wrapper в @wraps(func) при написании собственных декораторов.

Пример кода

Декоратор logged с сохранением метаданныхКопировать

from functools import wraps
def logged(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        print(f'Вызов {func.__name__}')
        return func(*args, **kwargs)
    return wrapper
@logged
def add(a, b):
    """Складывает два числа."""
    return a + b
print(add.__name__)   # 'add', а не 'wrapper'
print(add.__doc__)    # 'Складывает два числа.'

Что использовать на практике

• Каждый декоратор. Применяй @wraps(func) к обёртке во всех собственных декораторах — это просто и безопасно.
• Отладка. Сохранённые __name__ и __doc__ делают стектрейсы, логи и справку читаемыми.
• Интроспекция. Документаторы и профилировщики корректно работают, когда метаданные функций не потеряны.