What does functools.wraps fix about a decorator's wrapper function?

### Decoration rebinds a name; it does not rename an object `@deco` written above `def stage(...)` is pure sugar. Python compiles the `def`, builds a function object whose `__name__` is `"stage"`, calls `deco(stage)`, and binds the *result* back to the module global `stage`. Almost every decorator returns a brand-new inner function — conventionally called `wrapper` — so the name `stage` now points at that wrapper. Identity attributes belong to the function object that was compiled, not to the name it happens to be bound to. So after a naive decoration: * `stage.__name__` is `"wrapper"` * `stage.__qualname__` is `"deco.<locals>.wrapper"` * `stage.__doc__` is the wrapper's docstring, which is almost always `None` * `stage.__module__` names the module where the *decorator* was defined * `stage.__dict__` is empty, so any attribute hung on the original function is gone Nothing in the language notices or complains. The function still runs; it has simply lost its papers. ### Who actually reads those attributes The damage is not limited to `help()`, though `help(stage)` and `pydoc` output are the fastest way to see it. Concretely: * **Registries.** A decorator that does `REGISTRY[func.__name__] = func` collapses: every function decorated through the same decorator registers under `"wrapper"`, and the last one wins. * **Metrics and log messages** built from `func.__name__` by *another* decorator in the stack all report the same label, which makes a dashboard useless without any error being raised. * **Documentation tooling** reads `__doc__` and `__qualname__`; a decorated API renders blank. * **`pickle`** stores a plain function *by reference*: it writes `__module__` and `__qualname__` and re-imports the object on load. `"deco.<locals>.wrapper"` names a local object that no import can reach, so `pickle.dumps` raises `PicklingError`. That is why an un-wrapped decorator can break `multiprocessing` — the `spawn` and `forkserver` start methods pickle the callable, and since 3.14 `forkserver` is the default on Unix platforms other than macOS. * **`repr()`** of the function, which is what a traceback line and a debugger both show. ### What `functools.wraps` is `functools.wraps(func)` is a thin decorator factory: it returns a `functools.partial` of `functools.update_wrapper` with `wrapped=func` bound. So writing `@functools.wraps(func)` above the inner `wrapper` is exactly `functools.update_wrapper(wrapper, func)`, and `update_wrapper` does three things: 1. **Copies each name in `functools.WRAPPER_ASSIGNMENTS`** from the wrapped object onto the wrapper, silently skipping any the wrapped object does not have. On CPython 3.14 that tuple is `('__module__', '__name__', '__qualname__', '__doc__', '__annotate__', '__type_params__')`. 2. **Merges, for each name in `functools.WRAPPER_UPDATES`** — just `('__dict__',)` — with `wrapper.__dict__.update(func.__dict__)`. Note *update*, not replace, and note that it is **shallow**: a mutable attribute on the original is now the same object on both. 3. **Sets `wrapper.__wrapped__ = func`**, which is what lets `inspect` find the original later. The two version details worth knowing: `__type_params__` joined the tuple in 3.12 with PEP 695's type-parameter syntax, and in 3.14 PEP 649/749 made annotations lazy, so the tuple now carries `__annotate__` — the function that *computes* annotations — where 3.13 and earlier carried the already-built `__annotations__` dict. Reading `decorated.__annotations__` still gives you the original's annotations on every version; only the copied attribute changed. ### What it deliberately does not do `functools.wraps` is cosmetic in the precise sense that it never touches the wrapper's **code object**. The wrapper still really accepts `*args, **kwargs`, still appears as its own frame in a traceback, and is still a plain function even if the wrapped callable was a coroutine function. What changes is only what *introspection* reports — and `inspect.signature` reports the original's parameters because it follows `__wrapped__`, not because the wrapper's parameters changed. It also never raises for a missing attribute. Calling `functools.update_wrapper` against a `functools.partial` object, which has no `__name__`, quietly leaves the wrapper's own name in place and still sets `__wrapped__`. That silence is convenient and occasionally surprising. ### The practice Put `@functools.wraps(func)` on every wrapper you write, without deliberating about it. It is one line, it has no runtime cost after decoration, and the failures it prevents — a collapsed registry, a blank doc build, a pickling error at a process boundary — all surface far from the decorator that caused them. ### `wraps` and `update_wrapper` are the same operation `@functools.wraps(func)` is the decorator spelling and reads best directly above an inner `def`. `functools.update_wrapper(wrapper, func)` is the identical operation written as a plain call, which is what you reach for when there is no `def` in front of you: a callable you were handed, or one you have to fix up after it was built. Both accept optional `assigned` and `updated` arguments if you need to narrow or extend the two tuples - and note that even `assigned=(), updated=()` still sets `__wrapped__`, because that assignment is unconditional. ### How to demonstrate it in thirty seconds The whole answer fits in a REPL. Define one decorator without `functools.wraps` and one with it, apply each to a function with a docstring, and print `__name__`, `__qualname__` and `__doc__` for both. The first reports `wrapper`, `deco.<locals>.wrapper` and `None`; the second reports the original three. Then check `hasattr(decorated, "__wrapped__")` on each - `False` and `True` - which is the bridge to every introspection question that follows. Being able to produce that comparison from memory is what an interviewer is really checking, because it shows you have hit the problem rather than read the docstring.