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

# Demonstrating that `type` is the default metaclass for every class

# --- Part 1: Confirming the metaclass chain ---
class Vehicle:
    """A plain class — nothing special defined."""
    wheels = 4

print(type(Vehicle))          # <class 'type'>  — Vehicle is an *instance* of type
print(type(type))             # <class 'type'>  — type is its own metaclass
print(isinstance(Vehicle, type))  # True

# --- Part 2: Building a class manually using type() directly ---
# This is EXACTLY what Python does internally when it reads a `class` block.

# Arguments: (class_name, tuple_of_base_classes, attribute_namespace_dict)
ElectricCar = type(
    'ElectricCar',                        # name
    (Vehicle,),                           # bases — inherits from Vehicle
    {
        'battery_kwh': 75,                # class attribute
        'charge': lambda self: 'charging' # method
    }
)

my_car = ElectricCar()
print(my_car.wheels)          # 4  — inherited from Vehicle
print(my_car.battery_kwh)     # 75
print(my_car.charge())        # charging
print(type(my_car))           # <class '__main__.ElectricCar'>

# --- Part 3: Watching the three-step protocol in action ---
class TracingMeta(type):
    """A metaclass that prints each step of class construction."""

    @classmethod
    def __prepare__(mcs, name, bases, **kwargs):
        # Step 1: Called FIRST. Returns the namespace dict for the class body.
        print(f'[__prepare__] Preparing namespace for class: {name}')
        return super().__prepare__(name, bases, **kwargs)  # return an ordinary dict

    def __new__(mcs, name, bases, namespace, **kwargs):
        # Step 2: Called AFTER class body executes. namespace is now populated.
        print(f'[__new__] Assembling class object: {name}')
        print(f'          Attributes collected: {list(namespace.keys())}')
        return super().__new__(mcs, name, bases, namespace)

    def __init__(cls, name, bases, namespace, **kwargs):
        # Step 3: Called on the freshly created class object.
        print(f'[__init__] Initialising class: {name}')
        super().__init__(name, bases, namespace)

print('\n--- Class definition triggers the protocol ---')
class Rocket(metaclass=TracingMeta):
    fuel_type = 'liquid_hydrogen'

    def launch(self):
        return 'Lift off!'

print(f'\nRocket metaclass: {type(Rocket)}')

# ================================================================
# Pattern 1: Auto-Registry Metaclass
# Use case: A plugin system where each subclass registers itself.
# ================================================================

class PluginRegistryMeta(type):
    """Every class using this metaclass is auto-registered by its name."""

    # This dict lives on the metaclass, shared across all classes it creates.
    _registry: dict = {}

    def __new__(mcs, name, bases, namespace):
        cls = super().__new__(mcs, name, bases, namespace)

        # Don't register the abstract base class itself — only subclasses.
        if bases:  # bases is empty tuple for the root class
            mcs._registry[name] = cls
            print(f'  [Registry] Registered plugin: "{name}"')

        return cls

    @classmethod
    def get_plugin(mcs, name: str):
        """Look up a plugin class by its string name."""
        if name not in mcs._registry:
            raise KeyError(f'No plugin named "{name}". Available: {list(mcs._registry)}')
        return mcs._registry[name]


class DataExporter(metaclass=PluginRegistryMeta):
    """Abstract base — defines the contract for all exporters."""
    def export(self, data: list) -> str:
        raise NotImplementedError

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

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

# At runtime, fetch and use a plugin by name (e.g. from a config file)
exporter_name = 'CsvExporter'  # imagine this comes from config.yaml
exporter_class = PluginRegistryMeta.get_plugin(exporter_name)
result = exporter_class().export([1, 2, 3])
print(f'  Export result: {result}\n')


# ================================================================
# Pattern 2: Interface Enforcement Metaclass
# Use case: Ensure concrete classes implement required methods.
# ================================================================

class InterfaceEnforcerMeta(type):
    """Raises TypeError at CLASS DEFINITION TIME if required methods are missing."""

    REQUIRED_METHODS = ('process', 'validate', 'report')

    def __new__(mcs, name, bases, namespace):
        cls = super().__new__(mcs, name, bases, namespace)

        # Only enforce on subclasses, not the abstract base itself
        is_abstract = not bases
        if not is_abstract:
            missing = [
                method for method in mcs.REQUIRED_METHODS
                if not callable(getattr(cls, method, None))
            ]
            if missing:
                raise TypeError(
                    f'Class "{name}" must implement: {missing}. '
                    f'Define these methods or your class cannot be created.'
                )
        return cls


class DataPipeline(metaclass=InterfaceEnforcerMeta):
    """Base class — subclasses MUST implement process, validate, report."""
    pass

class SalesPipeline(DataPipeline):
    def process(self):
        return 'Processing sales data'

    def validate(self):
        return 'Validating schema'

    def report(self):
        return 'Generating sales report'

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

# This will raise TypeError AT CLASS DEFINITION — not when you call the method
try:
    class BrokenPipeline(DataPipeline):
        def process(self):
            return 'only partial implementation'
        # Missing: validate, report
except TypeError as error:
    print(f'  Caught at definition time: {error}\n')


# ================================================================
# Pattern 3: Attribute Transformation — auto-add docstrings audit
# Use case: Enforce that every public method has a docstring.
# ================================================================

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

    def __new__(mcs, name, bases, namespace):
        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):
            # No docstring!
            return True
except ValueError as error:
    print(f'  Caught: {error}')

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

class MetaA(type):
    def __new__(mcs, name, bases, namespace):
        print(f'  [MetaA.__new__] building {name}')
        return super().__new__(mcs, name, bases, namespace)

class MetaB(type):
    def __new__(mcs, name, bases, namespace):
        print(f'  [MetaB.__new__] building {name}')
        return super().__new__(mcs, name, bases, namespace)

class ClassWithMetaA(metaclass=MetaA):
    pass

class ClassWithMetaB(metaclass=MetaB):
    pass

# Trying to combine them directly causes a TypeError:
try:
    class Combined(ClassWithMetaA, ClassWithMetaB):
        pass
except TypeError as conflict:
    print(f'  Conflict: {conflict}')

# THE FIX: create a merged metaclass that inherits from both.
# Python's MRO kicks in and both __new__ methods run cooperatively.
class MetaMerged(MetaA, MetaB):
    """A combined metaclass. super() chains MetaA -> MetaB -> type correctly."""
    pass

print('\n  Building Combined with MetaMerged:')
class CombinedFixed(ClassWithMetaA, ClassWithMetaB, metaclass=MetaMerged):
    working_attribute = True

print(f'  CombinedFixed metaclass: {type(CombinedFixed).__name__}\n')


# ================================================================
# Gotcha 2: Using __prepare__ to catch duplicate attribute names
# Real use case: Enum-like structures where duplicates are a bug
# ================================================================

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

    def __setitem__(self, key: str, value):
        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, bases, **kwargs):
        # Returning a custom dict — the class body will write into THIS object
        return DuplicateDetectingNamespace()

    def __new__(mcs, name, bases, namespace, **kwargs):
        # Convert back 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}')

try:
    class BrokenStatusCodes(metaclass=NoDuplicatesMeta):
        OK = 200
        NOT_FOUND = 404
        OK = 201  # Duplicate! This would silently overwrite without our metaclass
except AttributeError as duplicate_error:
    print(f'  Caught duplicate: {duplicate_error}')


# ================================================================
# Gotcha 3: Metaclass __new__ vs __init__ — wrong hook, silent bug
# ================================================================

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

    def __init__(cls, name, bases, namespace):
        # bases here is the ORIGINAL tuple — mutating it won't change the class
        # This is a no-op. Don't do this.
        bases = bases + (object,)  # pointless — cls is already constructed
        super().__init__(name, bases, namespace)
        print(f'  [{name}] bases at __init__ time: {cls.__bases__}')  # unchanged

class CorrectHookMeta(type):
    """Correct: intercept bases in __new__ where you can influence construction."""

    def __new__(mcs, name, bases, namespace):
        # Here we CAN add or modify bases before the class is built
        if object not in bases:
            bases = bases + (object,)  # this actually works
        return super().__new__(mcs, name, bases, namespace)

class MyModel(metaclass=WrongHookMeta):
    pass