__init_subclass__ and Subclass Hooks

## What the hook is `__init_subclass__` arrived in Python 3.6 with PEP 487, "Simpler customisation of class creation". PEP 487 added two hooks — this one and `__set_name__` — with an explicit goal: remove the most common reason people reached for a metaclass, which was wanting to run a little code every time somebody subclassed a base class. Defining it is enough. There is no registration step, no custom metaclass, and no import-time magic: ```python class Plugin: registry = {} def __init_subclass__(cls, /, **kwargs): super().__init_subclass__(**kwargs) Plugin.registry[cls.__name__] = cls ``` ## Exactly when it runs Executing a class statement compiles the class body into a function, runs it to produce a namespace mapping, and hands name, bases and namespace to the metaclass — `type` unless you say otherwise. Inside `type.__new__` the class object is built first, and then, in this order, two hooks fire: every object in the *new* namespace that defines `__set_name__` is notified of its owner and attribute name, and only then is `__init_subclass__` called. The lookup is the part that matters. `type.__new__` does the equivalent of `super().__init_subclass__(cls=new_class, **class_keywords)` where the search starts at the class *after* the new one in its MRO. Two consequences follow directly: * The hook never runs for the class that defines it. When `Plugin` above is created, the search begins at `object`, and `object.__init_subclass__` is a do-nothing default. * It runs for descendants at any depth. A subclass of a subclass triggers it again, because the hook is inherited and the lookup finds it wherever it lives on the MRO. Interviewers probe this constantly, because code that assumes "direct children only" is a bug waiting for the first refactor that inserts an intermediate class. Both hooks run *inside* class creation, which means the class name is not yet bound in the enclosing module or function namespace when your hook body runs. You get the class object as `cls`; you cannot look it up by name yet. ## Why it is a classmethod without the decorator When a class body defines `__init_subclass__` as a plain function, class creation wraps it in `classmethod` for you. `__class_getitem__` gets the same implicit treatment; nothing else in the data model does. So the first parameter is the new subclass, not an instance. Adding `@classmethod` yourself is legal and harmless — the wrapping is idempotent — but it is not required, and an interviewer will read a `self` parameter there as a sign you have never actually used the hook. The conventional signature is `def __init_subclass__(cls, /, **kwargs)`. The `/` marks `cls` as positional-only, which frees the *name* `cls` for use as a class-header keyword; without it, `class C(Base, cls="x")` would collide with the first parameter. ## The cooperative super() call `object.__init_subclass__` accepts no keyword arguments at all: forwarding an unconsumed keyword to it raises `TypeError` at class-definition time. That is deliberate — a typo in a class header fails loudly at import rather than being silently ignored. The discipline is therefore: consume the keywords you own, forward the rest. ```python class Base: def __init_subclass__(cls, /, tag=None, **kwargs): super().__init_subclass__(**kwargs) cls.tag = tag ``` Skipping the `super()` call breaks cooperation: if two bases in a multiple-inheritance chain both define the hook, only the first one on the MRO runs, and the second silently stops working. Because the hook is looked up cooperatively, the same rules that govern any cooperative method chain apply here. ## What people actually use it for Four patterns dominate real code. **Registration**: the base keeps a mapping of subclasses so a factory can dispatch on a name. **Validation**: reject a subclass at import time if it forgot a required attribute or gave one the wrong type — `raise TypeError(...)` inside the hook makes the class statement itself fail. **Injection**: derive and attach an attribute, such as a slug computed from the class name. **Wrapping**: replace a method the subclass defined with an instrumented version. ## When something else is a better fit A class decorator registers exactly the class you decorate — opt-in, obvious in the source, and immune to inheritance surprises, at the price of being easy to forget. `__init_subclass__` is opt-out: it catches everything, including intermediates you did not mean to catch. A metaclass is still needed when you must control the namespace *before* the body executes or change how instances and subclass checks behave — but reaching for one merely to react to subclassing is the over-engineering that PEP 487 was written to retire.