How does inspect.signature see past a @functools.wraps wrapper to the original parameters?

### The link, not a rewrite The single fact that explains all of this: `functools.update_wrapper` — the machinery that `@functools.wraps(func)` invokes — finishes by executing `wrapper.__wrapped__ = func`. That attribute is a plain reference from the wrapper back to the callable it wraps. Nothing about the wrapper's own compiled parameters changes; the wrapper still accepts `*args, **kwargs` and always will. `inspect.signature` then resolves a callable in a defined order: 1. If the object has an explicit **`__signature__`** attribute holding an `inspect.Signature`, that wins outright — even when `follow_wrapped=False` is passed. 2. Otherwise, unless `follow_wrapped=False`, it walks the **`__wrapped__` chain** to its end. 3. It then builds a `Signature` from that final callable's code object and annotations. So the "magic" is a pointer traversal. A `@functools.wraps`-decorated function reports `(line: str, strict: bool = False)` because `inspect.signature` never looked at the wrapper at all. ### Seeing the wrapper's real parameters `inspect.signature(decorated, follow_wrapped=False)` stops the traversal and reports what the wrapper itself declares — typically `(*args, **kwargs)`. One wrinkle on 3.14: because `functools.WRAPPER_ASSIGNMENTS` copies `__annotate__`, the *return* annotation of the original comes along for the ride, so you may see `(*args, **kwargs) -> tuple[str, bool]`. The parameters are the wrapper's; the annotations were copied. `inspect.unwrap(obj)` walks the same chain and returns the object at the end. It takes an optional `stop` predicate to halt part-way, and it raises `ValueError` — `"wrapper loop when unwrapping ..."` — if it detects a cycle, which is why two decorators that accidentally point `__wrapped__` at each other fail loudly rather than hanging. ### Stacked decorators build a chain, not a single hop `@a` above `@b` above `def f` produces `a(b(f))`, and each layer that used `functools.wraps` set its own `__wrapped__`. The result is a linked list: `decorated.__wrapped__.__wrapped__ is f`. `inspect.signature` and `inspect.unwrap` both follow it to the end, so the reported parameters are the innermost function's regardless of stack depth — as long as *every* layer used `functools.wraps`. A single naive layer in the middle breaks the chain, and introspection stops at that layer's `(*args, **kwargs)`. ### Which other helpers follow the chain — and which do not This is the part candidates get wrong, because the behaviour is not uniform across `inspect`: * **Follows `__wrapped__`:** `inspect.signature`, `inspect.unwrap`, and the source-location helpers `inspect.getsource`, `inspect.getsourcefile` and `inspect.getfile`. That is why `inspect.getsource` on a decorated function prints the *original* `def` — including its decorator lines — rather than the three-line wrapper body. * **Does not follow it:** `inspect.getfullargspec`, which reports the wrapper's literal `args=[], varargs='args', varkw='kwargs'`. If you have legacy code introspecting callables with `getfullargspec`, decoration changes its answer even with `functools.wraps` applied. Prefer `inspect.signature`. `__wrapped__` is also just an attribute, so anything can set it — and a few libraries set it without running `update_wrapper` at all, purely to make introspection resolve. ### Why this design instead of copying the signature CPython could have had `update_wrapper` compute and store a `Signature` eagerly. Storing a reference instead is cheaper (no `Signature` object built at import time for decorators that are never introspected), it survives later mutation of the original, and it preserves a *chain* so a tool can choose how far to unwrap. The trade-off is the one that bites: what `inspect.signature` reports is the original's contract, which is correct only while the wrapper forwards arguments unchanged. A wrapper that injects, removes or renames a parameter makes the reported signature a lie — and the remedy is an explicit `__signature__`, which is exactly why step 1 of the resolution order exists. ### What to say in an interview State it as three sentences: `functools.wraps` sets `__wrapped__`; `inspect.signature` prefers an explicit `__signature__` and otherwise follows `__wrapped__` to the end of the chain; `follow_wrapped=False` or a direct look at the wrapper's code object shows the `*args, **kwargs` the wrapper really has. Then mention that `getfullargspec` does not follow the chain — it is the detail that shows you have actually debugged this rather than read about it. ### A debugging recipe worth keeping When a framework or dispatcher reports parameters that do not match reality, three lines localise the problem. Print `inspect.signature(obj)`, print `inspect.signature(obj, follow_wrapped=False)`, and print `inspect.unwrap(obj)`. If the first two agree, no chain is involved and the object really does declare those parameters. If they differ, you are looking through a wrapper, and the third line names exactly which callable the report came from - which is usually enough to find the decorator responsible. Walking `__wrapped__` in a loop, as the second example does, gives you the whole stack when several layers are involved. ### The related trap: a truncated chain Because every layer must cooperate, a single decorator in the middle of a stack that forgot `functools.wraps` cuts the chain at that point. Introspection then reports that layer's `(*args, **kwargs)`, and it does so silently - there is no warning, and the outer layers look innocent. If a decorated function suddenly reports bare varargs, the fault is almost never the outermost decorator; it is the first one, working inwards, that failed to wrap.