Metaclasses: the six steps of class creation, which show what a metaclass is for and what no longer needs one

Base: a class has a type too

The word "metaclass" frightens people more than it should, and nearly always because of one skipped step. The step is this: a class has a type too.

For objects this is familiar. Write x = 5 and x has a type, int. Declare class Order and make order = Order(), and order has a type, Order. The question nobody asks: what is the type of Order itself?

The answer is type. A class is an object like a number or a string, and it has a type as well. That type of a class is what a metaclass is.

From there the model fits into two lines, and these are the two to remember:

• an object is an instance of its class;
• a class is an instance of its metaclass.

Hence the junior-level answer, sayable in an interview as it stands: a metaclass governs how classes are created in much the same way a class governs how instances are created. A class decides what an object will be like; a metaclass decides what a class will be like.

That level is enough. If an interview asks "what is a metaclass", the answer above is a correct answer rather than a simplified one: it distorts nothing and promises nothing beyond what is there, and there is no obligation to go further. That is not why this lesson is marked advanced. Everything below is about which steps "creating a class" is made of, where each of them can be interfered with, and why in practice interfering is almost never necessary.

Mechanism 1: a class is an instance of its metaclass, and the protocol follows

One line checks it — and shows that the chain stops at type:

class Plain:
    pass
 
print(type(Plain))          # <class 'type'>
print(type(type))           # <class 'type'>

Plain is an object. Its type is type. A metaclass is simply a type whose instances are classes; to write one you subclass type. The language has no separate “metaclass” entity at all.

Something non-obvious follows immediately: Class(...) is a call on an instance of the metaclass. That is why instance creation is intercepted by defining __call__ on the metaclass rather than on the class. This is exactly how singletons are made:

class Singleton(type):
    _instances = {}
 
    def __call__(cls, *args, **kwargs):
        if cls not in cls._instances:
            cls._instances[cls] = super().__call__(*args, **kwargs)
        return cls._instances[cls]

Mechanism 2: six steps, and the order matters more than the list

The reference lists the steps briefly.

And the two most useful hooks are described elsewhere, in a different section — which is exactly why their place in the order usually gets guessed at.

The key part is whose action this is: both hooks are called by type.__new__ itself, which means they happen inside the third step rather than after it.

What follows in practice:

• __init_subclass__ will not see what the metaclass does in __init__ — that step is still ahead. The metaclass in __init__, on the other hand, already sees the result of both hooks.
• The name, the bases and the namespace can be changed only up to the third step. After that they stop being arguments and become properties of an existing class.
• A class decorator runs last, when everything is already in place: "After the class object is created, it is passed to the class decorators included in the class definition."

What "last" means for a class decorator

From "runs last" it is easy to derive "and therefore can do nothing", which is wrong. It receives a finished class object — and with a finished class you can do almost anything. A run of bench/metaclass/decorator_capabilities.py:

__name__ after the decorator                         Renamed
the new attribute is visible                         added by the decorator
the decorator returned another class: its name       Replacement
a class on object: __bases__ = (Base,)               TypeError
a class on Base: __bases__ = (Another,)              Another

Rename it — it can. Add and rewrite attributes — it can. Return an entirely different object in place of the class, so the name in the module binds to that instead — it can do that too. Bases are trickier, but the restriction is not about decorators: assigning __bases__ is not always allowed (on a class inheriting straight from object it raises TypeError), and that is a rule of type itself, not a consequence of when the decorator runs.

The real boundary runs somewhere else — through time, not power:

The same run prints the order of events, and in it the class body is executed in the mapping from __prepare__ long before the decorator:

__prepare__ supplied its own mapping
the namespace is given 'a'
the namespace is given 'b'
Meta.__new__ sees the names: ['a', 'b']
decorator: the body has already run, the class is assembled

Mechanism 3: what only a metaclass can do

Three things, and all three follow from the order.

First — intercept the execution of the class body. __prepare__ hands out the mapping the body will be written into, and therefore sees each assignment separately. Nothing else can do this: by the time __init_subclass__ runs the body has already executed and only the result is available.

class NoDuplicates(dict):
    def __setitem__(self, key, value):
        if key in self:
            raise TypeError(f"the name {key!r} is defined twice in the class body")
        super().__setitem__(key, value)
 
class StrictMeta(type):
    @classmethod
    def __prepare__(mcls, name, bases, **kwargs):
        return NoDuplicates()

An ordinary class accepts a duplicated name silently — the last assignment simply wins. With this metaclass you get a TypeError while the class is being defined.

Second — intercept instance creation through __call__. This is what singletons, instance caches and substituting the returned object are built on.

Third — substitute the name, the bases or the namespace. All three are arguments to Meta.__new__, that is, to the third step; by the time __init_subclass__ runs — let alone the decorator — the class already exists and it is too late.

Everything else people reach for a metaclass to do — registering subclasses, checking required attributes, giving descriptors their names — is covered by the two hooks from PEP 487.

The row about the name, the bases and the namespace deserves a precise reading. It is about them as arguments of class creation: only a metaclass can slip its own mapping under the body, or substitute the name or the bases before the class is assembled. A finished class a decorator will happily rename — the run above shows it doing so. The boundary between the two tools runs through time, not through power.

Mechanism 4: the boundary of __init_subclass__

The hook is called on the parent when a child is created. The reference compares it with a decorator directly:

The word "future" is the boundary:

class Registry:
    registered = []
 
    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        Registry.registered.append(cls.__name__)
 
class First(Registry): pass
class Second(Registry): pass
 
print(Registry.registered)      # ['First', 'Second'] — Registry itself is absent

A metaclass, by contrast, fires for the class that named it too: Meta.__new__ runs for the base class exactly as it does for the subclasses. If a registry must include the base class, that is one of the few reasons to take a metaclass.

One more thing: super().__init_subclass__(**kwargs) on the first line is not a formality. Without it the nearest parent's hook runs and every class further along the MRO is skipped — silently, with no error and no warning.

Deeper: what a metaclass actually costs

Not time. A class with an empty metaclass is created in 7.09 µs against 6.98 µs without one (3.13.7, best of seven runs) — a difference within the noise, and paid once per class rather than per instance.

Time is charged for exactly one thing: intercepting __call__ adds a Python method call to a path that otherwise runs entirely in C. 223.3 ns per instance against 59.6 — 3.7 times, on every creation. The measurement is on an empty class, so the addition here is a constant: on a class that actually does something in __init__ the same overhead weighs noticeably less. A singleton built with a metaclass pays that on every access, including the ones where the object already exists.

The real price is this one:

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

Note where the error appears: in someone else's file, for whoever writes the subclass and never chose your metaclass. All they wanted was to inherit from your class and from something else with a metaclass of its own — ABC, say, or Enum. They can fix it in two ways only: by not inheriting, or by writing a third metaclass that merges the other two.

How to answer in an interview

The short answer: a metaclass is the type of a class. A class is an instance of its metaclass exactly as an object is an instance of its class, and a metaclass governs how classes are created in much the same way a class governs how instances are created. Hence Class(...) calling the metaclass's __call__: the class is its instance.

That is enough for a correct answer. What follows is what you add when the interviewer digs.

If the interviewer digs deeper

On its own a metaclass can do two things nothing else can: intercept the execution of the class body through __prepare__, and intercept instance creation through __call__. The commonest tasks — registering subclasses, validating their fields, giving a descriptor its name — have been done since 3.6 with __init_subclass__ and __set_name__, more cheaply and without a metaclass conflict. That is design advice, not an equality of powers: preparing the namespace, replacing the bases and intercepting instance creation stay with the metaclass alone.

One phrasing that is easy to get wrong out loud concerns the class decorator. "A decorator cannot replace the class" is false: replacing it is exactly what it may do — it is free to return a different object in the class's place, and the name in the module binds to that. Its boundary lies elsewhere: it takes no part in creating the class. The mapping the body ran in, and the arguments of type.__new__, are history by the time it arrives, and it cannot influence what __set_name__ and __init_subclass__ will see. The difference between it and a metaclass is when it intervenes, not how much it can do.

If asked "when did you last write a metaclass", the honest answer is usually "I haven't", and it is the right one. A good sign the question is understood: name the conflict, not the runtime cost, as the price, and add that the one who pays it is someone else's code. And keep the boundary on the measurements: 7.09 against 6.98 µs and 223.3 against 59.6 ns were taken on one machine and on an empty class (3.13.7) — what they carry is not the number but what exactly is being charged for.

Next they ask

Common misconceptions

Version history

Practice

Two exercises. Answer first, then check against the real output: in both, the right answer comes from a recorded run rather than from an editor.

class Base:
  registry = []

  def __init_subclass__(cls, **kwargs):
      super().__init_subclass__(**kwargs)
      Base.registry.append(cls.__name__)


class A(Base):
  pass


class B(A):
  pass


print(Base.registry)

['A', 'B']

['Base', 'A', 'B']

['A']

[]

Check yourself

What measured this

The numbers in this article come from these scripts. Each one opens from here, together with the record of the run: what it was measured on, what came out, and with what spread.

• bench/metaclass/cost.py
• bench/metaclass/decorator_capabilities.py
• bench/metaclass/order.py