Why can an `__init_subclass__` registry register the same handler twice, and how do you make it idempotent?

## The failure, concretely Take a translation-memory updater whose segment handlers self-register: a `Handler` base keeps a list, and `__init_subclass__` appends every subclass to it. The updater walks the list and lets each handler write matching segments into the memory. A 340-case regression pack that used to be clean starts reporting that every translation-memory write lands twice — the same segment updated once, then updated again — and only for some handlers. This is the classic duplicated side effect of automatic registration, and it has two independent causes that look identical from the outside. ## Cause one: the hook is opt-out and depth-unaware `__init_subclass__` runs for every descendant at any depth, not for direct children only. So: * A thin subclass — `class TmxV2(Tmx)` adding one attribute, or a test double subclassing the real handler to override a single method — registers *in addition to* its parent. Dispatch then finds two handlers claiming the same format, and each performs the write. * Abstract intermediates register too. A `BaseFileHandler` that exists only to share code has no business being in a dispatch list, but nothing stops it from landing there. * Anything defined inside the test suite registers into the same global registry and stays there for the rest of the process, which is why a bug like this often appears only under the full regression pack and not when a single case is run. ## Cause two: one source file, two class objects Class identity is per-import, not per-file. The same module executed as `__main__` *and* imported by its package name produces two distinct class objects with the same `__qualname__`. The same happens when two `sys.path` entries reach the same file by different paths, when a package is importable both as `pkg.mod` and as `mod`, and when something calls `importlib.reload`, which re-executes the class statements and fires the hook again. A registry keyed by name would overwrite and hide this; a registry that appends to a list keeps both and doubles the work. Neither is what you want: you want the second registration to be *noticed*. ## Making it idempotent The shape that survives contact with real codebases has three properties. **Registration is explicit.** Use a class-header keyword as the registry key and treat its absence as "not a registered handler". That single change removes intermediates, mixins and test subclasses from the registry without any special-casing: ```python class Handler: registry = {} def __init_subclass__(cls, /, key=None, **kwargs): super().__init_subclass__(**kwargs) if key is None: return ... ``` **The registry is a mapping, not a list.** Appending can never be idempotent; assigning under a key can be. **A collision is loud.** If the key already maps to a *different* class object, raise. That converts the double-import case into an import-time error naming both classes, which is diagnosable in seconds, instead of a duplicated write discovered by a regression pack. Comparing with `is` rather than by name matters: two class objects from a double import have identical names and different identities, and identity is the thing you care about. ## Diagnosing it when it is already happening Print the registry with `id()` and `__module__` for each entry. Two entries with the same `__qualname__` and different ids is the double-import signature; a parent and a child both present is the depth signature. `sys.modules` will show the same file under two keys in the first case. From there the fix is either an import-path correction or the guarded registry above. ## Second-order concerns A class registry holds strong references, so every registered class — and through it, its module and any closures it captured — lives for the life of the process. That is fine for a fixed set of handlers loaded at startup and a genuine leak for classes generated per request or per document; `weakref.WeakValueDictionary` is the tool when the registry must not keep its entries alive. And registration only happens if the defining module is actually imported. `__init_subclass__` cannot discover a plugin nobody imported: you still need an explicit import sweep or a distribution entry point read through `importlib.metadata` to get the modules loaded. Self-registration solves bookkeeping, not discovery. ## When to abandon self-registration If the surprises keep coming — intermediates, test subclasses, conditional imports — a class decorator that registers exactly the class it decorates is the honest alternative. It is opt-in, it is visible at the definition site, and it never fires for a subclass you did not write. The cost is that someone can forget it; the benefit is that nothing happens by accident.