Typing decorators: why the checker goes quiet, and what fixes it

Two wrong calls, zero errors

Here is a decorator written the way they are most often written:

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

Three calls under it, two of them deliberately wrong: takes_int_str(1, "A"), takes_int_str("B", 2) with the types swapped, and takes_int_str() with no arguments at all.

The type checker — mypy — finds none of them. Zero errors, exit code zero.

It is the ellipsis

"... means any arguments" is an explanation that sounds harmless. PEP 612 puts it differently: an ellipsis in place of parameter types means that no validation of the arguments is done at all.

The gap between "any is acceptable" and "we do no validation" is exactly the gap between a harmless-sounding phrase and three calls let through. The checker did exactly what it was told. It was told badly.

ParamSpec: the same function, three errors

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

The decorator's body has not changed, the calls have not changed. The declaration has — and the checker now finds all three errors: two about types and one about the number of arguments.

P.args and P.kwargs are only ever written as a pair. The reason is not notational: different calls split the same set of parameters differently — f(1, y=2) puts the two into kwargs, f(1, 2) puts it into args. Half of the pair would fail to describe every case, and both checkers reject it.

The runtime is honest, the checker is blind

The most unexpected part is that the signature never went anywhere at runtime:

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

The second line is the truth: what will be called is a function taking *args, **kwargs. The first is what inspect shows by default, because functools.wraps left a reference to the wrapped function on the wrapper and signature hops along it.

Hence the belief that "wraps fixes everything". It fixes help() and introspection. It tells the checker nothing.

Where nearly everyone gets it wrong

A decorator supporting both forms — @trace and @trace(level=2) — is written as a pair of overloads, and it looks impeccable. Measured:

The second row is a loss, and a silent one: a wrong call to such a function is simply not flagged.

The cause is that a factory has to return one type, while a ParamSpec has to bind afresh at every application of the decorator. The cure is a factory that returns not a Callable but a protocol with a generic __call__:

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

After that both forms give the same signature.

What measured this

Every example lives as a whole file in bench/typing/: from bench/typing/01_naive.py through bench/typing/07_args_kwargs_pair.py, plus bench/typing/version_matrix.py for the version table. There are two checkers — mypy 2.3.1 and pyright 1.1.413 under CPython 3.13.7 — and they agreed on every file.

What either of them prints is an observation, not a source: the typing specification comes first, and wherever the word "rule" appears above, it is the specification or a PEP standing behind it.

Zero errors on two wrong calls

Start with the measurement, not the explanation. Here is an ordinary decorator, written the way they are most often written:

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

And three calls under it, two of them deliberately wrong:

takes_int_str(1, "A")  # a correct call
takes_int_str("B", 2)  # the types are swapped
takes_int_str()  # no arguments at all

The type checker — mypy 2.3.1 — finds none of them. The file in full is bench/typing/01_naive.py; the output verbatim:

$ mypy 01_naive.py
  -> exit=0

No error, no warning, exit code zero. The second checker, pyright 1.1.413, is silent on the same file too.

What the ellipsis means

The usual explanation — "... means any arguments" — sounds harmless, which is why it does not put anyone on guard. The typing documentation phrases it that way:

About what happens to the checking of CALLS to such an object, it says nothing. PEP 612 does say it, and in rather different words:

The gap between "any is acceptable" and "we do no validation" is exactly the gap between a harmless-sounding phrase and three calls let through. The typing specification puts it more strictly: This is a gradual form indicating that the type is consistent with any input signature. A gradual form is a place where checking is deliberately switched off.

Notice what this explanation does not contain: the word "bug". The checker did exactly what it was told. It was told badly.

ParamSpec: the same code, three errors

PEP 612 exists precisely to fix this. Its problem statement is about decorators in as many words:

The same decorator, rewritten with a ParamSpec in PEP 695 syntax:

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

The decorator's body has not changed. The calls have not changed. The file of calls is the same file. One line changed — the declaration. The output (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]

Three errors on the same two lines — two about types and one about the count. pyright finds the same three, in its own words. This article, in essence, comes down to that pair of runs: ... is not "any arguments", it is "do not check".

Why P.args and P.kwargs come only as a pair

The first thing people trip over is writing half of it:

def half[**P, R](f: Callable[P, R]) -> Callable[P, R]:
    def inner(*args: P.args) -> R:  # error: half of a pair
        return f(*args)
 
    return inner

Both checkers refuse, each in its own words (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]

And two more follow, on lines 27 and 29: the call is left without parameters, and the result no longer fits the declared type. The second checker refuses on the same three lines and names the rule more directly:

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

The reason is named in the PEP, and it is not about notational convenience:

Then comes the point of the restriction. Different calls split the same set of parameters differently: f(1, y=2) puts the one into args and the two into kwargs, while f(1, 2) puts both into args.

So the pair is not a syntactic formality but the only way to say "the very same parameters" without knowing in advance how the caller will split them.

The runtime is honest, the checker is blind

Here begins the part that is written down almost nowhere, and it inverts the picture people carry.

While the checker was silent, the signature never went anywhere at runtime. Measured on 3.12.3, 3.13.7 and 3.14.7 — identical on all three:

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')

Read it from the bottom up. The last line is the truth: under the decorator sits a function taking *args, **kwargs, and that is the one that will be called. The middle line is the same truth, spoken by inspect when asked not to hop. The top line is what inspect shows by default.

The hop is made possible by functools.wraps — the mechanism itself is taken apart in the article on decorators, and here it is taken as given. wraps puts a reference to the wrapped function on the wrapper (wrapper.__wrapped__ = wrapped, Lib/functools.py:62 on 3.13.7), and inspect.signature is declared to follow it: def signature(obj, *, follow_wrapped=True, ...) (Lib/inspect.py:3373).

That is where the belief that "functools.wraps fixes everything" comes from. It fixes introspection, help() and everything that reads __wrapped__. It tells the checker nothing: wraps is code that runs at decoration time, and the checker never gets as far as running anything.

The result is a picture rare in Python: the runtime tool knows the truth, and the tool whose whole job is to warn you in advance does not. Usually it is the other way round, and the mistake lives on that expectation.

When the decorator adds an argument

ParamSpec describes "the very same parameters". But a decorator often changes the signature: it supplies something itself and does not expose it outward. For those cases PEP 612 introduces Concatenate:

A decorator that supplies a database connection and hides it from the outside (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

From the outside query keeps two parameters rather than three, and that is checked:

The decorator's input type and output type are now different, and that is the whole point: Callable[Concatenate[str, P], R] going in, Callable[P, R] coming out.

What Concatenate cannot do

There is no symmetric way to add a keyword parameter. This is not a gap in the checkers, nor something "mypy has not got round to" — the limitation is written into the PEP as its own subsection, together with the reason:

The PEP closes the subsection promising to return to the question if there is sufficient demand. Apparently the demand has not built up: nothing changed in 3.14.

The practical conclusion is simple. A decorator that adds a keyword parameter can only be typed with a protocol whose __call__ spells the parameters out by hand, without a ParamSpec.

Decorating a method: Self survives

The common line "chained calls break after a decorator" can be checked the same way. Concatenate[S, P] preserves both the receiver and 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

The output:

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]

First line: on a.m the receiver is already bound, and one parameter is visible from outside. Second: a.chain() gives A, so Self made it through the decorator. Third: a wrong call to a method is caught just like a wrong call to a function.

When the decorator attaches an attribute

Callable[P, R] describes something callable, and nothing else. If a decorator adds an attribute to the object (cache_clear, a counter, anything), that type has no room for it. The answer is a protocol that has both a __call__ and everything else (the second half of 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]: ...

Then h.cache_clear() passes, and h("x") on an h(a: int) is an error — one that arrives with an address: Argument 1 to "__call__" of "HasCache". Note that P.args and P.kwargs behave inside a protocol exactly as they do in an ordinary function: the pair stays a pair.

The factory: where nearly everyone gets it wrong

A decorator that supports both forms — @trace and @trace(level=2) — is written as a pair of overloads, and it looks impeccable:

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

The output on two functions decorated by the different forms (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]

The first line is @trace, signature intact. The second is @trace(level=2), signature gone. The third is the error on a("bad"). And one line below sits b("bad"), a wrong call in exactly the same way, and it is not flagged at all.

The cause is visible in the second overload. A factory has to return one type, while a ParamSpec has to bind afresh at every application of the decorator. A single Callable[[Callable[..., object]], Callable[..., object]] cannot do that — and the ellipsis inside it does precisely what this article opened with.

The cure is a factory that returns not a Callable but a protocol with a generic __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: ...

The type parameters have moved from the function onto __call__ itself, and now they bind at the moment of application. The output:

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]

Both forms give the same signature, and b("bad") is finally caught.

One observation along the way, which cost us a correction of our own. The implementation under @overload originally had no annotations (def trace(f=None, *, level=1):). mypy does not look at such an implementation at all; pyright produced two errors each time, "Overloaded implementation is not consistent with signature of overload". Annotating the implementation removed both and changed nothing in the example's conclusions. An unannotated overload implementation is invisible to mypy — worth remembering well beyond decorators.

Version history

What measured this

The findings in this article come from these files. Each one opens right from here, together with the record of the run: what checked it, with which command, and what came out verbatim.

• 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

There are two checkers: mypy 2.3.1 and pyright 1.1.413, both under CPython 3.13.7. They agreed on all seven files — same lines, same counts, same conclusions. That is worth naming: what a tool prints is an observation here, not a source. The typing specification comes first, and wherever this article leans on a rule rather than on an observation, a quotation from the specification or from a PEP stands next to it.

The version matrix comes from a single file run on four interpreters: 3.11.15, 3.12.3, 3.13.7 and 3.14.7 — all four final releases, not release candidates. 3.11 is not there for completeness: it is the only one that shows ParamSpec has not always lived in C.

There are no timings in this article, deliberately. Typing does not affect speed, and any table of nanoseconds here would be a table about PEP 649 rather than about ParamSpec.