Типизация декораторов: почему проверяющий замолкает и чем это лечится

Два неверных вызова, ноль ошибок

Вот декоратор, написанный так, как его пишут чаще всего:

def add_logging(f: Callable[..., R]) -> Callable[..., R]:
    def inner(*args: object, **kwargs: object) -> R:
        return f(*args, **kwargs)
 
    return inner
 
 
@add_logging
def takes_int_str(x: int, y: str) -> int:
    return x + 7

Под ним три вызова, из которых два заведомо неверны: takes_int_str(1, "A"), takes_int_str("B", 2) — типы переставлены, и takes_int_str() — аргументов нет вовсе.

Проверяющий типов — mypy — не находит ни одного. Ноль ошибок, код возврата ноль.

Дело в многоточии

«... значит любые аргументы» — объяснение, которое звучит безобидно. PEP 612 формулирует иначе: многоточие вместо типов параметров означает, что проверки аргументов не выполняется вовсе.

Разница между «подойдёт любой» и «не проверяем» — это и есть разница между безобидной формулировкой и тремя пропущенными вызовами. Проверяющий сделал ровно то, что ему сказали. Сказали неудачно.

ParamSpec: та же функция, три ошибки

def add_logging[**P, R](f: Callable[P, R]) -> Callable[P, R]:
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        return f(*args, **kwargs)
 
    return inner

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

P.args и P.kwargs пишутся только парой. Причина не в удобстве записи: один и тот же набор параметров разные вызовы раскладывают по-разному — f(1, y=2) кладёт двойку в kwargs, а f(1, 2) — в args. Половина пары описывала бы не все случаи, и оба проверяющих такую запись отвергают.

Рантайм честен, проверяющий слеп

Самое неожиданное здесь — что в рантайме сигнатура никуда не делась:

inspect.signature(takes_int_str)                       -> (x: int, y: str) -> int
inspect.signature(takes_int_str, follow_wrapped=False) -> (*args, **kwargs) -> int

Вторая строка — правда: вызовут функцию, принимающую *args, **kwargs. Первая — то, что показывает inspect по умолчанию, потому что functools.wraps оставил на обёртке ссылку на обёрнутое, а signature по этой ссылке прыгает.

Отсюда и уверенность, что «wraps всё чинит». Он чинит help() и интроспекцию. Проверяющему он не говорит ничего.

Где ошибаются почти все

Декоратор, умеющий обе формы — @trace и @trace(level=2), — пишут парой перегрузок, и выглядит она безупречно. Измерено:

Вторая строка — потеря, и потеря молчаливая: неверный вызов такой функции просто не подчёркивается.

Причина в том, что фабрика обязана вернуть один тип, а ParamSpec должен связываться заново на каждом применении декоратора. Лечится тем, что фабрика возвращает не Callable, а протокол с обобщённым __call__:

class _Deco(Protocol):
    def __call__[**P, R](self, f: Callable[P, R], /) -> Callable[P, R]: ...

После этого обе формы дают одну и ту же сигнатуру.

Чем измерено

Все примеры лежат целыми файлами в bench/typing/: от bench/typing/01_naive.py до bench/typing/07_args_kwargs_pair.py, плюс bench/typing/version_matrix.py для матрицы версий. Проверяющих два — mypy 2.3.1 и pyright 1.1.413 под CPython 3.13.7, — и на всех файлах они сошлись.

Вывод любого из них — наблюдение, а не источник: первична спецификация системы типов, и там, где выше сказано «правило», за ним стоит она или PEP.

Ноль ошибок на двух неверных вызовах

Начнём с замера, а не с объяснения. Вот обычный декоратор, написанный так, как его пишут чаще всего:

def add_logging(f: Callable[..., R]) -> Callable[..., R]:
    def inner(*args: object, **kwargs: object) -> R:
        return f(*args, **kwargs)
 
    return inner
 
 
@add_logging
def takes_int_str(x: int, y: str) -> int:
    return x + 7

И три вызова под ним, из которых два заведомо неверны:

takes_int_str(1, "A")  # верный вызов
takes_int_str("B", 2)  # типы переставлены
takes_int_str()  # аргументов нет вовсе

Проверяющий типов — mypy 2.3.1 — не находит ни одного. Файл целиком — bench/typing/01_naive.py, вывод дословно:

$ mypy 01_naive.py
  -> exit=0

Ни ошибки, ни предупреждения, код возврата ноль. Второй проверяющий, pyright 1.1.413, на том же файле тоже молчит.

Что означает многоточие

Обычное объяснение — «... значит любые аргументы» — звучит безобидно и поэтому не настораживает. Документация typing формулирует именно так:

Про то, что происходит с проверкой ВЫЗОВОВ такого объекта, здесь не сказано ничего. А сказано это в PEP 612, и совсем в других словах:

Разница между «подойдёт любой» и «не проверяем» — это и есть разница между безобидной формулировкой и тремя пропущенными вызовами. Спецификация системы типов говорит то же самое строже: This is a gradual form indicating that the type is consistent with any input signature (Это градуальная форма, указывающая, что данный тип совместим с любой входной сигнатурой). Градуальная форма — это место, где проверка сознательно отключается.

Заметьте, чего в этом объяснении нет: слова «баг». Проверяющий сделал ровно то, что ему сказали. Сказали неудачно.

ParamSpec: то же самое, три ошибки

PEP 612 существует ровно затем, чтобы это чинить. Постановка задачи в нём — про декораторы прямым текстом:

Тот же декоратор, переписанный через ParamSpec в синтаксисе PEP 695:

def add_logging[**P, R](f: Callable[P, R]) -> Callable[P, R]:
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        return f(*args, **kwargs)
 
    return inner

Тело декоратора не изменилось. Вызовы не изменились. Файл вызовов тот же самый. Изменилась одна строка — объявление. Вывод (bench/typing/02_paramspec.py):

02_paramspec.py:22: error: Argument 1 to "takes_int_str" has incompatible type "str"; expected "int"  [arg-type]
02_paramspec.py:22: error: Argument 2 to "takes_int_str" has incompatible type "int"; expected "str"  [arg-type]
02_paramspec.py:23: error: Missing positional arguments "x", "y" in call to "takes_int_str"  [call-arg]

Три ошибки на тех же двух строках — две по типам и одна по числу аргументов. pyright находит те же три, другими словами. Вся статья, в сущности, сводится к этой паре прогонов: ... — не «любые аргументы», а «не проверять».

Почему P.args и P.kwargs только парой

Первое, обо что спотыкаются, — попытка написать половину:

def half[**P, R](f: Callable[P, R]) -> Callable[P, R]:
    def inner(*args: P.args) -> R:  # ошибка: половина пары
        return f(*args)
 
    return inner

Оба проверяющих отказываются, каждый своими словами (bench/typing/07_args_kwargs_pair.py):

07_args_kwargs_pair.py:26: error: ParamSpec must have "*args" typed as "P.args" and "**kwargs" typed as "P.kwargs"  [valid-type]

И следом ещё две, на строках 27 и 29: вызов остался без параметров, а результат перестал подходить под объявленный тип. Второй проверяющий отказывается на тех же трёх строках и называет правило прямее:

07_args_kwargs_pair.py:26: "args" and "kwargs" attributes of ParamSpec must both appear within a function signature

Причина названа в PEP, и она не про удобство записи:

Дальше — то, ради чего это ограничение и введено. Один и тот же набор параметров разные вызовы раскладывают по-разному: f(1, y=2) кладёт единицу в args, двойку в kwargs, а f(1, 2) — обе в args.

То есть пара — не синтаксическая формальность, а единственный способ описать «те же самые параметры», не зная заранее, как их разложит вызывающий.

Рантайм честен, проверяющий слеп

Здесь начинается то, чего почти нигде не пишут, и оно переворачивает привычную картину.

Пока проверяющий молчал, в рантайме сигнатура никуда не делась. Измерено на 3.12.3, 3.13.7 и 3.14.7 — на всех трёх одинаково:

inspect.signature(takes_int_str)                       -> (x: int, y: str) -> int
inspect.signature(takes_int_str, follow_wrapped=False) -> (*args, **kwargs) -> int
takes_int_str.__code__.co_varnames                     -> ('args', 'kwargs')

Читать это надо снизу вверх. Последняя строка — правда: под декоратором стоит функция, принимающая *args, **kwargs, и вызывать будут именно её. Средняя строка — та же правда, сказанная inspect, когда его просят не прыгать. А верхняя — то, что inspect показывает по умолчанию.

Прыжок возможен из-за functools.wraps — сам механизм разобран в статье про декораторы, здесь он берётся готовым. wraps ставит на обёртку ссылку на обёрнутое (wrapper.__wrapped__ = wrapped, Lib/functools.py:62 на 3.13.7), а inspect.signature объявлен так, что по этой ссылке идёт: def signature(obj, *, follow_wrapped=True, ...) (Lib/inspect.py:3373).

Отсюда и берётся уверенность, что «functools.wraps всё чинит». Он чинит интроспекцию, help() и всё, что читает __wrapped__. Проверяющему он не говорит ничего: wraps — это код, который выполняется при декорировании, а проверяющий смотрит на объявленные типы и до выполнения не доходит.

Получается редкая для Python картина: инструмент времени выполнения знает правду, а инструмент, задача которого — предупредить заранее, не знает. Обычно бывает наоборот, и на этом ожидании ошибка и держится.

Когда декоратор добавляет аргумент

ParamSpec описывает «те же самые параметры». Но декоратор часто меняет сигнатуру: что-то внедряет сам, а наружу это не выставляет. Для таких случаев PEP 612 вводит Concatenate:

Декоратор, который подставляет соединение с базой, а снаружи его прячет (bench/typing/03_concatenate_and_protocol.py):

def needs_conn[**P, R](f: Callable[Concatenate[str, P], R]) -> Callable[P, R]:
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        return f("conn", *args, **kwargs)
 
    return inner
 
 
@needs_conn
def query(conn: str, sql: str, limit: int) -> int:
    return limit

Снаружи у query остаётся два параметра, а не три, и это проверяется:

Тип входа и тип выхода у декоратора теперь разные, и в этом весь смысл: Callable[Concatenate[str, P], R] на входе, Callable[P, R] на выходе.

Чего Concatenate не умеет

Симметричного способа добавить именованный параметр нет. Это не пробел проверяющих и не то, что «пока не сделали в mypy», — ограничение записано в самом PEP отдельным подразделом, вместе с причиной:

PEP заканчивает подраздел обещанием вернуться к вопросу if there is sufficient demand (если будет достаточный спрос). Пока спроса, видимо, не набралось: в 3.14 ничего не изменилось.

Практический вывод простой. Декоратор, который добавляет именованный параметр, типизируется только протоколом с явно выписанным __call__ — то есть перечнем параметров руками, без ParamSpec.

Декоратор метода: Self переживает

Расхожее «после декоратора цепочки вызовов ломаются» проверяется тем же способом. Concatenate[S, P] сохраняет и получателя, и Self (bench/typing/06_methods.py):

def logged[S, **P, R](m: Callable[Concatenate[S, P], R]) -> Callable[Concatenate[S, P], R]:
    def inner(self: S, *args: P.args, **kwargs: P.kwargs) -> R:
        return m(self, *args, **kwargs)
 
    return inner
 
 
class A:
    @logged
    def m(self, x: int) -> str:
        return str(x)
 
    @logged
    def chain(self) -> Self:
        return self

Вывод:

06_methods.py:24: note: Revealed type is "def (x: int) -> str"
06_methods.py:25: note: Revealed type is "06_methods.A"
06_methods.py:26: error: Argument 1 to "m" of "A" has incompatible type "str"; expected "int"  [arg-type]

Первая строка: у a.m получатель уже связан, снаружи виден один параметр. Вторая: a.chain() даёт A, то есть Self доехал через декоратор. Третья: неверный вызов метода ловится так же, как неверный вызов функции.

Когда декоратор вешает атрибут

Callable[P, R] описывает вызываемое — и только. Если декоратор добавляет объекту атрибут (cache_clear, счётчик, что угодно), в этом типе для атрибута места нет. Решение — протокол, у которого есть и __call__, и всё остальное (вторая половина bench/typing/03_concatenate_and_protocol.py):

class HasCache[**P, R](Protocol):
    __wrapped__: Callable[P, R]
 
    def cache_clear(self) -> None: ...
    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R: ...
 
 
def memo[**P, R](f: Callable[P, R]) -> HasCache[P, R]: ...

Тогда h.cache_clear() проходит, а h("x") при h(a: int) даёт ошибку — и она приходит с адресом: Argument 1 to "__call__" of "HasCache". Обратите внимание, что P.args и P.kwargs работают внутри протокола ровно так же, как в обычной функции: пара остаётся парой.

Фабрика: тут ошибаются почти все

Декоратор, умеющий обе формы — @trace и @trace(level=2), — пишут парой перегрузок, и выглядит она безупречно:

@overload
def trace[**P, R](f: Callable[P, R], /) -> Callable[P, R]: ...
@overload
def trace(*, level: int = ...) -> Callable[[Callable[..., object]], Callable[..., object]]: ...

Вывод на двух функциях, задекорированных разными формами (bench/typing/04_factory_broken.py):

04_factory_broken.py:30: note: Revealed type is "def (x: int) -> str"
04_factory_broken.py:31: note: Revealed type is "def (*Any, **Any) -> object"
04_factory_broken.py:32: error: Argument 1 to "a" has incompatible type "str"; expected "int"  [arg-type]

Первая строка — @trace, сигнатура цела. Вторая — @trace(level=2), сигнатуры больше нет. Третья — ошибка на a("bad"). А строкой ниже стоит b("bad"), ровно такой же неверный вызов, и он не подчёркнут вовсе.

Причина видна во второй перегрузке. Фабрика обязана вернуть один тип, а ParamSpec должен связываться заново на каждом применении декоратора. Один Callable[[Callable[..., object]], Callable[..., object]] этого не умеет — и многоточие внутри него делает ровно то, с чего начиналась статья.

Лечится тем, что фабрика возвращает не Callable, а протокол с обобщённым __call__ (bench/typing/05_factory_fixed.py):

class _Deco(Protocol):
    def __call__[**P, R](self, f: Callable[P, R], /) -> Callable[P, R]: ...
 
 
@overload
def trace[**P, R](f: Callable[P, R], /) -> Callable[P, R]: ...
@overload
def trace(*, level: int = ...) -> _Deco: ...

Параметры типа переехали с функции на сам __call__, и связываются они теперь в момент применения. Вывод:

05_factory_fixed.py:34: note: Revealed type is "def (x: int) -> str"
05_factory_fixed.py:35: note: Revealed type is "def (x: int) -> str"
05_factory_fixed.py:36: error: Argument 1 to "b" has incompatible type "str"; expected "int"  [arg-type]

Обе формы дают одну и ту же сигнатуру, и b("bad") наконец ловится.

Попутно — наблюдение, которое стоило нам самим одной правки. Реализация под @overload сначала стояла без аннотаций (def trace(f=None, *, level=1):). mypy на такую реализацию не смотрит вовсе; pyright выдавал по две ошибки Overloaded implementation is not consistent with signature of overload. Аннотация реализации убрала обе, ничего не изменив в выводах примера. Неаннотированная реализация перегрузки для mypy невидима — это стоит помнить и за пределами декораторов.

История версий

Чем измерено

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

• bench/typing/01_naive.py
• bench/typing/02_paramspec.py
• bench/typing/03_concatenate_and_protocol.py
• bench/typing/04_factory_broken.py
• bench/typing/05_factory_fixed.py
• bench/typing/06_methods.py
• bench/typing/07_args_kwargs_pair.py
• bench/typing/version_matrix.py

Проверяющих два: mypy 2.3.1 и pyright 1.1.413, оба под CPython 3.13.7. На всех семи файлах они сошлись — те же строки, те же количества, те же выводы. Это важно назвать: вывод любого инструмента здесь — наблюдение, а не источник. Первична спецификация системы типов, и там, где статья опирается на правило, а не на наблюдение, стоит цитата из неё или из PEP.

Матрица версий снята одним и тем же файлом на четырёх интерпретаторах: 3.11.15, 3.12.3, 3.13.7 и 3.14.7 — все четыре релизные сборки, не кандидаты. 3.11 здесь не для полноты: только на ней видно, что ParamSpec не всегда жил в C.

Времени в этой статье нет намеренно. Типизация на скорость не влияет, и любая таблица наносекунд здесь была бы таблицей про PEP 649, а не про ParamSpec.