What does the @ decorator syntax above a Python def actually do?

### The desugaring, stated once A decorator is not a special kind of object, and `@` is not a runtime mechanism. `@deco` on the line above a `def` is grammar that expands into two ordinary steps. Python first executes the `def` statement and builds a function object exactly as it always does. Then, instead of binding that object to the name, it calls `deco` with it and binds the **result** to the name in the enclosing namespace. So this: ```python @deco def f(x): return x ``` is the same program as this: ```python def f(x): return x f = deco(f) ``` with one small difference: in the sugared form the undecorated function is never bound to the name at all, so no other code can observe it under that name, not even briefly. Every other decorator behaviour you will ever be asked about follows from that single rebinding. ### What qualifies as a decorator Anything callable that accepts one positional argument. A plain function is the usual case, but a class whose instances are callable works too, and so does a builtin. The interpreter does not inspect or validate the return value. A decorator may return the same object it was handed — the registration idiom, where the point is the side effect and the function is passed through untouched — or a brand-new function, or an instance of some class, or `None`. Returning `None` is the classic beginner's bug: the `def` seems to vanish, the name is bound to `None`, and the failure surfaces far from its cause as `TypeError: 'NoneType' object is not callable`. Since Python 3.9 (PEP 614) the expression after `@` may be any expression — a subscript, a call whose result is itself called, a conditional expression. Older grammars allowed only a dotted name with an optional argument list. On 3.14 the relaxed grammar is simply the rule; you rarely need it, but it explains why `@things[0]` parses. ### The wrapper-closure shape Most useful decorators need to run code around each call, and the only way to do that is to hand back a different callable. That callable is normally a nested function that closes over the original: ```python def announce(func): def wrapper(*args, **kwargs): print("calling", func.__name__) return func(*args, **kwargs) return wrapper ``` `wrapper` is created fresh each time `announce` runs, and it captures `func` in its closure. After `@announce` is applied, the module-level name refers to `wrapper`; the original function object is still alive, but the only reference to it is the closure cell inside that wrapper. This is why a decorated function is not "modified" — nothing about the original object changes. It is wrapped, and the *name* is what moved. ### Everything the name change implies Because callers reach the wrapper, the wrapper is now the public callable. Its parameters are the signature callers must satisfy, its return value is what callers receive, and its identity is what introspection sees: `f.__name__` reports `'wrapper'` unless the decorator copies the metadata across, which `functools.wraps` exists to do and which is its own topic. Comparisons by identity, pickling by name, and anything else keyed on the object all now see the wrapper. None of that is surprising once you hold on to `f = deco(f)`. ### Applying a decorator by hand Since `@` only rebinds a name, you can always do it yourself: ```python def build_pick_list(order): return sorted(order) build_pick_list = announce(build_pick_list) ``` That is the escape hatch when the target is not yours to annotate — a callable imported from elsewhere, a function you want to decorate only under a runtime condition, or a lambda stored in a table. It is also the shape to recall in an interview when someone asks what `@` "compiles to": there is no separate mechanism to describe, only a call and a binding. ### The mental model to keep Read `@deco` as "hand this new function to `deco` and use whatever comes back". A junior who can state that sentence, and who knows that the decorator body runs at definition time while the wrapper runs per call, already has the whole model; decorators with arguments, stacked decorators, metadata preservation and class decoration are all variations layered on top of one rebinding.