At what point does a Python decorator's own body run relative to calls?

### Two clocks, not one A decorator involves two moments that beginners collapse into one. **Decoration time** is when the decorator function itself runs: the `def` statement executes, builds a function object, hands it to the decorator, and binds the name to the return value. **Call time** is when the returned wrapper runs. The decorator body executes exactly once per `def`; the wrapper executes once per call. Knowing which of the two a line of code is in explains most surprising decorator behaviour. ### When decoration time actually is A `def` at module level is a top-level statement, and top-level statements run when the module is executed — which for an imported module means the first time it is imported anywhere in the process. Import machinery then records the module in `sys.modules`, so subsequent `import` statements for the same name rebind a reference and do **not** re-execute the body. Decoration therefore happens once per module per process, no matter how many modules import it. (`importlib.reload` deliberately re-executes the module and so re-runs the decoration, which is exactly why reloading a module with a registration decorator can produce duplicate entries.) Within a single module the order is plain source order, top to bottom. Across modules it is import order, which is decided by the import graph and by whatever your entry point touches first — not by anything visible at the definition site. Any design that depends on decorators running in a particular sequence across files has an ordering assumption that nobody can see or verify locally. A `def` nested inside another function is different: its decorator runs each time the outer function runs, because the inner `def` is an ordinary statement in the outer body. That is a real cost if the decorator is expensive, and a real bug source if the decorator registers something, since each outer call registers again. ### The scenario that teaches it A nightly warehouse pick-list builder runs for about six hours. Someone writes a decorator that records the run date and stamps every pick list with it. Written in the decorator body — ```python import datetime def stamped(func): day = datetime.date.today() # decoration time: once def wrapper(*args, **kwargs): return day, func(*args, **kwargs) return wrapper ``` — `day` is evaluated once, when the module was imported. A job that starts at 22:00 and finishes at 04:00 stamps every list produced after midnight with the previous day, and the bug is invisible in a short test run. Move `datetime.date.today()` inside the wrapper and each call re-evaluates it. The general rule: per-call values belong in the wrapper; only genuinely shared state — a cache dict, a counter, a lock, a compiled pattern — belongs in the decorator body, where being created once is the point. The same run shows the ordering hazard. If two modules each decorate steps at import, the sequence in which those decorator bodies ran is the sequence in which their modules happened to be imported. Rearranging an import, or adding one, silently reorders them. ### Import-time side effects Because decorator bodies execute during import, anything they do happens before your program's own start-up has finished. That has consequences worth stating explicitly: - **Logging is not configured yet.** A decorator that logs at decoration time emits before `main()` calls the logging configuration, so the message is formatted by default handlers or dropped entirely. - **Configuration and the environment may not be loaded.** Reading a setting at decoration time freezes the value that existed at import, so later changes are ignored, and any code path that sets the environment after import has no effect. - **The cost is paid by every process that merely imports the module** — including a `--help` invocation, a test collection run that imports the module without calling anything, a documentation build, and every worker process a server forks or spawns. - **Failures at decoration time are import failures.** An exception in a decorator body surfaces as an `ImportError`-shaped traceback from the import statement, not from any call, which makes it a confusing place to do fallible work such as opening a file or a socket. Keep the decorator body cheap, deterministic and side-effect-free where you can; put fallible or configuration-dependent work in the wrapper, guarded so it happens on first call. ### Consequences for control `@` is unconditional: the decoration happens when the module executes, so you cannot express "decorate only in production" with the `@` line alone. The two workable shapes are to decide inside the wrapper at call time — checking a flag that later configuration can change — or to skip the `@` and rebind the name by hand under a condition. And because decoration is once-per-process, a decorated function cannot be undecorated at runtime except by rebinding the name to something else.