Полезные декораторы в Python — исчерпывающий гайд

[Aladdin]

Декоратор в Python это обычная функция, которая принимает другую функцию (или класс) как аргумент, расширяет её поведение и возвращает новый вызываемый объект. Синтаксис @decorator это просто синтаксический сахар: запись @timer над функцией foo полностью эквивалентна foo = timer(foo).

def my_decorator(func):
    def wrapper(*args, **kwargs):
        print("до вызова")
        result = func(*args, **kwargs)
        print("после вызова")
        return result
    return wrapper

@my_decorator
def greet(name):
    print(f"Привет, {name}!")

# Эквивалентно: greet = my_decorator(greet)
greet("Alice")
# до вызова
# Привет, Alice!
# после вызова

Механизм работы в три шага: Python видит @decorator, вызывает decorator(func) в момент определения функции (не при вызове), сохраняет результат под тем же именем. Это важно: код декоратора вне wrapper выполняется один раз при загрузке модуля.

---

functools.wraps — первое правило декораторов

Без @wraps задекорированная функция теряет своё имя, docstring и сигнатуру. Это ломает отладку, help(), inspect, Sphinx-документацию и любые инструменты интроспекции.

from functools import wraps

def my_decorator(func):
    @wraps(func)          # копирует __name__, __doc__, __module__, __annotations__
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@my_decorator
def add(a: int, b: int) -> int:
    """Складывает два числа."""
    return a + b

print(add.__name__)   # add  (без @wraps было бы 'wrapper')
print(add.__doc__)    # Складывает два числа.

@wraps под капотом вызывает functools.update_wrapper, который копирует атрибуты __module__, __name__, __qualname__, __annotations__, __doc__ и обновляет __wrapped__, позволяя при необходимости добраться до оригинальной функции через add.__wrapped__.

---

Встроенные декораторы — стандартная библиотека

@property

Превращает метод в управляемый атрибут с геттером, сеттером и делитером. Позволяет добавить валидацию без изменения публичного API класса.

class Temperature:
    def __init__(self, celsius: float = 0):
        self._celsius = celsius

    @property
    def celsius(self) -> float:
        return self._celsius

    @celsius.setter
    def celsius(self, value: float):
        if value < -273.15:
            raise ValueError("Ниже абсолютного нуля невозможно")
        self._celsius = value

    @property
    def fahrenheit(self) -> float:
        return self._celsius * 9 / 5 + 32

t = Temperature(100)
print(t.fahrenheit)   # 212.0
t.celsius = -300      # ValueError

@staticmethod и @classmethod

@staticmethod объявляет метод, не привязанный ни к экземпляру (self), ни к классу (cls это просто функция внутри пространства имён класса. @classmethod передаёт сам класс первым аргументом, что позволяет создавать альтернативные конструкторы.

class Date:
    def __init__(self, year: int, month: int, day: int):
        self.year, self.month, self.day = year, month, day

    @classmethod
    def from_string(cls, s: str) -> "Date":
        year, month, day = map(int, s.split("-"))
        return cls(year, month, day)      # работает и в подклассах

    @staticmethod
    def is_leap_year(year: int) -> bool:
        return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)

d = Date.from_string("2024-03-15")
print(Date.is_leap_year(2024))   # True

@dataclass

Автоматически генерирует __init__, __repr__, __eq__ и, опционально, методы сравнения и хэширования. Начиная с Python 3.10 можно использовать slots=True для экономии памяти.

from dataclasses import dataclass, field

@dataclass(order=True, frozen=True)
class Point:
    x: float
    y: float
    label: str = field(default="", compare=False)

p1 = Point(1.0, 2.0, "A")
p2 = Point(3.0, 4.0, "B")
print(p1 < p2)    # True (сравнивает x, затем y)
# p1.x = 5.0     # FrozenInstanceError, т.к. frozen=True

Параметры eq, order, frozen, slots, kw_only (3.10+) и match_args (3.10+) позволяют точно настроить поведение.

@abstractmethod

Из модуля abc. Помечает метод как абстрактный: класс, содержащий хотя бы один такой метод, нельзя инстанциировать. Подкласс обязан переопределить все абстрактные методы.

from abc import ABC, abstractmethod

class Shape(ABC):
    @abstractmethod
    def area(self) -> float: ...

    @abstractmethod
    def perimeter(self) -> float: ...

class Circle(Shape):
    def __init__(self, r: float):
        self.r = r
    def area(self) -> float:
        return 3.14159 * self.r ** 2
    def perimeter(self) -> float:
        return 2 * 3.14159 * self.r

# Shape()    # TypeError: Can't instantiate abstract class
c = Circle(5)

@cached_property

Добавлен в Python 3.8. Вычисляет значение при первом обращении, кэширует его в __dict__ экземпляра и больше не вызывает getter. В отличие от @property нет лишнего вызова при каждом обращении.

from functools import cached_property
import statistics

class Dataset:
    def __init__(self, data: list[float]):
        self._data = data

    @cached_property
    def stats(self) -> dict:
        print("вычисляем...")   # выполнится только один раз
        return {
            "mean": statistics.mean(self._data),
            "stdev": statistics.stdev(self._data),
        }

ds = Dataset([1, 2, 3, 4, 5])
print(ds.stats)   # вычисляем...  {'mean': 3, 'stdev': 1.58...}
print(ds.stats)   # из кэша, без "вычисляем..."

Важно: не работает с __slots__ и не потокобезопасен без внешней блокировки.

@override (Python 3.12+)

Из модуля typing. Сигнализирует тайп-чекеру, что метод переопределяет родительский. Если в родителе метод переименовали или удалили, тайп-чекер выдаст ошибку.

from typing import override

class Base:
    def process(self, data: str) -> str:
        return data.upper()

class Child(Base):
    @override
    def process(self, data: str) -> str:   # ошибка, если в Base нет process
        return data.lower()

@deprecated (Python 3.13+)

Из модуля warnings. Помечает функцию или класс как устаревший: при вызове автоматически выдаётся DeprecationWarning, а тайп-чекеры отображают предупреждение.

from warnings import deprecated

@deprecated("Используйте new_api() вместо этого")
def old_api():
    return 42

old_api()   # DeprecationWarning: Используйте new_api() вместо этого

---

functools — арсенал высшего порядка

@lru_cache и @cache

@lru_cache(maxsize=N) кэширует результаты функции по аргументам (мемоизация), выбрасывая наименее использованные записи при достижении лимита. @cache (Python 3.9+) это @lru_cache(maxsize=None) без ограничения размера.

from functools import lru_cache, cache

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

print(fibonacci(50))               # мгновенно
print(fibonacci.cache_info())      # CacheInfo(hits=48, misses=51, maxsize=128, currsize=51)
fibonacci.cache_clear()            # сбросить кэш

# Для чистых функций без ограничения размера:
@cache
def factorial(n: int) -> int:
    return n * factorial(n - 1) if n else 1

Аргументы должны быть хэшируемыми. Список, словарь или другой изменяемый тип вызовет TypeError. Для методов экземпляра лучше использовать @cached_property или явно кэшировать через словарь.

@singledispatch

Реализует перегрузку функций по типу первого аргумента (single dispatch, аналог pattern matching по типу).

from functools import singledispatch

@singledispatch
def process(value):
    raise TypeError(f"Неподдерживаемый тип: {type(value)}")

@process.register(int)
def _(value: int) -> str:
    return f"Целое: {value * 2}"

@process.register(str)
def _(value: str) -> str:
    return f"Строка: {value.upper()}"

@process.register(list)
@process.register(tuple)
def _(value) -> str:
    return f"Последовательность длиной {len(value)}"

print(process(5))           # Целое: 10
print(process("hello"))     # Строка: HELLO
print(process([1, 2, 3]))   # Последовательность длиной 3

Для методов классов используется functools.singledispatchmethod (Python 3.8+).

@total_ordering

Если определить __eq__ и один из методов сравнения (__lt__, __le__, __gt__, __ge__), @total_ordering автоматически выведет остальные три.

from functools import total_ordering

@total_ordering
class Version:
    def __init__(self, major: int, minor: int, patch: int):
        self.v = (major, minor, patch)

    def __eq__(self, other) -> bool:
        return self.v == other.v

    def __lt__(self, other) -> bool:
        return self.v < other.v

v1 = Version(1, 2, 3)
v2 = Version(2, 0, 0)
print(v1 < v2)    # True
print(v1 >= v2)   # False (сгенерировано @total_ordering)
print(v2 > v1)    # True  (сгенерировано @total_ordering)

---

Декораторы с параметрами

Чтобы передать аргументы в декоратор, нужен ещё один уровень вложенности: функция, возвращающая декоратор.

from functools import wraps
import time

def retry(max_attempts: int = 3, delay: float = 1.0, exceptions=(Exception,)):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            last_exc = None
            for attempt in range(1, max_attempts + 1):
                try:
                    return func(*args, **kwargs)
                except exceptions as e:
                    last_exc = e
                    print(f"Попытка {attempt}/{max_attempts} не удалась: {e}")
                    if attempt < max_attempts:
                        time.sleep(delay)
            raise last_exc
        return wrapper
    return decorator

@retry(max_attempts=3, delay=0.5, exceptions=(ConnectionError,))
def fetch_data(url: str) -> str:
    # симулируем нестабильное соединение
    import random
    if random.random() < 0.7:
        raise ConnectionError("Нет соединения")
    return "data"

Начиная с Python 3.8 можно сделать декоратор, работающий как с аргументами (@retry(3)), так и без (@retry), через параметр func=None и позиционно-ключевые аргументы:

def retry(_func=None, *, max_attempts: int = 3):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for _ in range(max_attempts):
                try:
                    return func(*args, **kwargs)
                except Exception:
                    pass
            raise RuntimeError("Все попытки исчерпаны")
        return wrapper

    if _func is not None:   # вызов без скобок: @retry
        return decorator(_func)
    return decorator        # вызов со скобками: @retry(max_attempts=5)

---

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

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

from functools import wraps

def bold(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return f"<b>{func(*args, **kwargs)}</b>"
    return wrapper

def italic(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return f"<i>{func(*args, **kwargs)}</i>"
    return wrapper

@bold
@italic
def greet(name: str) -> str:
    return f"Привет, {name}!"

# Эквивалентно: greet = bold(italic(greet))
print(greet("Alice"))   # <b><i>Привет, Alice!</i></b>

Порядок имеет значение. @bold @italic дают <b><i>...</i></b>, тогда как @italic @bold дадут <i><b>...</b></i>.

---

Декораторы классов

Декоратор может быть не только функцией, но и классом. В таком случае __call__ становится телом обёртки, а __init__ получает декорируемую функцию.

from functools import wraps, update_wrapper
import time

class Timer:
    """Декоратор-класс: замеряет время выполнения."""

    def __init__(self, func):
        self.func = func
        self.total_time = 0.0
        self.call_count = 0
        update_wrapper(self, func)  # аналог @wraps для классов

    def __call__(self, *args, **kwargs):
        start = time.perf_counter()
        result = self.func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        self.total_time += elapsed
        self.call_count += 1
        print(f"{self.func.__name__}: {elapsed:.4f}с")
        return result

    def stats(self):
        avg = self.total_time / self.call_count if self.call_count else 0
        return {"total": self.total_time, "calls": self.call_count, "avg": avg}

@Timer
def slow_sum(n: int) -> int:
    return sum(range(n))

slow_sum(1_000_000)
slow_sum(500_000)
print(slow_sum.stats())

Декоратор-класс удобен, когда нужно хранить состояние между вызовами (счётчик, накопленное время, кэш).

---

Применение декоратора к классу целиком

Декоратор можно применить и к классу: Python передаёт объект класса, а не функции.

def add_repr(cls):
    """Добавляет __repr__, если его нет."""
    if "__repr__" not in cls.__dict__:
        def __repr__(self):
            attrs = ", ".join(
                f"{k}={v!r}" for k, v in self.__dict__.items()
            )
            return f"{cls.__name__}({attrs})"
        cls.__repr__ = __repr__
    return cls

@add_repr
class Config:
    def __init__(self, host: str, port: int):
        self.host = host
        self.port = port

print(Config("localhost", 8080))   # Config(host='localhost', port=8080)

---

Практические паттерны

Логирование

import logging
from functools import wraps

def log_calls(logger=None, level=logging.DEBUG):
    _logger = logger or logging.getLogger(__name__)
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            _logger.log(level, "Вызов %s args=%s kwargs=%s", func.__name__, args, kwargs)
            try:
                result = func(*args, **kwargs)
                _logger.log(level, "%s вернул %r", func.__name__, result)
                return result
            except Exception as exc:
                _logger.exception("%s выбросил %s", func.__name__, exc)
                raise
        return wrapper
    return decorator

logging.basicConfig(level=logging.DEBUG)

@log_calls()
def divide(a: float, b: float) -> float:
    return a / b

Rate Limiter

import time
from collections import deque
from functools import wraps

def rate_limit(calls: int, period: float):
    """Не более `calls` вызовов за `period` секунд."""
    def decorator(func):
        timestamps: deque = deque()
        @wraps(func)
        def wrapper(*args, **kwargs):
            now = time.monotonic()
            while timestamps and now - timestamps >= period:
                timestamps.popleft()
            if len(timestamps) >= calls:
                sleep_for = period - (now - timestamps)
                time.sleep(sleep_for)
            timestamps.append(time.monotonic())
            return func(*args, **kwargs)
        return wrapper
    return decorator

@rate_limit(calls=5, period=1.0)
def call_api(endpoint: str) -> dict:
    return {"endpoint": endpoint, "ok": True}

Singleton

from functools import wraps
import threading

def singleton(cls):
    instances = {}
    lock = threading.Lock()

    @wraps(cls, updated=[])
    def get_instance(*args, **kwargs):
        if cls not in instances:
            with lock:
                if cls not in instances:  # double-checked locking
                    instances[cls] = cls(*args, **kwargs)
        return instances[cls]

    return get_instance

@singleton
class DatabasePool:
    def __init__(self, dsn: str = "sqlite:///:memory:"):
        self.dsn = dsn
        print(f"Создан пул: {dsn}")

a = DatabasePool("postgresql://localhost/db")
b = DatabasePool()   # "Создан пул" не печатается второй раз
print(a is b)        # True

Валидация типов

import inspect
from functools import wraps

def validate_types(func):
    sig = inspect.signature(func)
    hints = func.__annotations__

    @wraps(func)
    def wrapper(*args, **kwargs):
        bound = sig.bind(*args, **kwargs)
        bound.apply_defaults()
        for name, value in bound.arguments.items():
            if name in hints and name != "return":
                expected = hints[name]
                if not isinstance(value, expected):
                    raise TypeError(
                        f"Параметр '{name}': ожидался {expected.__name__}, "
                        f"получен {type(value).__name__}"
                    )
        return func(*args, **kwargs)
    return wrapper

@validate_types
def power(base: float, exp: int) -> float:
    return base ** exp

power(2.0, 3)    # OK
power(2.0, 3.5)  # TypeError: Параметр 'exp': ожидался int, получен float

---

Асинхронные декораторы

Декоратор не знает заранее, синхронная функция или async. Для универсального декоратора нужно проверять это явно.

import asyncio
import time
import inspect
from functools import wraps

def timeit(func):
    @wraps(func)
    async def async_wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = await func(*args, **kwargs)
        print(f"{func.__name__}: {time.perf_counter() - start:.4f}с (async)")
        return result

    @wraps(func)
    def sync_wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        print(f"{func.__name__}: {time.perf_counter() - start:.4f}с (sync)")
        return result

    # Выбираем обёртку один раз при декорировании (не при каждом вызове)
    return async_wrapper if inspect.iscoroutinefunction(func) else sync_wrapper

@timeit
def cpu_task(n: int) -> int:
    return sum(range(n))

@timeit
async def io_task(delay: float) -> str:
    await asyncio.sleep(delay)
    return "done"

cpu_task(10_000_000)
asyncio.run(io_task(0.1))

Проверка inspect.iscoroutinefunction выполняется один раз при декорировании, а не при каждом вызове, что исключает лишние расходы в рантайме.

---

Декораторы в контексте Python 3.13 и 3.14

В Python 3.13 появился @typing.deprecated для явной пометки устаревшего кода прямо в системе типов. В Python 3.14 аннотации стали отложенными (PEP 649): они не вычисляются при определении функции. Это означает, что декораторы, читающие func.__annotations__ напрямую (например, validate_types выше), теперь получат объект AnnotateFunc, а не уже вычисленный словарь. Для надёжной работы с аннотациями используйте inspect.get_annotations(func, eval_str=True):

import inspect

def validate_types(func):
    sig = inspect.signature(func)
    # eval_str=True вычисляет строковые аннотации и отложенные (3.14+)
    hints = inspect.get_annotations(func, eval_str=True)
    ...

---

Шпаргалка — когда что использовать

Задача	Декоратор
Управляемый атрибут	@property
Метод без self/cls	@staticmethod
Альтернативный конструктор	@classmethod
Автогенерация boilerplate	@dataclass
Абстрактный интерфейс	@abstractmethod
Ленивое кэширование атрибута	@cached_property
Мемоизация чистых функций	@lru_cache / @cache
Перегрузка по типу	@singledispatch
Вывод методов сравнения	@total_ordering
Пометить как устаревший	@deprecated (3.13+)
Явное переопределение метода	@override (3.12+)
Сохранить метаданные функции	@wraps

---

Полезные источники

• Официальная документация functools — docs.python.org/3/library/functools.html
• “What’s New In Python 3.13” — docs.python.org/3/whatsnew/3.13.html (про @deprecated, @override)
• “What’s New In Python 3.14” — docs.python.org/3/whatsnew/3.14.html (про отложенные аннотации PEP 649)
• Real Python — Primer on Python Decorators — realpython.com/primer-on-python-decorators/
• freeCodeCamp — The Python Decorator Handbook — freecodecamp.org/news/the-python-decorator-handbook/
• asyncmove.com — The Comprehensive Guide to Python Decorators (2026) — asyncmove.com/blog/2026/01/the-comprehensive-guide-to-python-decorators/
• PEP 318 — декораторы функций и методов
• PEP 614 — расслабление грамматических ограничений на декораторы (3.9+)
• PEP 649 — отложенные аннотации (3.14)

---

References

1. Fancy Decorators - In this tutorial, you’ll look at what Python decorators are and how you define and use them. Decorat…

2. The Python Decorator Handbook - freeCodeCamp - Python decorators provide an easy yet powerful syntax for modifying and extending the behavior of fu…

3. functools — Higher-order functions and operations on callable … - The functools module is for higher-order functions: functions that act on or return other functions…

4. Python Standard Library | collections | itertools | functools - Dev Genius - Python’s functools module, part of the standard library, provides higher-order functions and operati…

5. Handy Python Decorators. Implementing and Using Advanced… - The Python Standard Library contains four incredibly useful decorators: staticmethod , classmethod ,…

6. What’s New In Python 3.13 — Python 3.14.4 documentation - The biggest changes include a new interactive interpreter, experimental support for running in a fre…

7. What’s New In Python 3.13 — Python 3.14.0rc3 documentation - Editors, Adam Turner and Thomas Wouters,. This article explains the new features in Python 3.13, com…

8. Mastering Python Decorators for Code Reusability and Optimization - Discover how Python decorators can help you write reusable, efficient, and maintainable code by modi…

9. The Comprehensive Guide to Python Decorators - Decorators are one of Python’s most powerful metaprogramming tools, widely used in the industry to w…

10. What’s new in Python 3.14 — Python 3.14.4 documentation - This article explains the new features in Python 3.14, compared to 3.13. … no_type_check_decorator…