Why does an @functools.lru_cache-wrapped formatter in an invoice-PDF renderer keep returning the previous currency format after a global setting changes, and how do you fix it?

## The bug class: an input that never reaches the key Memoization is only sound when the function is a function *of its arguments*. The moment the body reads something the caller did not pass — a module global, an environment variable, a process-wide setting, a file, a clock, a row in a database — the cache is keyed on a strict subset of the real inputs. Every hit after that hidden input changes is a wrong answer, delivered fast. ```python import functools CURRENCY = "USD" @functools.lru_cache def render(amount): return f"{amount:.2f} {CURRENCY}" print(render(12.5)) # 12.50 USD CURRENCY = "EUR" print(render(12.5)) # 12.50 USD <- stale hit render.cache_clear() print(render(12.5)) # 12.50 EUR ``` Nothing here is malfunctioning. The wrapper did exactly what it promised: same key, same answer. The defect is the design that put a second input outside the signature. ## Diagnosis The symptom in an invoice renderer is oddly shaped: most output is right, and a subset — usually the rows rendered right after a settings change, or the rows produced by whichever worker warmed the cache first — carries the old format. Three moves narrow it quickly. First, read `cache_info()` around the failing operation. High `hits` with wrong output points at staleness. The opposite reading — `hits` near zero with `currsize` climbing — is a different problem entirely: the key contains something that varies per call, so nothing is being reused and the cache is only costing you memory. Second, call `render.__wrapped__(amount)` and compare. If the undecorated function is right and the wrapper is wrong, the cache is the story and you can stop looking at the formatting code. Third, read the body for every name it uses that is not a parameter. Globals, `self` attributes mutated elsewhere, module-level configuration objects and anything imported at module scope are all candidates. This is a mechanical review step and it finds the bug more reliably than reasoning about it does. ## Fixes, in the order you should prefer them **Widen the key.** Make the hidden input a parameter. It is the only fix that restores the invariant the cache depends on, it makes the cache correct under concurrency for free, and it usually improves the hit rate because entries for different settings coexist instead of thrashing: ```python import functools @functools.lru_cache(maxsize=340) def render(amount, currency): return f"{amount:.2f} {currency}" ``` The caller now passes what it already knew. If the setting is threaded through several layers, that is a signal about the design, not an argument for keeping the global. **Bind the cache to the right lifetime.** If the setting belongs to a render job rather than to the process, a module-level cache is the wrong scope: the cache outlives the thing it is valid for. Move the memo onto an object whose lifetime matches the setting, so a new job starts with an empty one and nothing needs invalidating. **Clear on change.** `cache_clear()` when the setting flips is the blunt instrument. It works in a single-threaded batch. It is unsatisfying because it is global — every caller of that function loses its entries — and it is genuinely unsafe under threads, since another thread can miss, read the old global and repopulate the cache in the window around the change. Treat it as a stopgap you can explain, not a design. **Do not cache.** If the function is cheap and impure, the cache was never buying enough to justify the invariant it needs. ## The test-suite variant A 340-case regression pack that runs in one process shares module-level caches across every case. A case that renders under one currency warms an entry; a later case under a different currency reads it. The failures are order-dependent, they vanish when the failing case is run alone, and they will move around as cases are added — the most expensive kind of flake to chase. The remedies are the same in priority order: parameterise so the entries cannot collide; failing that, clear the cache in per-test teardown so each case starts cold; failing that, do not put a process-lifetime cache under code the suite is meant to vary. ## What to say about it in review A cache is a promise that a function's answer depends only on what you hand it. When you approve a `@functools.lru_cache` on a function, you are approving that promise. The two questions worth asking every time are *what else does this body read?* and *what would make an entry wrong rather than merely old?* — because there is no TTL to bail you out and no size setting that bounds staleness. A stale-cache bug is a correctness bug wearing a performance decorator, and it is discovered in the output, days after the change that caused it.