How does typing.ParamSpec let a decorator preserve the wrapped function's signature?

## The problem: decorators erase signatures A decorator replaces a function with a wrapper. If you annotate that transformation loosely, you also throw away what callers knew: ```python def memoized(fn: Callable[..., Any]) -> Callable[..., Any]: ... ``` Everything still checks, and that is the danger. After decoration, an invoice renderer declared `render_invoice(invoice_id: int, *, watermark: str = "") -> bytes` looks to a checker like a function of unknown parameters returning `Any`. Call it with the id as a string, misspell the keyword, or add a stray positional argument, and nothing complains. The bug surfaces at runtime — often far from the decorator, in the reporting path that only exercises the cache-miss branch when the hit rate drops below its usual 83%. The earlier workaround was a `TypeVar` bound to `Callable`: ```python F = TypeVar("F", bound=Callable[..., Any]) def memoized(fn: F) -> F: ... ``` This preserves the signature exactly and is still seen in older code, but it is rigid: it can only return *the identical* callable type, so a decorator that changes the return type, adds a parameter, or wraps a sync function into an async one cannot be expressed. ## What ParamSpec is `typing.ParamSpec`, added in Python 3.10 by PEP 612, is a type variable whose value is **an entire parameter list** — positional, keyword, defaults, ordering and all — rather than a single type. Where `TypeVar` lets you say "whatever type comes in comes out", `ParamSpec` lets you say "whatever *signature* comes in comes out". ```python P = ParamSpec("P") R = TypeVar("R") def memoized(fn: Callable[P, R]) -> Callable[P, R]: ... ``` `Callable[P, R]` places the ParamSpec in the parameter slot where a list of types would normally go. A checker binds `P` to the concrete parameter list of each decorated function and `R` to its return type, then re-applies both to the result. Callers of the decorated renderer keep full checking: the id must be an `int`, `watermark` must be a `str` keyword, and the result is `bytes`, not `Any`. ## P.args and P.kwargs Inside the wrapper, the two members of a ParamSpec appear as annotations: ```python def wrapper(*args: P.args, **kwargs: P.kwargs) -> R: return fn(*args, **kwargs) ``` Three rules govern them. They may only annotate the `*args` and `**kwargs` parameters of a function; they must be used **together** in the same signature, never one alone; and their whole meaning is "these two together represent exactly one call to `P`". That last point is what allows the checker to verify that the wrapper forwards the arguments faithfully — `fn(*args, **kwargs)` is accepted, while dropping, reordering or injecting arguments is not. ## What ParamSpec is not It is not `functools.wraps`, and the two are not alternatives. `functools.wraps` is a runtime device that copies `__name__`, `__doc__`, `__module__`, `__qualname__` and the wrapped function's `__dict__` onto the wrapper so introspection and documentation tools see the original. It does nothing for a static checker, and the checker does nothing for runtime introspection. A well-typed decorator uses both. It is also not limited to identity transformations. Because the return type is a separate variable, a decorator may legitimately change it — `Callable[P, R] -> Callable[P, Awaitable[R]]` types a wrapper that makes a sync function awaitable, keeping the parameters intact. And a ParamSpec can be declared with a default in the PEP 696 sense, or spelled inline as `def memoized[**P, R](fn: Callable[P, R]) -> Callable[P, R]` using the type-parameter syntax available from 3.12. ## Why the loss spreads The reason a weak decorator annotation matters more than it first appears is that `Any` is contagious through a call graph. The decorated renderer returns `Any`; the function that calls it assigns that to a local, passes it on, and every downstream annotation that depended on the result being `bytes` is now being checked against a value the checker has agreed not to reason about. One loosely typed decorator applied across a module's public functions can quietly switch off checking for a whole layer, and because nothing errors, the loss never appears in a build log — it appears months later as a class of bug the team assumed the checker was catching. That is also why `ParamSpec` is worth applying to decorators that seem trivial. A logging or timing decorator adds no behaviour worth typing, but it sits on top of functions whose signatures are the ones callers actually rely on. ## Limits worth knowing A bare `ParamSpec` copies the parameter list unchanged. It cannot express a decorator that *adds* or *consumes* a parameter — that is `Concatenate`'s job, and only for leading positional parameters. It also cannot express "adds a keyword-only option", which still needs a `Protocol` with `__call__` or an overload set. And on Python versions before 3.10 the names live in a backport package rather than the standard library, which is why long-lived codebases sometimes carry an import shim. The practical rule: any decorator you write in a typed codebase should be `Callable[P, R]`-shaped by default. The ellipsis form should have to argue for itself.