A @functools.wraps decorator changes a function's parameters - how do you keep inspect.signature honest?

### The scenario A log-ingest pipeline is built from stage functions, and a dispatcher wires them together by reading `inspect.signature(stage)` and binding whatever the pipeline context can supply. A four-person team adds a decorator that injects the ingest `source` so individual stages stop threading it manually: ```python @inject_source def parse(line, source): ... ``` The wrapper supplies `source` itself, so callers must now pass only `line`. But the decorator used `functools.wraps`, `functools.wraps` set `__wrapped__`, and `inspect.signature` follows `__wrapped__` — so the dispatcher still reads `(line, source)`. It dutifully passes `source`, the wrapper passes its own too, and every stage dies on a duplicate keyword argument. Nobody wrote a bug; the metadata simply describes a contract the wrapper no longer honours. ### Why the lie happens `inspect.signature` resolves a callable in a fixed order: an explicit **`__signature__`** attribute first, then the **`__wrapped__`** chain, then the object's own code object. `functools.wraps` only ever populates the second of those. That default is right for the overwhelmingly common wrapper — one that forwards `*args, **kwargs` untouched — and wrong for any wrapper that changes the call contract: injecting an argument, consuming one, adding a keyword-only flag, or binding a value with `functools.partial`. ### The fix: publish the real contract Build the signature you actually accept and assign it: ```python sig = inspect.signature(func) params = [p for name, p in sig.parameters.items() if name != "source"] wrapper.__signature__ = sig.replace(parameters=params) ``` `inspect.Signature.replace` returns a new immutable `Signature`; `inspect.Parameter` lets you add one (`inspect.Parameter("trace", inspect.Parameter.KEYWORD_ONLY, default=False)`) as easily as drop one. Because `__signature__` is checked *before* `__wrapped__`, the reported signature becomes the truth while `__name__`, `__doc__`, `__module__` and `__wrapped__` keep doing their jobs. Note that `__signature__` wins even when a caller passes `follow_wrapped=False`, so there is no back door to the old answer — which is the point. Two worse alternatives worth being able to reject out loud: * **`del wrapper.__wrapped__`.** It does make `inspect.signature` fall back to the wrapper's own `(*args, **kwargs)` — technically not a lie, but useless to a dispatcher, and it breaks `inspect.unwrap` and `inspect.getsource`. * **Dropping `functools.wraps` entirely.** You trade one wrong answer for a wrapper with no name, no docstring and no `__qualname__`, which breaks registries and pickling too. A third option deserves respect: *do not change the contract in a decorator*. A wrapper that alters the parameter list is a small API redesign wearing an `@`, and on a shared pipeline it is often clearer to make `source` an explicit keyword-only parameter with a default than to hide the injection. ### The second, quieter problem: a shared `__dict__` The same team hit a related surprise. `functools.update_wrapper` merges attributes with `wrapper.__dict__.update(func.__dict__)` — an *update*, and a **shallow** one. If a first decorator attaches a mutable attribute to the function (`func.filters = []`) and a second decorator wraps the result, the wrapper's `filters` is the *same list object*, not a copy. Two stages configured by two different developers then mutate one shared list, and because the pipeline configures stages from several threads at import-adjacent startup, the observed state depends on ordering: a race on shared state whose root cause is one `update()` call in the standard library. The defence is to treat function attributes as immutable once set, or to have each decorator rebind rather than mutate — `wrapper.filters = [*getattr(func, "filters", ()), new]` — so no two layers ever hold the same container. ### Scope: runtime only `__signature__` is a *runtime* fact. A static type checker never executes your decorator and never reads the attribute; it reasons from the decorator's own declared parameter and return types. If both audiences matter, the decorator needs honest static typing (a `Callable` or a `Protocol` describing the returned callable) *and* a `__signature__` for the runtime dispatcher. Saying that out loud — that these are two separate mechanisms serving two separate consumers — is what separates a senior answer from a correct one. ### Proving it, and keeping it proved An explicit `__signature__` is hand-written metadata, so it can drift from the wrapper it describes the moment somebody edits the wrapper. Pin it with a test rather than a comment: take `inspect.signature(decorated)`, call `Signature.bind` with the arguments a caller would really pass, and then actually call the function with the same arguments. If the bind succeeds and the call raises `TypeError`, the published signature is lying. That one assertion catches the injected-argument case, the removed-argument case and the renamed-parameter case, and it costs a few lines per decorator. ### What to say when asked Lead with the resolution order, because everything else follows from it: `inspect.signature` checks `__signature__`, then the `__wrapped__` chain, then the object's own code object. `functools.wraps` populates only the middle one, which is correct for a forwarding wrapper and wrong for any wrapper that edits the call contract. Then give the repair - build a `Signature` with `replace` and assign it - and finish with the design point: a decorator that changes the parameter list is an API change in disguise, and re-signing is how you make it honest, not a reason to make more of them.