Python Metaclasses and `type()`

A metaclass is the class of a class. In Python, classes are objects just like integers and strings, and just as every object has a type that created it, every class has a metaclass. The default metaclass for all classes is type.

The article on the Python object model established that everything in Python is an object. Metaclasses are the logical conclusion of this principle: if classes are objects, something must create them, and that something is a metaclass.

You rarely need to write a custom metaclass. But understanding how type creates classes, and when a metaclass is the right solution, deepens your understanding of how Python works at a fundamental level.

Creating classes with the type built-in

The type function serves two purposes. Called with one argument, it returns the type of an object. Called with three arguments, it creates and returns a new class.

python

Dog = type("Dog", (), {"sound": "woof", "speak": lambda self: self.sound})
 
d = Dog()
print(type(d))
print(d.speak())
print(Dog.__name__)

The type function acts as a class factory when called with three arguments. The resulting class behaves exactly like one created with the class statement, with the same method resolution and attribute lookup semantics.

text

<class '__main__.Dog'>
woof
Dog

The two approaches produce identical results. You can verify this by inspecting the class dictionary and comparing it to what a class statement would produce.

Adding base classes works the same way as inheritance in a class statement. The method resolution order is computed automatically.

python

class Animal:
    def speak(self):
        return "generic sound"
 
Cat = type("Cat", (Animal,), {"sound": "meow"})
 
c = Cat()
print(c.speak())

The Cat class inherits the speak method from Animal through normal inheritance. The same method resolution order rules apply as with any class created by the class statement.

text

meow

Dynamic class creation is useful when the class structure depends on runtime data. Configuration-driven frameworks and plugin systems often use type to build classes from external definitions.

How the class statement uses metaclasses

When Python encounters a class statement, it executes the body in a new namespace, collects all names defined there, and calls the metaclass to create the class object. The default metaclass is type.

You can specify a different metaclass with the metaclass keyword in the class definition. Python passes the class name, bases, and namespace to the metaclass, which returns the new class object.

python

class Registry(type):
    _classes = {}
 
    def __new__(mcs, name, bases, namespace):
        cls = super().__new__(mcs, name, bases, namespace)
        mcs._classes[name] = cls
        return cls
 
class Base(metaclass=Registry):
    pass
 
class User(Base):
    pass
 
class Product(Base):
    pass
 
print(Registry._classes)

The Registry metaclass records every class that inherits from Base. The new method runs before the class is fully created, giving you a chance to inspect or modify the namespace.

text

{'Base': <class '__main__.Base'>, 'User': <class '__main__.User'>, 'Product': <class '__main__.Product'>}

This auto-registration pattern is one of the most common legitimate uses of metaclasses. Frameworks use it to discover plugins, serializers, and handlers without explicit registration calls.

Validating class definitions with a metaclass

A metaclass can inspect and reject class definitions that do not meet requirements. This is stricter than runtime checks because the error appears at import time, before any instances are created.

python

class RequiredMethods(type):
    _required = []
 
    def __new__(mcs, name, bases, namespace):
        cls = super().__new__(mcs, name, bases, namespace)
        missing = [m for m in mcs._required if m not in namespace]
        if missing:
            raise TypeError(f"{name} must define: {', '.join(missing)}")
        return cls
 
class Service(metaclass=RequiredMethods):
    _required = ["start", "stop"]
 
class WebService(Service):
    def start(self):
        return "started"
 
    def stop(self):
        return "stopped"
 
ws = WebService()
print(ws.start())

The WebService class defines both required methods and passes validation. If it omitted start or stop, the error would appear at definition time.

text

started

This pattern is useful for plugin systems where every plugin must implement a specific interface. The metaclass enforces the contract before any code can instantiate a non-conforming class.

Adding methods with a metaclass

A metaclass can inject methods or attributes into every class it creates. This is less common than validation but useful when you need every subclass to share behaviour that cannot be expressed through normal inheritance.

python

class DebugMeta(type):
    def __new__(mcs, name, bases, namespace):
        namespace["debug"] = lambda self: {
            "class": name,
            "attrs": vars(self),
        }
        return super().__new__(mcs, name, bases, namespace)
 
class Config(metaclass=DebugMeta):
    host = "localhost"
    port = 5432
 
cfg = Config()
print(cfg.debug())

The DebugMeta metaclass adds a debug method to every class it creates. Each instance can call debug to inspect its own state.

text

{'class': 'Config', 'attrs': {}}

The attrs dictionary is empty because host and port are class attributes, not instance attributes. The debug method reports the instance state, which is correct for instance-level debugging.

The metaclass hierarchy

Every class is an instance of a metaclass. The default metaclass is type. When you create a custom metaclass, it must inherit from type.

Instances of your custom metaclass are classes. The metaclass of a class is the metaclass of its base class, or type if no metaclass is specified. This means metaclasses propagate through inheritance automatically.

python

class Meta(type):
    pass
 
class A(metaclass=Meta):
    pass
 
class B(A):
    pass
 
print(type(A))
print(type(B))

Both A and B are instances of Meta because B inherits A's metaclass. Python resolves metaclass conflicts when multiple bases specify different metaclasses, requiring those metaclasses to share a common ancestor.

text

<class '__main__.Meta'>
<class '__main__.Meta'>

The article on class creation in Python explores the full class creation machinery in more detail.

When not to use metaclasses

Metaclasses are powerful but they add complexity that every reader of your code must understand. Most problems that seem to need a metaclass can be solved with simpler tools.

Class decorators can modify a class after creation and cover many of the same use cases with less magic. Descriptors and properties handle attribute-level control, and inheritance and mixins capture shared behaviour. The init subclass hook, available since Python 3.6, handles subclass registration without a metaclass.

Reach for a metaclass only when you need to intercept the class creation process itself. Validation at definition time, automatic registration, and namespace modification are the three legitimate use cases. If your problem fits a decorator, use a decorator.