Python Metaclasses Explained — How Classes Are Built and Why It Matters

# ================================================================
# Part 1: type(name, bases, namespace) is what the interpreter does
# ================================================================

# Writing a class block...
class ForgePoint:
    x: float = 0.0
    y: float = 0.0

    def distance(self) -> float:
        return (self.x ** 2 + self.y ** 2) ** 0.5

# ...is exactly equivalent to calling type() directly:
ForgePointDynamic = type(
    'ForgePointDynamic',          # name
    (object,),                    # bases
    {                             # namespace
        'x': 0.0,
        'y': 0.0,
        'distance': lambda self: (self.x ** 2 + self.y ** 2) ** 0.5,
    }
)

print(f'ForgePoint metaclass:        {type(ForgePoint).__name__}')         # type
print(f'ForgePointDynamic metaclass: {type(ForgePointDynamic).__name__}')  # type
print(f'type metaclass:              {type(type).__name__}')                # type itself
print()


# ================================================================
# Part 2: Tracing the four hooks in execution order
# ================================================================

class TracingMeta(type):
    """
    A metaclass that prints a message at each hook so you can see
    exactly when each step fires relative to the class body.
    """

    @classmethod
    def __prepare__(mcs, name: str, bases: tuple, **kwargs) -> dict:
        print(f'  [1] __prepare__   called for "{name}" — returning namespace dict')
        # Return a plain dict here; could return a custom dict subclass
        return super().__prepare__(name, bases, **kwargs)

    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs):
        print(f'  [3] __new__       called for "{name}" — class object not yet built')
        print(f'      namespace keys: {[k for k in namespace if not k.startswith("__")]}')
        cls = super().__new__(mcs, name, bases, namespace)
        print(f'  [3] __new__       returning {cls}')
        return cls

    def __init__(cls, name: str, bases: tuple, namespace: dict, **kwargs):
        print(f'  [4] __init__      called for "{name}" — class is already built: {cls}')
        super().__init__(name, bases, namespace)


print('--- Defining ForgeConfig ---')

class ForgeConfig(metaclass=TracingMeta):
    print('  [2] class body    executing — this is step 2')
    host: str = 'localhost'
    port: int = 8080

print()
print(f'ForgeConfig.host = {ForgeConfig.host}')
print(f'type(ForgeConfig) = {type(ForgeConfig).__name__}')
print()


# ================================================================
# Part 3: __new__ can replace the class; __init__ cannot
# ================================================================

class ReplacingMeta(type):
    """Demonstrates that __new__ can return a completely different object."""

    def __new__(mcs, name: str, bases: tuple, namespace: dict):
        if namespace.get('_replace_with_dict'):
            # Return a plain dict instead of a class — unusual but valid
            print(f'  ReplacingMeta: returning dict instead of class for "{name}"')
            return {'replaced': True, 'original_name': name}
        return super().__new__(mcs, name, bases, namespace)


class NormalClass(metaclass=ReplacingMeta):
    _replace_with_dict = False
    value = 42

print(f'NormalClass is a class: {isinstance(NormalClass, type)}')
print(f'NormalClass.value = {NormalClass.value}')

from __future__ import annotations
from typing import Any

# ================================================================
# Pattern 1: Auto-Registry Metaclass
# Use case: Plugin system where every subclass registers itself
# automatically — no manual register() call, no silent omissions.
# ================================================================

class PluginRegistryMeta(type):
    """Every concrete subclass is registered by name at class definition time."""

    _registry: dict[str, type] = {}

    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any):
        cls = super().__new__(mcs, name, bases, namespace)
        # Skip registration for the abstract base class itself
        # bases is an empty tuple only for the root class
        if bases:
            mcs._registry[name] = cls
            print(f'  [Registry] Registered plugin: "{name}"')
        return cls

    @classmethod
    def get_plugin(mcs, name: str) -> type:
        if name not in mcs._registry:
            raise KeyError(f'No plugin named "{name}" — registered: {list(mcs._registry)}')
        return mcs._registry[name]


class Exporter(metaclass=PluginRegistryMeta):
    """Abstract base — not registered."""
    def export(self, data: list) -> str:
        raise NotImplementedError


class CsvExporter(Exporter):
    def export(self, data: list) -> str:
        return ','.join(str(item) for item in data)


class JsonExporter(Exporter):
    import json
    def export(self, data: list) -> str:
        import json
        return json.dumps(data)


# Runtime dispatch by name — no if/elif chain, no manual registry
exporter_cls = PluginRegistryMeta.get_plugin('CsvExporter')
result = exporter_cls().export([1, 2, 3])
print(f'  Export result: {result}')
print()


# ================================================================
# Pattern 2: Interface Enforcement at Definition Time
# Use case: Guarantee abstract methods are implemented before the
# class can even be created — catches bugs in CI, not production.
# ================================================================

class InterfaceMeta(type):
    """Raises at class definition time if required methods are missing."""

    _required_methods: tuple[str, ...] = ()

    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any):
        # Only enforce on concrete subclasses, not the base class
        if bases:
            required = getattr(mcs, '_required_methods', ())
            missing = [m for m in required if m not in namespace]
            if missing:
                raise TypeError(
                    f'Class "{name}" must implement: {missing}. '
                    f'Define these methods or your class cannot be created.'
                )
        return super().__new__(mcs, name, bases, namespace)


class Pipeline(metaclass=InterfaceMeta):
    InterfaceMeta._required_methods = ('validate', 'report')

    def validate(self) -> bool:
        raise NotImplementedError

    def report(self) -> str:
        raise NotImplementedError


class SalesPipeline(Pipeline):
    def validate(self) -> bool:
        return True

    def report(self) -> str:
        return 'Generating sales report'


print(f'  SalesPipeline created successfully.')
print(f'  Report: {SalesPipeline().report()}')
print()

try:
    class BrokenPipeline(Pipeline):
        def validate(self) -> bool:
            return False
        # Missing: report()
except TypeError as enforcement_error:
    print(f'  Caught at definition time: {enforcement_error}')
print()


# ================================================================
# Pattern 3: Attribute Validation — Docstring Enforcement
# Use case: All public methods must have docstrings.
# Catches undocumented methods at class definition, not at review.
# ================================================================

class DocstringEnforcerMeta(type):
    """Raises at class definition if any public method lacks a docstring."""

    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any):
        for attr_name, attr_value in namespace.items():
            if callable(attr_value) and not attr_name.startswith('_'):
                if not getattr(attr_value, '__doc__', None):
                    raise ValueError(
                        f'{name}.{attr_name}() has no docstring. '
                        f'All public methods must be documented.'
                    )
        return super().__new__(mcs, name, bases, namespace)


class PaymentProcessor(metaclass=DocstringEnforcerMeta):
    def charge(self, amount: float) -> bool:
        """Charge the customer the given amount in USD."""
        return True

    def refund(self, amount: float) -> bool:
        """Issue a refund for the given amount."""
        return True

print('  PaymentProcessor passed docstring audit.')

try:
    class UndocumentedProcessor(metaclass=DocstringEnforcerMeta):
        def charge(self, amount: float) -> bool:  # no docstring
            return True
except ValueError as doc_error:
    print(f'  Caught: {doc_error}')

from __future__ import annotations
from typing import Any

# ================================================================
# Gotcha 1: Metaclass Conflict — and how to resolve it
# ================================================================

class MetaA(type):
    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any):
        print(f'  [MetaA.__new__] building "{name}"')
        return super().__new__(mcs, name, bases, namespace)


class MetaB(type):
    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any):
        print(f'  [MetaB.__new__] building "{name}"')
        return super().__new__(mcs, name, bases, namespace)


class ClassWithMetaA(metaclass=MetaA):
    pass


class ClassWithMetaB(metaclass=MetaB):
    pass


try:
    class Combined(ClassWithMetaA, ClassWithMetaB):
        pass
except TypeError as conflict:
    print(f'  Conflict: {conflict}')
print()

# THE FIX: create a merged metaclass that inherits from both.
# MetaA.__new__ -> MetaB.__new__ -> type.__new__ via super() chaining.
class MetaMerged(MetaA, MetaB):
    """A combined metaclass. super() chains MetaA → MetaB → type correctly."""
    pass


print('  Building CombinedFixed with MetaMerged:')

class CombinedFixed(ClassWithMetaA, ClassWithMetaB, metaclass=MetaMerged):
    working_attribute = True

print(f'  CombinedFixed metaclass: {type(CombinedFixed).__name__}')
print(f'  MetaMerged MRO: {[m.__name__ for m in MetaMerged.__mro__]}')
print()


# ================================================================
# Gotcha 2: __prepare__ to catch duplicate attribute definitions
# Python silently overwrites duplicates — this namespace does not.
# ================================================================

class DuplicateDetectingNamespace(dict):
    """A dict subclass that raises on duplicate non-dunder key assignments."""

    def __setitem__(self, key: str, value: Any) -> None:
        if key in self and not key.startswith('_'):
            raise AttributeError(
                f'Duplicate attribute "{key}" detected in class body. '
                f'Each attribute must be defined exactly once.'
            )
        super().__setitem__(key, value)


class NoDuplicatesMeta(type):
    """Uses __prepare__ to inject our duplicate-detecting namespace."""

    @classmethod
    def __prepare__(mcs, name: str, bases: tuple, **kwargs: Any) -> DuplicateDetectingNamespace:
        return DuplicateDetectingNamespace()

    def __new__(mcs, name: str, bases: tuple, namespace: DuplicateDetectingNamespace, **kwargs: Any):
        # Convert custom namespace to a plain dict before passing to type.__new__
        return super().__new__(mcs, name, bases, dict(namespace))


class StatusCodes(metaclass=NoDuplicatesMeta):
    OK = 200
    NOT_FOUND = 404
    SERVER_ERROR = 500

print(f'  StatusCodes.OK = {StatusCodes.OK}')
print(f'  StatusCodes.NOT_FOUND = {StatusCodes.NOT_FOUND}')

try:
    class BrokenStatusCodes(metaclass=NoDuplicatesMeta):
        OK = 200
        NOT_FOUND = 404
        OK = 201  # Duplicate — caught at definition time
except AttributeError as duplicate_error:
    print(f'  Caught duplicate: {duplicate_error}')
print()


# ================================================================
# Gotcha 3: __new__ vs __init__ — wrong hook, silent bug
# __init__ cannot change bases — the class is already built.
# ================================================================

class WrongHookMeta(type):
    """Bug: modifying bases in __init__ has NO effect — class is already constructed."""

    def __init__(cls, name: str, bases: tuple, namespace: dict) -> None:
        modified_bases = bases + (object,)  # pointless — cls is already built from original bases
        super().__init__(name, bases, namespace)  # must pass original bases
        print(f'  [{name}] __init__ bases (unchanged): {cls.__bases__}')


class CorrectHookMeta(type):
    """Correct: intercept and modify bases in __new__ before construction."""

    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any):
        # Ensure object is always in bases — this actually works because
        # we modify bases before passing it to super().__new__
        if object not in bases:
            bases = bases + (object,)
        return super().__new__(mcs, name, bases, namespace)


print('  Demonstrating wrong hook (WrongHookMeta):')

class MyModelWrong(metaclass=WrongHookMeta):
    pass

print()
print('  Demonstrating correct hook (CorrectHookMeta):')

class MyModelCorrect(metaclass=CorrectHookMeta):
    pass

print(f'  MyModelCorrect.__bases__ = {MyModelCorrect.__bases__}')