Metaclasses

When you define a class in Python, you’re creating a template for building objects. But what builds the class itself? The answer is a metaclass.

A metaclass is a “class of a class”. Just as an object is an instance of a class, a class is an instance of a metaclass. By default, all classes in Python are constructed using the built-in type() function, which acts as the default metaclass.

Here is a visualization distinguishing between class creation time and instance creation time:

class MyMeta(type):
    def __new__(mcs, name, bases, namespace):
        print(f"1. Creating class {name}")
        return super().__new__(mcs, name, bases, namespace)

print("0. Before class definition")
class MyClass(metaclass=MyMeta):
    pass
print("2. After class definition")

m = MyClass()
print("3. Instance created")

Notice that the metaclass __new__ method runs while the class is being defined, completely independent of when (or if) you ever instantiate it!

The Default Metaclass

If you don’t specify a metaclass, Python uses type.

class MyClass:
    pass
print(type(MyClass))

<class 'type'>

Customizing Class Creation with __new__

You can write your own metaclass by inheriting from type. The most common method to override is __new__, which takes four arguments:

1. mcs: The metaclass itself.
2. name: The name of the class being created.
3. bases: A tuple of base classes.
4. namespace: A dictionary containing the class attributes and methods.

Let’s modify a class namespace before the class even exists by converting all its custom attributes to uppercase!

class UppercaseMeta(type):
    def __new__(mcs, name, bases, namespace, **kwargs):
        uppercase_attr = {k.upper(): v for k, v in namespace.items() if not k.startswith('__')}
        return super().__new__(mcs, name, bases, uppercase_attr, **kwargs)

class MyClass(metaclass=UppercaseMeta):
    my_attr = 10

print(hasattr(MyClass, 'my_attr'))
print(hasattr(MyClass, 'MY_ATTR'))

False
True

Class Factories and Registries

Metaclasses are sometimes referred to as class factories. A very common use case is building a registry of plugins. Whenever a new subclass is defined, the metaclass can automatically record it in a dictionary.

registry = {}
class PluginMeta(type):
    def __new__(mcs, name, bases, namespace):
        cls = super().__new__(mcs, name, bases, namespace)
        if name != 'BasePlugin':
            registry[name] = cls
        return cls

class BasePlugin(metaclass=PluginMeta):
    pass
class MyPlugin(BasePlugin):
    pass

print(list(registry.keys()))

['MyPlugin']

Initialization with __init__

While __new__ creates the class object, you can also override __init__ on the metaclass to configure the class immediately after it has been created.

class InitMeta(type):
    def __init__(cls, name, bases, namespace):
        super().__init__(name, bases, namespace)
        cls.initialized_by_meta = True

class TestClass(metaclass=InitMeta):
    pass
print(TestClass.initialized_by_meta)

True

Inheriting Metaclasses

The appropriate metaclass for a class is determined by looking at its explicit metaclass keyword argument or by checking its base classes. If a base class has a custom metaclass, the derived class will inherit it automatically.

class Meta(type):
    pass
class Base(metaclass=Meta):
    pass
class Derived(Base):
    pass
print(type(Derived))

<class '__main__.Meta'>

Metaclass Conflicts

Because a class inherits metaclasses from its bases, multiple inheritance can cause problems. If you try to inherit from two classes that have different, unrelated metaclasses, Python won’t know which one to use to construct your new class!

class MetaA(type): pass
class MetaB(type): pass
class A(metaclass=MetaA): pass
class B(metaclass=MetaB): pass

try:
    class C(A, B): pass
except TypeError as e:
    print('TypeError')

TypeError

To resolve this, you would have to manually create a new metaclass that inherits from both MetaA and MetaB, and specify it as the metaclass for C.

Metaclass vs __init_subclass__

While metaclasses are incredibly powerful, they are often overkill. Since Python 3.6, the __init_subclass__ classmethod provides a much simpler way to customize class creation (like building registries) without the complexity of metaclasses. The golden rule is: If __init_subclass__ can solve your problem, use it instead of a metaclass.