Decorating Classes

### The transform, stated exactly The `@` on a class is the same `@` as on a function; only the decorated object differs. When the interpreter reaches ```python @deco class C: ... ``` it executes the class body to completion, hands the resulting namespace to the metaclass (`type`, unless the class says otherwise), gets back a finished class object, and *only then* calls `deco` with that object. The name `C` is then bound to the return value. The equivalent longhand is: ```python class C: ... C = deco(C) ``` That is the entire mechanism. Everything else about class decorators follows from it. ### Consequence 1: the class is already finished By the time the decorator runs, the class exists. Its methods are attributes in `cls.__dict__`, `cls.__name__` and `cls.__qualname__` are set, its bases are recorded and its method resolution order is computed. A class decorator can therefore *inspect and mutate*, but it cannot change how the class was constructed -- it cannot alter which metaclass ran, and it cannot retroactively add `__slots__`, because slot descriptors have to exist before the class object is laid out. Anything that must intervene *during* creation belongs to a metaclass or to `__init_subclass__` on a base class. ### Consequence 2: mutate and return `cls` is the normal shape The common body is three lines: do something with the class, then hand it back. ```python def tagged(cls): cls.tag = cls.__name__.lower() return cls ``` Mutation is done with plain attribute assignment or `setattr`, and it affects the one class object every future instance and subclass will look through. Typical work: attaching a computed attribute, appending the class to a registry, adding generated methods, or validating that required methods exist and raising at import time if they do not. ### Consequence 3: forgetting `return cls` is the classic bug A decorator with no explicit `return` returns `None`, so the class name is bound to `None`. The class statement appears to succeed and the failure surfaces later as `TypeError: 'NoneType' object is not callable` on the first instantiation. Nothing checks the return type, because a decorator is just a call. ### Consequence 4: returning a different object is legal Returning a function, an instance, or an entirely new class is permitted and occasionally deliberate, but it changes what the name means. Callers who wrote `isinstance(x, C)` or `class Sub(C):` are now talking about the replacement, and tools that follow the source will disagree with the runtime. The stdlib does this in exactly one well-known place: `@dataclasses.dataclass(slots=True)`, added in 3.10, must build a *new* class because slots cannot be added after the fact -- the plain `@dataclasses.dataclass` form returns the same class object it was given. Rebuilding a class also silently discards anything that captured the original, such as an already-registered reference or a closure over `__class__`. ### Decoration runs once, at class-creation time For a module-level class the decorator body executes while the defining module is imported, exactly once, no matter how many instances are made. That makes class decorators a natural place for registration and import-time validation, and a bad place for anything expensive or order-dependent. It also means subclasses do **not** re-run it: decorating a base class runs the decorator on that base only, and subclasses merely inherit whatever attributes it left behind. ### Stdlib class decorators to name in an interview `@dataclasses.dataclass`, `@functools.total_ordering`, `@enum.unique` and `@typing.runtime_checkable` are all class decorators, and all but the `slots=True` dataclass form return the same class object after mutating it. Being able to say *"`@enum.unique` checks for duplicate values and returns the same enum class"* demonstrates that you understand the shape rather than having memorised one example. ### The mental checklist Given any class decorator, four questions settle its behaviour: what does it receive (the finished class), when does it run (once, at class-statement time), what does it return (usually the same class), and does the name still mean what the reader thinks it means (only if it returned the same class). Those four cover almost every real bug in this area.