How do you make a Python decorator remember state, such as a call count, between calls?

A decorator is just a callable that takes a function and returns a replacement. `@count_calls` above `def settle(...)` is exactly `settle = count_calls(settle)`, and that assignment happens once, while the module is being executed. The wrapper it returns is what runs on every subsequent call. That two-phase structure is the whole answer to "where does state live": the decorator body is the setup phase that runs once, the wrapper body is the per-call phase, and state has to be created in the first so it can be seen from the second. **Why a plain local does not work.** If you write `calls = 0` inside the wrapper, it is recreated on each call and always reads zero. If you write `calls = 0` in the decorator body and then `calls += 1` in the wrapper, the compiler sees an assignment to `calls` inside the wrapper and classifies it as a *local* of the wrapper, so the read on the right-hand side finds nothing bound yet and Python raises `UnboundLocalError`. The declaration `nonlocal calls` at the top of the wrapper tells the compiler that the name belongs to the enclosing decorator scope, and rebinding then updates the shared value. **Three idioms, in the order you will meet them.** 1. *Closure plus `nonlocal`.* `calls = 0` in the decorator body, `nonlocal calls` then `calls += 1` in the wrapper. Clean, but the value is awkward to read from the outside: the caller only has the wrapper, and the counter is hidden inside it, so you end up exposing an accessor. 2. *Closure over a mutable object.* `stats = {"calls": 0}` in the decorator body, `stats["calls"] += 1` in the wrapper. No `nonlocal` is needed because you are mutating an object rather than rebinding a name. This is the usual shape when the state is a cache dict, a deque of timestamps for a rate limiter, or a set of seen keys. 3. *An attribute on the wrapper.* `wrapper.calls = 0` after defining the wrapper, `wrapper.calls += 1` inside it. Functions are ordinary objects with a `__dict__`, so this works, and it gives the outside world a name to read and reset: `settle.calls`, `settle.calls = 0`. Set the attribute *after* applying `functools.wraps`, because `wraps` copies the wrapped function's `__dict__` over the wrapper's and can overwrite what you set first. **One state object per decorated function.** Because the decorator runs once per `@` line, each decorated function gets its own closure and therefore its own counter. Decorating `settle` and `refund` with the same decorator gives two independent counters; a module-level global would instead give one shared counter and is the classic wrong answer. The flip side is that the state is per *function*, not per call site and not per instance: decorate a method in a class body and every instance of that class shares the one counter, because there is exactly one function object in the class. **Lifetime and reset.** The state lives as long as the wrapper does, which for a module-level function means as long as the process. Nothing evicts it, so a counter is harmless but a growing cache dict is not - give anything unbounded an explicit way to clear it, such as `wrapper.cache = cache` plus a documented `clear()`. **Reading and resetting it.** Whichever idiom you pick, decide deliberately how the state is read back and cleared. An attribute makes both trivial - `settle.calls` reads it, `settle.calls = 0` resets it - while a `nonlocal` variable needs an accessor and a setter you write by hand. This matters most in tests: the state persists for the process, so a test that asserts a count sees whatever earlier tests left behind, and a suite that passes alone but fails in a full run is the classic symptom. Reset the state in setup rather than relying on test order. **Thread safety.** `calls += 1` compiles to a read, an add and a store. Those steps can interleave across threads, so counts can be lost; if the number matters, guard it with a `threading.Lock` or use an inherently atomic operation such as `itertools.count().__next__`. This matters more on the free-threaded build, where no global lock coarsely serializes bytecode. **When to reach for a class instead.** Once the state is more than one counter, or you want methods that inspect and reset it, a class implementing `__init__` and `__call__` reads better than a closure with attributes bolted on: the state becomes plain instance attributes. The tradeoff is that the decorated name is then an instance rather than a function, which changes what introspection and other tooling see.