Python Metaclasses Tutorial

The Story That Explains Metaclasses

Everything Is an Object — Including Classes

Python has one central truth that unlocks metaclasses: classes are objects too. You can pass them around, store them in lists, assign new attributes to them, and — the key part — they were themselves created by another class. That creator class is type.

class Dog:
    pass

buddy = Dog()

# buddy is an instance of Dog
print(type(buddy))         # <class '__main__.Dog'>

# Dog is an instance of type — that's the metaclass level
print(type(Dog))           # <class 'type'>

# type is itself an instance of type — the recursion stops here
print(type(type))          # <class 'type'>

# Classes have __class__ pointing to their metaclass
print(Dog.__class__)       # <class 'type'>

Animated Diagram — The Three-Level Hierarchy

Trace the "what is it an instance of?" arrow at each level. The individual dog is an instance of the Dog class. The Dog class is an instance of type. type is an instance of itself — the top of the chain.

Creating a Class Dynamically With type()

Because type is the metaclass, calling it with the right arguments creates a class from scratch — no class keyword needed. This is the machinery Python uses internally every time you write a class.

# These two forms produce IDENTICAL classes — Python translates one into the other

# Form 1 — the class keyword you already know
class Dog:
    species = "Canis familiaris"
    def bark(self):
        return f"{self.species} says woof"


# Form 2 — same thing, built by calling type() directly
def bark(self):
    return f"{self.species} says woof"

Dog2 = type(
    "Dog2",                                    # class name
    (),                                          # base classes
    {"species": "Canis familiaris", "bark": bark}    # namespace
)

# Both work identically
print(Dog().bark())       # Canis familiaris says woof
print(Dog2().bark())      # Canis familiaris says woof
print(type(Dog) is type(Dog2))   # True — both classes have type() as their metaclass

Your First Custom Metaclass

To write a metaclass, subclass type. Override its __new__ or __init__ to run code every time a class using your metaclass is defined. Then attach it via metaclass=YourMeta in the class header.

class LoggingMeta(type):
    """A metaclass that announces every class defined with it."""

    def __new__(mcs, name, bases, namespace):
        print(f"[LoggingMeta] creating class {name!r} with {len(namespace)} attrs")
        # Delegate the real creation to type
        cls = super().__new__(mcs, name, bases, namespace)
        # Free to modify the class here — inject methods, add attributes...
        cls.created_at = "2026-07-12"
        return cls


class Cat(metaclass=LoggingMeta):
    def meow(self):
        return "meow"


class Dog(metaclass=LoggingMeta):
    def bark(self):
        return "woof"


# The metaclass injected created_at into every class
print(Cat.created_at)    # 2026-07-12
print(Dog.created_at)    # 2026-07-12

# type() confirms the metaclass
print(type(Cat))         # <class '__main__.LoggingMeta'>
print(type(Dog))         # <class '__main__.LoggingMeta'>

Animated Diagram — The Metaclass Intercepts Class Creation

Watch what happens when Python encounters class Dog(metaclass=LoggingMeta):. Before the class object even exists, Python calls LoggingMeta.__new__. Your metaclass sees the raw name, bases, and namespace — and can validate, decorate, or reject before handing back the finished class.

What Do Metaclass __new__, __init__, and __call__ Control?

class Meta(type):
    def __new__(mcs, name, bases, namespace):
        print(f"  [Meta.__new__]  creating class {name!r}")
        return super().__new__(mcs, name, bases, namespace)

    def __init__(cls, name, bases, namespace):
        print(f"  [Meta.__init__] class {name!r} is ready")
        super().__init__(name, bases, namespace)

    def __call__(cls, *args, **kwargs):
        print(f"  [Meta.__call__] creating an instance of {cls.__name__}")
        return super().__call__(*args, **kwargs)


print("Defining Dog:")
class Dog(metaclass=Meta):
    def __init__(self, name):
        self.name = name

print("\nCreating buddy:")
buddy = Dog("Buddy")

Practical Example 1 — Enforcing Class-Design Rules

A metaclass that validates every class it produces. Here we enforce that every public method's name must be lowercase — a small stand-in for real coding standards you might want to enforce across a codebase.

class SnakeCaseMeta(type):
    """Every public method must be snake_case (lowercase)."""

    def __new__(mcs, name, bases, namespace):
        for attr_name, attr_value in namespace.items():
            # Only check callable, public attributes
            if callable(attr_value) and not attr_name.startswith("_"):
                if not attr_name.islower():
                    raise TypeError(
                        f"In class {name!r}: method {attr_name!r} "
                        "must be lowercase (snake_case)"
                    )
        return super().__new__(mcs, name, bases, namespace)


# ── This class is fine — all methods are snake_case ──
class Good(metaclass=SnakeCaseMeta):
    def do_something(self):
        return "ok"

    def save_to_disk(self):
        return "saved"

print("Good class created successfully")


# ── This class violates the rule — refused at DEFINITION time ──
try:
    class Bad(metaclass=SnakeCaseMeta):
        def DoSomething(self):        # PascalCase — not allowed
            return "nope"
except TypeError as e:
    print("Blocked:", e)

Practical Example 2 — Auto-Registry of Subclasses

A metaclass that quietly keeps track of every subclass ever defined. Add a new plugin, and it auto-registers itself — no manual bookkeeping. This is the pattern behind plugin systems, ORM model discovery, serializer registries, and much more.

class PluginRegistry(type):
    """A metaclass that auto-registers every subclass into a shared registry."""

    registry = {}    # class-level dict — one for the entire metaclass

    def __init__(cls, name, bases, namespace):
        super().__init__(name, bases, namespace)
        # Don't register the base "Plugin" itself — only its children
        if bases:
            PluginRegistry.registry[name] = cls
            print(f"[registry] Registered {name}")


# The base class — not registered because it has no bases
class Plugin(metaclass=PluginRegistry):
    def run(self, msg):
        raise NotImplementedError


# Every subclass is automatically added to the registry — no manual work
class EmailPlugin(Plugin):
    def run(self, msg):
        return f"EMAIL: {msg}"

class SMSPlugin(Plugin):
    def run(self, msg):
        return f"SMS: {msg}"

class PushPlugin(Plugin):
    def run(self, msg):
        return f"PUSH: {msg}"


# The registry now contains every plugin — dispatch by name
print()
print("All registered plugins:", list(PluginRegistry.registry))

for plugin_name, plugin_cls in PluginRegistry.registry.items():
    plugin = plugin_cls()
    print(f"  {plugin_name} → {plugin.run('hello')}")

Animated Diagram — The Registry Grows With Each Subclass

The Modern Alternative — __init_subclass__

Python 3.6 introduced __init_subclass__, which covers most real use cases for metaclasses without the ceremony. If all you need is "run some code every time a subclass is defined," this is almost always the better choice.

# ── SAME auto-registry pattern — no metaclass needed ──────
class Plugin:
    registry = {}

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        Plugin.registry[cls.__name__] = cls
        print(f"[registry] Registered {cls.__name__}")


class EmailPlugin(Plugin):
    def run(self, msg): return f"EMAIL: {msg}"

class SMSPlugin(Plugin):
    def run(self, msg): return f"SMS: {msg}"

print(list(Plugin.registry))    # ['EmailPlugin', 'SMSPlugin']

When to Use a Metaclass (and When Not To)

Common Mistakes (and Fixes)

Quick Reference

Golden Rules