Декораторы в Python: @-функции, аргументы и functools.wraps

Декоратор - это функция, которая оборачивает функцию

Фраза звучит абстрактно, но механика простая. Декоратор принимает функцию и возвращает функцию. Возвращённая обычно вызывает исходную, накручивая сверху дополнительное поведение.

Самый короткий пример:

def shout(func):
    def wrapper():
        result = func()
        return result.upper()
    return wrapper

def greet():
    return "hello"

greet = shout(greet)
print(greet())

shout - декоратор. Он принимает функцию (greet), строит новую функцию (wrapper), которая вызывает оригинал и повышает регистр результата, и возвращает её. Переприсваивание greet = shout(greet) подменяет оригинал на обёрнутую версию.

Этот паттерн переприсваивания настолько частый, что Python дал ему отдельный синтаксис.

@ - сахар для переприсваивания

@name строкой выше def эквивалентно name = name(...) сразу после определения функции:

def shout(func):
    def wrapper():
        return func().upper()
    return wrapper

@shout
def greet():
    return "hello"

print(greet())

@shout читается как «примени декоратор shout к этой функции». Python запускает greet = shout(greet) сразу после def - та же механика, меньше набора.

Как увидишь @name - мысленно заменяй на function = name(function). Это всё, что означает синтаксис.

Обработка аргументов

У большинства функций есть аргументы. Пригодный декоратор пробрасывает их дальше. Идиома - *args, **kwargs, способ Python принять любые аргументы: обёртке не должно быть важно, что ждёт обёрнутая функция:

def shout(func):
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result.upper()
    return wrapper

@shout
def greet(name, punctuation="!"):
    return f"hello, {name}{punctuation}"

print(greet("rosa"))
print(greet("boris", punctuation="."))

*args забирает все позиционные аргументы. **kwargs - все keyword-аргументы. Обёртка пробрасывает всё в обёрнутую функцию без изменений и делает дополнительную работу, ради которой декоратор и нужен, - здесь поднимает регистр результата.

Такую форму принимает большинство реальных декораторов.

Более полезный пример: тайминг

Выводим, сколько занимает функция:

import time

def timed(func):
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} took {elapsed*1000:.2f} ms")
        return result
    return wrapper

@timed
def slow_sum(n):
    total = 0
    for i in range(n):
        total += i
    return total

print(slow_sum(1_000_000))
print(slow_sum(5_000_000))

Паттерн - «запустить что-то до вызова, запустить что-то после» - то, чем в итоге занимается большинство декораторов. Логирование, проверки авторизации, повторы и валидация - одной формы.

Сохраняем оригинал: functools.wraps

Декорирование функции её заменяет, и обёрнутая функция теряет исходные атрибуты __name__ и __doc__:

def shout(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs).upper()
    return wrapper

@shout
def greet(name):
    """Return a personalised greeting."""
    return f"hello, {name}"

print(greet.__name__)
print(greet.__doc__)

greet.__name__ теперь "wrapper", docstring исчез. Это ломает help(), трейсбэки и любые инструменты, инспектирующие функцию.

Ремонт - одна строка: @functools.wraps(func) на внутренней функции копирует метаданные.

from functools import wraps

def shout(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs).upper()
    return wrapper

@shout
def greet(name):
    """Return a personalised greeting."""
    return f"hello, {name}"

print(greet.__name__)
print(greet.__doc__)

Всегда ставь @wraps(func) на внутреннюю функцию. Это ничего не стоит и избавляет от удивлённых отладочных сессий позже.

Декораторы с аргументами

Иногда самому декоратору нужна настройка - «повтори функцию до 3 раз», «логируй на уровне DEBUG». Это ещё один слой вложенности: внешняя функция принимает аргументы и возвращает декоратор.

from functools import wraps

def repeat(times):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for _ in range(times):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

@repeat(times=3)
def say_hi(name):
    print(f"Hi, {name}")

say_hi("Rosa")

Три слоя звучит как много. Читай изнутри наружу:

1. repeat(times=3) - вызов функции. Возвращает decorator.
2. decorator - собственно декоратор, принимает функцию и возвращает обёрнутую.
3. wrapper - обёрнутая функция, работающая в момент вызова.

Эта форма лежит в основе @retry(times=5), @cache(maxsize=100) и фреймворковых декораторов вроде @app.route("/users"). Как увидел трёхслойный паттерн - вся семья читается одинаково.

Стекинг декораторов

К функции можно применить несколько декораторов. Они стекаются снизу вверх: ближайший к def срабатывает первым:

from functools import wraps

def add_exclaim(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs) + "!"
    return wrapper

def shout(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs).upper()
    return wrapper

@shout
@add_exclaim
def greet(name):
    return f"hi, {name}"

print(greet("rosa"))

Сначала оборачивает add_exclaim, прибавляя !. Потом сверху - shout, повышающий регистр. Вывод - HI, ROSA!.

Порядок важен. Если стек перевернуть, восклицательный знак добавится после повышения регистра - визуально здесь то же самое, но представь декоратор, форматирующий JSON: выполнить его до или после декоратора, логирующего вход, даст совсем разные результаты.

Встроенные декораторы, которые встретишь

У Python и его стандартной библиотеки есть декораторы, с которыми ты встретишься в реальном коде:

from functools import lru_cache

class Circle:
    def __init__(self, radius):
        self.radius = radius

    @property
    def area(self):
        return 3.14159 * self.radius ** 2

    @staticmethod
    def unit_circle_area():
        return 3.14159

    @classmethod
    def from_diameter(cls, diameter):
        return cls(diameter / 2)

@lru_cache(maxsize=128)
def fib(n):
    if n < 2:
        return n
    return fib(n - 1) + fib(n - 2)

c = Circle(5)
print(c.area)
print(Circle.unit_circle_area())
print(Circle.from_diameter(10).radius)
print(fib(50))

• @property превращает метод в вычисляемый атрибут.
• @staticmethod помечает метод, не использующий self или cls.
• @classmethod получает класс как cls вместо экземпляра - отлично для альтернативных конструкторов.
• @functools.lru_cache мемоизирует результаты, и повторные вызовы с теми же аргументами попадают в кэш.

Фреймворковые декораторы (@app.route, @pytest.fixture, @dataclass) работают по той же механике. Ничего особенного - просто функции, оборачивающие функции.

Когда писать, а когда не писать

Пиши декоратор, когда хочешь применить одно и то же поведение к многим функциям - тайминг, логирование, повторы, проверки доступа. Смысл в том, чтобы держать это поведение вне тела функции.

Пропусти декоратор, когда:

• Поведение принадлежит одной конкретной функции. Положи его в функцию.
• Нужен только для тестирования. Фикстура или параметр понятнее.
• Тянет настакать их четыре-пять. В этот момент управление потоком прячется в цепочке декораторов - читателю придётся разматывать каждый слой, чтобы увидеть, что реально выполняется. Простой хелпер читается лучше.

Декораторы - острый инструмент. Используется хорошо - код сухой, намерение очевидное. Плохо - код скрывает, что делает. Склоняйся к «очевидному», когда решаешь, тянуться ли.

Дальше: аннотации типов

Декораторы - частое место, где встречаешь type hints в дикой природе: функции wrapper часто аннотируют свои сигнатуры. Type hints - маленькая фича, которая быстро окупается, и она на следующей странице.