Demystifying Python Metaclasses
A beginner-friendly guide to understanding metaclasses in Python, how they work, and when to use them.
A clear, practical guide for Python 3 (and a note about old-style Python 2 syntax)
Metaclasses are advanced—but elegant—tools that let you influence how classes are created. If you think of classes as blueprints for objects, then metaclasses are the blueprints for classes. Use them when you really need to control class creation and behavior.
- In Python everything is an object — even classes.
- Classes are instances of a metaclass. By default that metaclass is
type. type(name, bases, dict)is the dynamic form of theclassstatement.- To change how classes are built, subclass
typeand override the metaclass hooks (__prepare__,__new__,__init__,__call__). - Prefer simpler tools (decorators,
__init_subclass__) for most cases — metaclasses are powerful and can be overkill.
Table of contents
- Everything is an object
- What is a metaclass?
type()— the class factory- Metaclass hooks and where to use them
__prepare____new__vs__init__(metaclass and instance level)__call__
- Example metaclasses (practical snippets)
- When to use (and when not to)
- Gotchas & tips
- Further reading
1. Everything is an object
In Python everything is an object: strings, numbers, lists — and yes, classes. That means you can call type() on an instance to get the class it belongs to:
1
2
3
4
>>> type('hello')
<class 'str'>
>>> isinstance('hello', str)
True
Because classes are objects, the classes themselves have a type — their metaclass:
1
2
3
4
>>> type(int)
<class 'type'>
>>> isinstance(int, type)
True
type is the default metaclass that creates (and defines the behavior of) normal classes.
2. What is a metaclass?
A metaclass is simply the class of a class — it controls how classes are created. By default Python uses type as the metaclass, but you can provide your own metaclass to intercept and modify class construction.
A class definition like below is roughly equivalent to calling type():
1
2
class MyClass(Base):
attr = 1
is internally similar to:
1
MyClass = type('MyClass', (Base,), {'attr': 1})
So, creating classes with class syntax calls type (or your custom metaclass) under the hood.
3. type() — the class factory
type() behaves differently depending on how many arguments you pass:
type(obj)→ returns the type (class) ofobj.type(name, bases, dict)→ dynamically creates a new class. The arguments are:name(string) → becomes__name__of the new class.bases(tuple) → base classes, becomes__bases__.dict(mapping) → the namespace for class attributes and methods, becomes__dict__.
This is how the class statement is implemented internally.
Example:
1
2
MyDynamic = type('MyDynamic', (object,), {'x': 42, 'hello': lambda self: 'hi'})
print(MyDynamic, MyDynamic.x)
4. Metaclass hooks and where to use them
To customize class creation, subclass type and override the hooks that type exposes. The most important hooks are __prepare__, __new__, __init__, and (optionally) __call__.
__prepare__
__prepare__ is called before the class body is executed. It returns the mapping (namespace) used during the class body execution (by default this is a plain dict). You can return any mapping — for example an OrderedDict to preserve definition order or a custom mapping that records attribute creation.
Signature (conceptual):
1
2
3
@classmethod
def __prepare__(metacls, name, bases, **kwargs):
return mapping
This hook was introduced in PEP 3115 and makes it possible to control the class namespace.
__new__ vs __init__ (metaclass and instance level)
There are two analogous creation stages both for instances and for classes.
Instance level:
__new__(a static method-like constructor) is responsible for creating and returning a new instance.__init__initializes the already-created instance.
Metaclass level (when creating classes):
When a class statement runs, the metaclass’ __new__ and __init__ are invoked to construct the class object itself. If you subclass type, the signatures look like:
1
2
3
4
5
6
7
8
class Meta(type):
def __new__(mcls, name, bases, namespace):
# called first — must return the class object
return super().__new__(mcls, name, bases, namespace)
def __init__(cls, name, bases, namespace):
# called after __new__ — initialize the class object
super().__init__(name, bases, namespace)
Important: if __new__ in the metaclass does not return a class object (usually super().__new__), the __init__ of the metaclass may never be called.
__call__
When you call SomeClass() to create an instance, the call flow is:
- The metaclass’
__call__is invoked (by default that’stype.__call__). - That implementation calls the class’
__new__to create the instance. - Then it calls the class’
__init__to initialize the instance.
If you override __call__ in a metaclass, you can intercept or modify instance creation for all classes created with that metaclass.
Flow summary for class instantiation:
1
Metaclass.__call__() -> Class.__new__() -> Class.__init__()
Flow summary for class creation (the metaclass creating the class):
1
Metaclass.__prepare__() -> execute class body -> Metaclass.__new__() -> Metaclass.__init__()
5. Example metaclasses (practical snippets)
5.1 A simple logging metaclass
This metaclass logs when classes are created:
1
2
3
4
5
6
7
8
9
class LoggingMeta(type):
def __new__(mcls, name, bases, namespace):
print(f"Creating class {name}")
return super().__new__(mcls, name, bases, namespace)
class My(metaclass=LoggingMeta):
pass
# Output: Creating class My
5.2 Registering subclasses automatically
A common practical use: automatically register subclasses (useful for plugin systems):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
class RegistryMeta(type):
def __init__(cls, name, bases, namespace):
if not hasattr(cls, 'registry'):
# base class — create the container
cls.registry = []
else:
# concrete subclass — register it
cls.registry.append(cls)
super().__init__(name, bases, namespace)
class Base(metaclass=RegistryMeta):
pass
class A(Base):
pass
class B(Base):
pass
print(Base.registry) # [<class '__main__.A'>, <class '__main__.B'>]
5.3 Enforcing naming or attribute rules
You can enforce coding rules at class creation time (raise an error if a rule is violated):
1
2
3
4
5
6
class NoPublicAttrsMeta(type):
def __init__(cls, name, bases, namespace):
for attr in namespace:
if not attr.startswith('_') and callable(namespace[attr]):
raise TypeError("Public methods are not allowed")
super().__init__(name, bases, namespace)
(Use such strict rules sparingly — they can make code harder to extend.)
6. When to use (and when not to)
Metaclasses are powerful but often unnecessary. Consider alternatives first:
- Class decorators — good to modify or wrap a single class.
__init_subclass__— a hook that runs on subclass creation; good for per-class initialization logic without the complexity of a metaclass.- Registries and factories built from regular classes and modules.
If you need to enforce policy or behavior across many classes or want subclasses to inherit the customization automatically, a metaclass is appropriate.
A famous community guideline: “Metaclasses are deeper magic than 99% of users should ever worry about.” That’s a reminder to prefer simpler tools when they suffice.
7. Gotchas & tips
- Multiple inheritance & metaclass conflicts: If two base classes have different metaclasses, Python computes the appropriate metaclass (it must be compatible) and may raise
TypeErrorif there’s a conflict. The rule is similar to MRO — the resulting metaclass must be a (non-strict) subclass of all involved metaclasses. - Always return the result of
super().__new__from a metaclass__new__unless you have a very specific reason not to — otherwise class initialization flow can break. __prepare__controls the namespace used during class body execution — useful for preserving order or using custom dict-like behavior.__call__intercepts instance creation for all classes using that metaclass. Overriding it without callingsuper()can break expected behaviors.- Keep metaclass logic simple and well-tested — it affects every class built with it.
8. Further reading
This guide focused on practical, hands-on usage. If you want to dive deeper, look for resources on:
- PEP 3115 (class creation semantics and
__prepare__) - Python data model (sections on metaclasses and class creation)
- Tutorials and long-form explanations (Real Python has an approachable metaclasses article and course)
Appendix: Quick reference snippets
Example: dynamic class creation
1
2
# same as "class X: ..."
X = type('X', (object,), {'value': 10, 'greet': lambda self: 'hello'})
Minimal metaclass template
1
2
3
4
5
6
7
8
9
10
11
12
13
14
class Meta(type):
def __prepare__(mcls, name, bases, **kwargs):
return super().__prepare__(name, bases)
def __new__(mcls, name, bases, namespace):
# modify namespace if needed
return super().__new__(mcls, name, bases, namespace)
def __init__(cls, name, bases, namespace):
super().__init__(name, bases, namespace)
def __call__(cls, *args, **kwargs):
# control instance creation
return super().__call__(*args, **kwargs)
Python 2 note (historical)
In Python 2 there was an __metaclass__ hook inside the class body or as a module-level variable. In Python 3 the preferred syntax is the metaclass= keyword in the class header (and Python 3 uses new-style classes by default).
Closing thoughts
Metaclasses let you program at the level of class creation. They’re a powerful tool that, used carefully, can simplify patterns that are otherwise awkward or repetitive. When in doubt: try a decorator or __init_subclass__ first — if those don’t fit, a well-designed metaclass can be the elegant answer.