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

Дополнительный уровень нужен, потому что сначала необходимо получить настройки декоратора, затем — сам декоратор, принимающий функцию, и только после этого — обёртку, вызываемую вместо исходной функции. Иными словами, декоратор с параметрами обычно состоит из фабрики настроек, функции-декоратора и wrapper-функции.

Исторический контекст

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

Дополнительный уровень вызова позволяет отделить конфигурацию от применения к конкретной функции. Это делает один механизм повторно используемым с разными настройками.

Постановка проблемы

При использовании декоратора с параметрами легко перепутать вызов фабрики настроек с вызовом обёрнутой функции. Если вернуть не функцию-декоратор, а wrapper слишком рано, Python передаст результат конфигурации не тому уровню вызовов.

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

Подробное решение

Механизм состоит из трёх этапов:

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

from functools import wraps

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

@repeat(3)
def save(value):
    return value

При определении save сначала вызывается repeat(3). Полученная функция decorator получает save и заменяет её на wrapper; при последующем вызове save выполняется именно wrapper.

Значение times доступно wrapper через замыкание. Для каждой функции, к которой применяется фабрика, создаётся собственная цепочка локальных областей, поэтому настройки разных применений не смешиваются, если состояние намеренно не вынесено в общий объект.

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

Важно различать момент декорирования и момент вызова: фабрика и функция-декоратор выполняются при создании или переопределении функции, а wrapper — при каждом вызове результата декорирования. Если конфигурация должна перечитываться динамически на каждый вызов, её нельзя бездумно вычислять только внутри фабрики.

Ситуация из практики

В сервисе нужно повторять сетевую операцию заданное число раз. Рассматривались три варианта: копировать цикл в каждом месте вызова, использовать глобальную настройку или сделать параметризованный декоратор.

Копирование цикла быстро приводит к дублированию и разным правилам обработки ошибок. Глобальная настройка проще, но плохо подходит функциям с разными лимитами и создаёт скрытую зависимость от общего состояния.

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

Что кандидаты часто упускают

Что произойдёт, если фабрика параметризованного декоратора возвращает исходную функцию вместо функции-декоратора?

При записи с параметрами результат фабрики должен быть вызываемым объектом, который примет исходную функцию. Если фабрика вернёт исходную функцию сразу, Python попытается передать эту функцию как аргумент возвращённому объекту или получит объект с неподходящей сигнатурой. Ошибка возникнет на этапе применения декоратора, потому что нарушена последовательность «настройки → принятие функции → создание обёртки».
Почему состояние, созданное фабрикой, обычно относится к одному применению декоратора?

Каждый вызов фабрики создаёт новое замыкание с собственными локальными переменными. Поэтому два применения одного параметризованного декоратора могут иметь разные лимиты, счётчики или настройки. Однако изменяемый объект, помещённый во внешнюю общую область или переданный нескольким декораторам, может стать разделяемым состоянием и вызвать взаимное влияние.
Что изменится, если настройку вычислять внутри wrapper, а не в фабрике?

Она будет вычисляться при каждом вызове функции. Это полезно для динамической конфигурации, текущего времени или данных из внешнего источника, но может добавить расходы и сделать результат нестабильным между вызовами. Если настройка постоянна для конкретной функции, вычисление в фабрике обычно дешевле и яснее; если она должна меняться без повторного декорирования, вычисление внутри wrapper оправдано.