Python __mro_entries__ Method
Last modified November 18, 2026 Python 3.15
Python calls __mro_entries__ when a base in a class statement is
not a class — typically an instance acting as a placeholder. The hook returns
the real bases to use, so the placeholder never appears in the final method
resolution order. This article shows replacement, erasure,
types.resolve_bases, multiple bases, dynamic selection,
validation and the errors raised by an invalid return value.
Replacing a placeholder base
An instance in a base list is not a class, so Python asks it for real bases
through __mro_entries__. The hook receives the original bases
tuple and returns a tuple of classes. The printout below uses names only, so
it stays stable across runs.
class Replacer:
def __init__(self, name):
self.name = name
def __mro_entries__(self, bases):
print("resolving", self.name, "with", len(bases), "base(s)")
return (object,)
class C(Replacer("X")):
pass
print([c.__name__ for c in C.__mro__])
The hook ran before the class was created and returned
object, so C has only object as a base.
The placeholder itself is absent from the MRO. Note that this resolution
applies to non-class bases; a real class with a __mro_entries__
method is used directly and the method is not called.
$ python basic_mro_entries.py resolving X with 1 base(s) ['C', 'object']
Erasing a placeholder from the bases
Returning an empty tuple removes the placeholder without adding anything. Any other bases in the class statement are kept.
class Remover:
def __mro_entries__(self, bases):
return ()
class D(Remover()):
pass
class E(Remover(), dict):
pass
print([c.__name__ for c in D.__mro__])
print([c.__name__ for c in E.__mro__])
D ends up inheriting only from object. In
E the placeholder disappears but dict remains a
real base. This is the mechanism used by placeholder objects that exist only
to configure a class.
$ python erase_mro_entries.py ['D', 'object'] ['E', 'dict', 'object']
The types.resolve_bases function
types.resolve_bases() performs the same substitution explicitly.
It is useful for seeing exactly what the class machinery will use as bases.
import types
class Placeholder:
def __mro_entries__(self, bases):
return (int,)
resolved = types.resolve_bases((Placeholder(), str))
print([b.__name__ for b in resolved])
The placeholder was replaced by int while the ordinary
str base was left alone. A class statement performs this step
internally before it computes the MRO.
$ python resolve_bases.py ['int', 'str']
Seeing the original bases tuple
The bases argument contains every base written in the class
header, including the placeholder itself. Printing their names or types
avoids unstable object representations.
class Show:
def __mro_entries__(self, bases):
for base in bases:
if isinstance(base, type):
print("class", base.__name__)
else:
print("placeholder", type(base).__name__)
return ()
class T(Show(), dict):
pass
print([c.__name__ for c in T.__mro__])
The tuple had two entries: the Show instance and the
dict class. A hook that needs to inspect sibling bases can use
this argument before deciding what to return.
$ python bases_arg.py placeholder Show class dict ['T', 'dict', 'object']
Dynamic base selection
The returned tuple can depend on the placeholder's configuration. This turns a placeholder into a selector that chooses a real base at class creation time.
class Select:
def __init__(self, mode):
self.mode = mode
def __mro_entries__(self, bases):
if self.mode == "int":
return (int,)
return (str,)
class A(Select("int")):
pass
class B(Select("str")):
pass
print([c.__name__ for c in A.__mro__])
print([c.__name__ for c in B.__mro__])
The same placeholder class produced two different inheritance trees.
Because resolution happens once, when the class statement executes, later
changes to self.mode would not affect either class.
$ python select_base.py ['A', 'int', 'object'] ['B', 'str', 'object']
Validating the finished class
A placeholder can return a small helper base whose
__init_subclass__ checks the class being defined. The closure
captures the required method names, so each placeholder carries its own
rules. The old version of this article put __init_subclass__ on
the placeholder's own class, which never runs when the placeholder is
erased.
class Requires:
def __init__(self, *names):
self.names = names
def __mro_entries__(self, bases):
names = self.names
class V:
def __init_subclass__(cls, **kwargs):
for name in names:
if not hasattr(cls, name):
raise TypeError(f"missing {name}")
return (V,)
class Good(Requires("serialize")):
def serialize(self):
return "ok"
print([c.__name__ for c in Good.__mro__])
try:
class Bad(Requires("serialize")):
pass
except TypeError as e:
print(type(e).__name__, e)
Good defines serialize and is accepted.
Bad is rejected at class definition time with a clear message.
The helper class V stays in the MRO, which is how its inherited
hook gets called for the finished class.
$ python validate_mro_entries.py ['Good', 'V', 'object'] TypeError missing serialize
The hook must return a tuple
Python checks the type of the return value. Returning a class or a list
instead of a tuple raises TypeError immediately during class
creation.
class BadReturn:
def __mro_entries__(self, bases):
return object
class BadList:
def __mro_entries__(self, bases):
return [int]
for placeholder in (BadReturn(), BadList()):
try:
class Attempt(placeholder):
pass
except TypeError as e:
print(type(e).__name__, e)
Both invalid returns are rejected with the same message. The fix is to
wrap the classes in a tuple: return (object,) or
return (int,). Note the trailing comma for a single class.
$ python bad_mro_entries.py TypeError __mro_entries__ must return a tuple TypeError __mro_entries__ must return a tuple
Best practices
A few rules keep base resolution predictable:
- Return a tuple of classes, using a trailing comma for a single entry.
- Return
()to erase a placeholder without adding a base. - Remember that the
basesargument includes the placeholder itself. - Only non-class bases are resolved; a class is used directly and its hook is ignored.
- Validation for the finished class belongs on a returned base, not on the erased placeholder.
Source
object.__mro_entries__ - Python documentation
types.resolve_bases - Python documentation
Method resolution order - Python documentation
PEP 560 - Core support for typing module and generic types
In this article we have implemented the __mro_entries__ hook.
We have covered base replacement, erasure, types.resolve_bases,
the original bases tuple, dynamic selection, validation and the tuple return
requirement. For related topics, see Python
__init_subclass__ method, Python method resolution
order, and Python metaclasses.
Author
List all Python tutorials.