Why is module-level mutable state rebound with `global` risky in a long-running collector service?

### What the phrase means "Module-level mutable state" is a name in a module namespace bound to something mutable -- a dict, a list, a counter -- that functions in the file read and, with a `global` declaration, rebind. It is the path of least resistance: no parameter to thread, no object to construct, importable from anywhere. Take a sensor-telemetry collector as the running example: one module owns `READINGS = {}`, every ingest function writes into it, and a `reset()` function does `global READINGS; READINGS = {}` between runs. It works on the first day and it costs you on every day after. ### Cost 1: the state is created at import time A module-level binding is created the first time the module is imported, and its creation is therefore entangled with import order. Two things go wrong. **Import cycles.** If the collector module imports the sensor-driver module and the driver imports the collector back to reach `READINGS`, one of them runs against a **partially initialised** module. The name may not be bound yet, and a circular import at startup then surfaces as an `ImportError` or an `AttributeError` from a line that looks unrelated -- and only in whichever import order the entry point happens to produce. State that is created inside a function called from `main()` cannot have this problem, because nothing about it depends on which module was imported first. **Aliasing.** `from collector import READINGS` copies the *reference* into the importing module's namespace. A later `global READINGS; READINGS = {}` rebinds the attribute on the collector module only -- every importer still holds the old dict, and now two halves of the system are writing to different objects with no error anywhere. This is the single most common concrete bug in this area, and it is why `import collector` plus `collector.READINGS` is the safer form when module-level mutable state exists at all. ### Cost 2: the state outlives every test Module state is created once per process and then persists. Tests run in one process, so whatever the first test wrote is still there for the second: suites start passing or failing depending on order, and a test that passes alone fails in the suite. The workaround is to patch the module attribute per test, for example with `unittest.mock.patch`, or to call a `reset()` in setup -- which means every test must remember, and a new one that forgets breaks a different test rather than itself. Treat that as a stopgap; the durable fix is state a test can simply construct. ### Cost 3: nothing scopes the lifetime to a unit of work During a six-hour nightly collection run, an accumulator keyed by sensor and timestamp only grows. There is no natural point at which it is discarded, because its lifetime is the process, not the run. You end up adding manual pruning, and manual pruning is a thing to get wrong. When the same state belongs to a run object created at the start of the run, the memory is reclaimed when the run ends, for free, and a second concurrent run is simply a second object rather than a design problem. ### Cost 4: nobody owns it, and no signature says so A function that writes to a module-level dict has a signature that lies: it looks like a pure transformation and it is not. You cannot tell from a call site that state changed, you cannot enumerate the writers without grepping for the `global` statement and every mutating method call, and you cannot reason about a function in isolation. That is a review and onboarding cost that compounds with the size of the module. ### Cost 5: "global" is not as global as it sounds Two mechanisms give you a second copy of the state whether you wanted one or not. `importlib.reload` creates fresh module-level bindings while old references to the previous objects survive. And in Python 3.14 the standard library's multiple-interpreters support (PEP 734) gives each interpreter its own imported copy of a module, so a module-level name is per-interpreter, not per-process. Code that assumes "there is exactly one of these in the process" is making an assumption the language does not guarantee. ### What is fine, and what the fix looks like Module scope itself is not the problem; *mutability plus rebinding* is. Constants -- a timeout, a URL template, a tuple of field names -- are bound once at import, read without any declaration, and never rebound, so none of the costs above apply. The one defensible `global` is a lazily-built resource behind a single accessor function that owns both the read and the write, and even that should expose a way to reset it for tests. Everything else becomes an object created at the entry point and passed down: ```python class Collector: def __init__(self): self._readings = [] def record(self, value): self._readings.append(value) def average(self): return sum(self._readings) / len(self._readings) ``` `main()` builds one, hands it to the ingest functions, and drops it when the run ends. Tests construct their own and need no patching. Import order becomes irrelevant, because nothing happens at import. Two runs can coexist. And the signature of every function that touches the collector now says so.