Lesson 27. Metaclasses, and Why Not

Mission link: The mission asks you to name precisely why someone's metaclass is the wrong tool. That requires knowing what a metaclass does, what the cheaper hooks do, and the small set of cases where nothing else works.
Primary source: The Python Language Reference, Metaclasses
Prerequisites: Lesson 25, Lesson 26

Warm-up

1. ▢ Lesson 25 gave a hook that runs once per subclass at class-creation time. Which, and what did it replace?

2. ▢ What is type(Order), for an ordinary class Order?

Know this

A class statement is not a declaration; it is code that runs. Roughly:

class Order:
    currency = "GBP"
    def total(self): ...

is:

namespace = {}                        # execute the body into a dict
exec(class_body, globals(), namespace)
Order = type("Order", (), namespace)  # call the metaclass to build the class

The namespace holds exactly the names the body defined, and it exists before any class does. What comes out of the call is the class, which is why replacing the call is all a metaclass has to do.

type is the default metaclass. Calling it with three arguments, name, bases and namespace, builds a class, which is why type(Order) is type and why classes can be created at run time.

A metaclass replaces that call:

class Meta(type):
    def __new__(mcls, name, bases, namespace, **kwargs):
        cls = super().__new__(mcls, name, bases, namespace, **kwargs)
        return cls

class Order(metaclass=Meta): ...

Now type(Order) is Meta, and Meta gets to inspect or alter every class that uses it, including subclasses.

The four hooks that come first

Almost every real use of a metaclass is one of these, and each has a cheaper answer:

A class decorator is the one to reach for when the change happens after the class exists:

def slots_checked(cls):
    if not hasattr(cls, "__slots__"):
        raise TypeError(f"{cls.__name__} must define __slots__")
    return cls

@slots_checked
class Point:
    __slots__ = ("x", "y")

It runs once, it is visible directly above the class, it composes by stacking, and it does not change the class's type. Compared with a metaclass it gives up exactly one thing: it does not apply automatically to subclasses.

That single difference is the honest decision rule. If subclasses must be affected without opting in, you need __init_subclass__ or a metaclass. Otherwise a decorator does it.

What only a metaclass can do

Four things, and they are recognisable:

1. Control the class body's namespace before it executes, via __prepare__. This is how a framework makes a class body record declaration order in something other than a dict, or rejects duplicate names.
2. Change what isinstance and issubclass answer, via __instancecheck__ and __subclasshook__ on the metaclass. abc itself is built this way.
3. Customise the class object's own behaviour: attributes on the class rather than on instances, a __repr__ for the class, a __call__ that changes what Order(...) does before __new__ is reached, or __getattr__ for class-level attribute access.
4. Apply behaviour to a whole hierarchy the base class did not anticipate, because a metaclass is inherited and __init_subclass__ requires the base to have been written with the hook.

These are framework problems. abc, enum, and ORMs use metaclasses correctly, and they all exist to make ordinary code not need one.

The costs, concretely

• Type conflicts. Two bases with different metaclasses cannot be combined: TypeError: metaclass conflict. This shows up as a library being uncombinable with another library, and there is no fix on the user's side.
• Invisible action at a distance. A reader of the subclass sees no indication that anything happens; the behaviour lives in a class they may not know exists.
• Tooling. Checkers, editors and refactoring tools reason poorly about attributes a metaclass creates, so a codebase built this way loses the stage-3 benefits.
• Debuggability. The stack trace at class-creation time is at import time, and the failure often surfaces as a missing attribute much later.

Reading one

You will meet metaclasses in other people's code, so recognise the shape:

class Meta(type):
    @classmethod
    def __prepare__(mcls, name, bases, **kwargs):
        return {}                            # the namespace the body executes into

    def __new__(mcls, name, bases, namespace, **kwargs):
        return super().__new__(mcls, name, bases, namespace)

    def __init__(cls, name, bases, namespace, **kwargs):
        super().__init__(name, bases, namespace)

    def __call__(cls, *args, **kwargs):      # runs when the class is called
        return super().__call__(*args, **kwargs)

__prepare__, then the body executes, then __new__, then __init__. The cls in the last two methods is the class being built, and mcls is the metaclass. __call__ is the one that surprises people: it intercepts instance creation before __new__ from lesson 25 is reached, which is where singleton metaclasses live.

Two lines answer most questions about unfamiliar code: type(SomeClass) names the metaclass, and SomeClass.__mro__ shows what it inherited.

The rule, stated once

Write a metaclass when you are building a framework whose users must not have to opt in, and you have checked that __init_subclass__, __set_name__, abc and a class decorator cannot do it. Otherwise the metaclass is a cost paid by every future reader for a feature that had a simpler spelling.

Practice

1. ▢ Rewrite without a metaclass.

   class RegistryMeta(type):
       registry = {}
       def __new__(mcls, name, bases, ns, **kw):
           cls = super().__new__(mcls, name, bases, ns)
           if bases:
               RegistryMeta.registry[name.lower()] = cls
           return cls
   
   class Handler(metaclass=RegistryMeta): ...
   class CsvHandler(Handler): ...
   

class Handler:
    registry: ClassVar[dict[str, type["Handler"]]] = {}

    def __init_subclass__(cls, **kwargs) -> None:
        super().__init_subclass__(**kwargs)
        Handler.registry[cls.__name__.lower()] = cls

class CsvHandler(Handler): ...

2. ▢ Decorator or __init_subclass__?

   • a) Validate that a class defines __slots__, applied to twelve specific classes
   • b) Ensure every subclass of Model in the codebase, present and future, registers its table
   • c) Add __repr__ to a handful of legacy classes
   • d) Require every subclass written by another team to implement handle

3. ▢ Two libraries each provide a base class, and combining them fails. What does the error say, and what can a user do?

TypeError: metaclass conflict: the metaclass of a derived class must be a
(non-strict) subclass of the metaclasses of all its bases

4. ▢ Which of these genuinely needs a metaclass?

   • a) A singleton, so Connection() always returns the same object
   • b) A class body that must record the order in which fields were declared
   • c) Changing what isinstance(x, Shape) answers for classes that merely have the right methods
   • d) Generating __init__ from annotations

5. ▢ You inherit a codebase and a class behaves in a way its body does not explain. Give the two lines you run first.

type(SomeClass)          # names the metaclass, if any
SomeClass.__mro__        # names every base, in lookup order

6. ▢ A colleague proposes a metaclass so that all models automatically validate their fields on assignment. Give a fuller answer than "no".

Real-world reps

• [ ] Run type(cls) over the classes in one dependency you use heavily. The ones that are not type are where the framework's magic lives.
• [ ] Find a metaclass in any codebase and decide which of the four legitimate capabilities it uses. Most use none.
• [ ] Take one metaclass, if you have one, and try rewriting it as __init_subclass__ plus a class decorator. Keep whichever version a new reader would understand faster.
• [ ] Read the first thirty lines of enum.py or abc.py in the standard library. Both are metaclasses done for a reason, and both exist so your code does not need one.
• [ ] Tomorrow: write a class decorator that adds one thing, and stack two of them, to see how composition works where inheritance of metaclasses does not.

Going further

• Metaclasses: __prepare__, the creation sequence, and the conflict rule
• PEP 487, Simpler customisation of class creation: the explicit argument for the hooks over metaclasses
• abc: a correct metaclass, and __subclasshook__
• type: the three-argument form that builds a class
• inspect: reading the source of whatever is doing the magic
• Resources

Not landing? Reread the primary source at the top, since this lesson compresses it and compression is where understanding leaks. Check the glossary for any term that felt slippery.

If the lesson itself is unclear rather than the material, that is a defect: open an issue.