ZetCode

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.

basic_mro_entries.py
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.

erase_mro_entries.py
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.

resolve_bases.py
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.

bases_arg.py
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.

select_base.py
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.

validate_mro_entries.py
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.

bad_mro_entries.py
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:

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

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Python tutorials.