Why does @retry(times=3) need one more function layer than a bare @retry?

### The decoration line is a rewrite rule, not special argument handling Python does not treat `@` as a keyword that understands options. It evaluates the expression that follows `@`, calls the result with the object being defined, and rebinds the name to whatever that call returns. One rule covers both spellings: ```python @retry def plan_route(): ... # plan_route = retry(plan_route) @retry(times=3) def plan_route(): ... # plan_route = retry(times=3)(plan_route) ``` The second decoration contains a *call*. The interpreter evaluates `retry(times=3)` first, and then immediately applies whatever came back to `plan_route`. Nothing hands `times=3` to `retry` alongside the function; there are two separate calls, in that order. That is the entire reason a parameterised decorator needs one more layer than a bare one — the layer is not a convention, it is what the desugaring demands. ### The three levels and what each one closes over ```python import functools def retry(times): # 1: the factory - receives the options def decorator(func): # 2: the real decorator - receives the function @functools.wraps(func) def wrapper(*args, **kwargs): # 3: runs per call - sees both for attempt in range(1, times + 1): try: return func(*args, **kwargs) except ValueError: if attempt == times: raise return wrapper return decorator ``` The names are conventional; the return chain is not. Each level's only structural job is to return the next one, and the last one returns the value the caller wanted. `wrapper` can read `times` because it is nested inside the factory's scope, and it can read `func` because it is nested inside the decorator's scope. Both arrive as closure cells, which is why nothing has to be stored on the function object or threaded through as an extra parameter. A useful way to check your own code is to count `return` statements rather than `def` statements: a bare decorator has one `return` of a callable, a factory has two. ### When each level actually runs Levels one and two run exactly once, at the moment the `def` statement executes — module import time for a top-level function, class-body execution for a method. Only `wrapper` runs per call. Saying that out loud in an interview is what separates "I memorised the shape" from "I know decoration is ordinary function application". It also explains why any cost you pay inside the factory or the decorator is paid once per process, while cost inside the wrapper is paid on every call. ### The two ways of getting the count wrong, and how differently they fail Apply a factory bare and nothing complains at import: `plan_route = retry(plan_route)` succeeds, binding the function object to the `times` parameter and leaving the *inner decorator* under the name `plan_route`. The failure surfaces later, at the first call, and the message points at a function the caller has never heard of: ``` TypeError: retry.<locals>.decorator() missing 1 required positional argument: 'func' ``` The mirror-image mistake — writing `@log()` where `log` is an ordinary two-level decorator — fails immediately, at import, with `TypeError: log() missing 1 required positional argument: 'func'`. That asymmetry is worth remembering: the missing-parentheses bug is the dangerous one because it can ship, sit in a rarely-exercised branch, and blow up in production far from the decoration line. ### Empty parentheses are not optional If a factory's options all have defaults, you still write `@retry()`, not `@retry`. The parentheses are what runs the factory and produces a decorator. Deciding a factory should also accept the bare form is a deliberate design choice that costs an extra branch in the signature; it does not happen for free. ### The factory is just a callable Nothing requires the factory to be a plain function, and nothing requires the decorator it returns to be a function either — only that the object returned by the `@` expression can be called with one argument and return something useful. Since Python 3.9 (PEP 614) the grammar after `@` accepts any expression, so `@registry["retry"](times=3)` is legal; before 3.9 the grammar allowed only a dotted name with an optional call, which already permitted `@retry(times=3)`. The semantics of decorator factories themselves are unchanged through 3.14. ### Why this gets asked live Interviewers ask candidates to write a parameterised decorator on the spot precisely because the three-level shape is easy to memorise and hard to fake under a follow-up. The tell is whether a candidate can say, for each `return` in their own code, what the returned object is and who calls it next.