Metaclass Patterns

Also Known As

TL;DR

Explanation

A metaclass is the class of a class. By default, every class in Python has type as its metaclass; setting metaclass=Meta lets you intercept class creation via Meta.__new__ and Meta.__init__, running code before the class object exists. Common patterns: (1) Registry — automatically register every subclass in a dict for plugin discovery or serializer lookup. (2) ORM column collection — frameworks like Django and SQLAlchemy's legacy declarative system walk the class namespace, find Column/Field descriptors, and assemble a schema attached to the class. (3) Abstract enforcement — ABCMeta uses metaclass machinery to refuse instantiation of classes with unimplemented @abstractmethod members. (4) Attribute validation — reject classes that violate naming conventions or are missing required attributes at definition time, not at first use.

Since Python 3.6, __init_subclass__ and __set_name__ cover the majority of real-world needs without a metaclass — subclass registration, descriptor wiring, and per-class configuration are all simpler with these hooks. Reach for a metaclass only when you need to modify the class namespace before the class is created (e.g. controlling MRO, customizing __prepare__ to use an ordered or specialized mapping, or making isinstance/issubclass lie via __instancecheck__).

Metaclass conflicts are the main practical hazard: multiple inheritance from classes with different metaclasses fails unless one metaclass is a subclass of the other. This frequently breaks when mixing ABC with a framework that has its own metaclass. Document any metaclass clearly, prefer composition with __init_subclass__, and never use a metaclass purely for syntactic sugar — the readability cost for downstream maintainers is significant.

Common Misconception

Why It Matters

Common Mistakes

• Using a metaclass for subclass registration when __init_subclass__ does the same in five lines.
• Mixing classes with incompatible metaclasses and getting cryptic 'metaclass conflict' errors at import time.
• Forgetting that metaclass code runs at class definition time, not at instance creation — side effects fire on import.
• Returning from Meta.__new__ without calling super().__new__, breaking the type machinery silently.
• Using a metaclass purely to add methods that a simple class decorator or mixin would provide more transparently.

Avoid When

• A class decorator, mixin, or __init_subclass__ achieves the same result.
• The codebase mixes with frameworks (Django, ABC, Pydantic) whose own metaclasses may conflict.
• Junior-heavy teams where the indirection cost outweighs any DRY benefit.

When To Use

• Building an ORM or schema framework that needs to inspect and transform the class namespace at definition time.
• Implementing custom isinstance/issubclass behavior via __instancecheck__ and __subclasscheck__.
• Enforcing structural invariants on every subclass before the class object becomes accessible.
• Customizing __prepare__ to control the namespace mapping used during class body execution.

Code Examples

# Heavy metaclass just to register subclasses:
class PluginMeta(type):
    registry = {}
    def __new__(mcs, name, bases, namespace):
        cls = super().__new__(mcs, name, bases, namespace)
        if bases:  # skip base class
            PluginMeta.registry[name] = cls
        return cls

class Plugin(metaclass=PluginMeta):
    pass

class JsonPlugin(Plugin):
    pass

# Mixing with ABC fails: metaclass conflict
# class AbstractPlugin(Plugin, ABC): ...  # TypeError

# Modern equivalent with __init_subclass__ — no metaclass needed:
class Plugin:
    registry: dict[str, type] = {}

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        Plugin.registry[cls.__name__] = cls

class JsonPlugin(Plugin):
    pass

# Genuine metaclass use: ORM column collection at class creation.
class Column:
    def __set_name__(self, owner, name):
        self.name = name

class ModelMeta(type):
    def __new__(mcs, name, bases, namespace):
        columns = {k: v for k, v in namespace.items() if isinstance(v, Column)}
        cls = super().__new__(mcs, name, bases, namespace)
        cls.__columns__ = columns
        return cls

class Model(metaclass=ModelMeta):
    pass

class User(Model):
    id = Column()
    email = Column()
# User.__columns__ == {'id': ..., 'email': ...}

References

• https://docs.python.org/3/reference/datamodel.html#metaclasses
• https://peps.python.org/pep-3115/
• https://peps.python.org/pep-0487/

Tags

Related Terms