When do you choose a class decorator over a mixin base class or a metaclass?

### Three tools, one axis All three mechanisms add behaviour to classes; they differ in **when they run, how far they reach, and what they cost to undo**. | | runs | reaches subclasses | shows in `isinstance` | composes with others | |---|---|---|---|---| | class decorator | after the class is built | no | no | freely | | mixin base class | at attribute lookup | yes | yes | via MRO, usually fine | | metaclass | during class creation | yes | no | badly | ### The class decorator A decorator is called with the finished class and returns it, usually after mutating it. It is opt-in per class, written at the point of use where a reader will see it, adds nothing to the method resolution order, and can be deleted by removing one line. It cannot influence how the class was built, and crucially **it does not apply to subclasses**: ```python def sealed(cls): cls.sealed = True return cls @sealed class Base: pass class Child(Base): pass print(Base.sealed) # True print("sealed" in Child.__dict__) # False print(Child.sealed) # True, found on Base by lookup ``` `Child` inherits the *attribute* but the decorator never ran for it, so any per-class work -- registering, validating, generating methods from that class's own annotations -- silently skipped it. That single property decides most real choices: if forgetting the decorator on a subclass is a bug someone will make, a decorator is the wrong mechanism. ### The mixin base class A mixin is ordinary inheritance. Its methods are found through the MRO, subclasses get them automatically, overriding works with `super()` cooperation, and `isinstance(obj, Mixin)` is true -- which is exactly right when the behaviour is part of the object's identity and callers may reasonably branch on it. The costs are structural: it consumes a base-class slot, it becomes part of every subclass's MRO forever, and removing it later is a breaking change for anyone who type-annotated against it. It also cannot easily add *class-level* facts derived from the class itself, which is a decorator's speciality. ### The metaclass A metaclass participates in class creation, so it can inspect or rewrite the namespace before the class object exists, and -- unlike a decorator -- it runs for every subclass automatically. That is its unique power: policies that must not be forgettable. The price is composability. Metaclasses are inherited, and two base classes whose metaclasses are unrelated cannot be combined at all; the class statement fails outright. Library authors who ship a metaclass constrain every user of their hierarchy, which is why abstract base classes and their `ABCMeta` are conspicuous, deliberate exceptions rather than a pattern to copy. Since 3.6, `__init_subclass__` on a base class covers a large share of what metaclasses were used for -- running per-subclass hook code -- without a custom metaclass and without the conflict problem. That has moved the decision boundary: today a metaclass earns its keep mainly when you must intervene *before* the class object exists. ### How to actually decide 1. **Does it need to reach subclasses automatically?** If yes, a decorator is out; use a base class with `__init_subclass__`, or a metaclass if you must act before creation. 2. **Should callers see it in the type?** If `isinstance` should be true, that is inheritance, not decoration. 3. **Is it per-class data derived from the class itself?** Generated comparison operators, registration keys, computed attributes -- decorator territory, and the stdlib agrees: `@dataclasses.dataclass`, `@functools.total_ordering` and `@enum.unique` are all decorators. 4. **How reversible does it need to be?** A decorator is one line; a base class is in every subclass's MRO and in every annotation someone wrote. ### The organisational angle These mechanisms differ in how they behave in a codebase with many hands. A decorator is greppable and local: a reader sees `@register` above the class and knows something happened. A metaclass acts at a distance -- a class three levels down a hierarchy is transformed by code the reader may never open -- which is precisely why it is both powerful for enforcement and expensive for comprehension. When the goal is a rule the organisation must not break, invisibility is the feature; when the goal is a convenience, invisibility is a tax on everyone who debugs it later. One practical caveat for either generated-code approach: static type checkers do not execute your decorator, so attributes it injects are invisible to them unless you declare them. `typing.dataclass_transform`, added in 3.11, exists for exactly this -- it lets a decorator that generates dataclass-like methods tell checkers what it produces. Weigh that in: a mechanism your tooling cannot see is a mechanism your team debugs at runtime.