Why can a class-decorator registry leak memory in a long-running service, and how do you bound it?

### The pattern The registry is the most common real use of a class decorator, and one of the strongest arguments for the shape: ```python HANDLERS = {} def register(cls): HANDLERS[cls.language_pair] = cls return cls ``` Each decorated class adds itself to a lookup table as its class statement executes, so a dispatcher can find implementations by key without importing each one by name. Because decoration happens once, while the defining module is imported, the registry is populated as a side effect of import and is complete before any request is served. ### Why it is normally safe For classes written at module level, the number of registrations equals the number of `class` statements in the source. That is a fixed, small number. The registry holds strong references forever, but "forever" here means "for the life of the process", and those classes were going to live that long anyway -- their module holds a reference too. ### Where the leak comes from The failure mode appears when classes stop being source-level constants. Consider a translation-memory updater that builds a small handler class per language pair, per tenant, or per document batch, inside a factory function called on the request path. Each call now creates a *new class object*, and the registry pins it. At a 1,200-request-per-minute peak that is up to 72,000 new class objects per hour that can never be freed. A class is an unusually expensive thing to leak. Holding a class alive also holds its `__dict__`, every function object it contains, each function's default arguments and closure cells, its annotations, its docstrings, and -- through the functions' `__globals__` -- the entire module namespace it was defined in. A leaked class is rarely a few hundred bytes; it is a subgraph. Classes are also cyclic by construction: the class references its methods, the methods reference the class through their globals, and the type's own attributes point back at it. So a class is never freed by refcounting alone; it requires the cycle collector. That is why the leak looks *gradual and jagged* rather than instant -- collections keep running and keep failing to free anything, because the registry is a live root. ### Confirming the diagnosis The registry itself is the cheapest instrument: log `len(HANDLERS)` periodically. If it climbs with traffic rather than settling after startup, the case is closed without any profiling. Beyond that, `tracemalloc` snapshots taken minutes apart and diffed will point at the factory's line, and counting class objects in `gc.get_objects()` distinguishes "leaking classes" from "leaking instances", which is a completely different bug with a completely different fix. ### The fixes, in order **1. Do not generate classes per request.** This is almost always the real answer. A class generated per language pair is a class whose only difference from its siblings is data; make it one class with the pair as an instance attribute, or as a key into a table. Dynamic class creation belongs at configuration-load time, not on a request path. **2. Make the registry hold weak references.** When classes genuinely must be created at runtime, `weakref.WeakValueDictionary` lets the entry vanish once nothing else refers to the class: ```python import gc import weakref REGISTRY = weakref.WeakValueDictionary() def register(cls): REGISTRY[cls.language_pair] = cls return cls ``` Because classes participate in reference cycles, an entry does not disappear the instant the last strong reference goes away -- it disappears at the next cycle-collection pass. That is fine for bounding memory and confusing during a five-line experiment, which is why an explicit `gc.collect()` belongs in the test that proves it works. **3. Deregister explicitly.** If the lifetime is genuinely owned by something -- a tenant teardown, a config reload -- delete the key when that owner goes away. This is the most predictable option and the easiest to get wrong, because every early-return and exception path has to honour it. ### The design lesson A registry decorator quietly converts *"this class exists"* into *"this class is reachable from a module global for the life of the process"*. That promotion is invisible at the call site; nothing in `@register` above a class statement suggests a lifetime decision. When the decorated thing is a source-level class the promotion is free, and when it is a runtime-generated class it is a leak. Deciding which case you are in is the whole question.