Metaclass __new__ — Database Calls Turn 50ms Import into 3s

Every Python framework you have admired — Django's ORM, SQLAlchemy's declarative base, Python's own enum.Enum — uses metaclasses quietly in the background. They are the reason you can define a Django model by simply inheriting from models.Model and writing plain class attributes, and Django magically maps them to database columns without you calling any setup function. That magic is not magic at all; it is metaclasses intercepting the moment a class is born.

The problem metaclasses solve is class-level enforcement and transformation at definition time, not at runtime. With regular decorators or __init_subclass__, you can react after a class is created. Metaclasses let you intercept the creation process itself — validating attributes, injecting methods, registering classes in a global registry, or enforcing coding standards across an entire class hierarchy the instant the interpreter reads a class block.

Where this matters in 2026: as Python codebases scale into larger teams and plugin-heavy architectures, the cost of inconsistency compounds. A team of 30 engineers cannot rely on everyone remembering to call register() after defining a new plugin class, or to decorate every new model with @validate_schema. Metaclasses make the right thing automatic and the wrong thing impossible. That is a real engineering trade-off worth understanding.

The production concern: metaclasses are powerful but unforgiving. Heavy computation in __new__ runs at import time, not at call time — a database query in a metaclass adds latency to every module import, not just the first use. Metaclass conflicts cause TypeError when combining two frameworks with incompatible metaclasses. And forgetting super() in metaclass hooks silently breaks cooperative multiple inheritance in ways that only surface when two class hierarchies are combined months later. This guide covers both the concepts and the operational patterns that prevent these failures.

Metaclass __new__ — The Constructor That Runs at Import Time

A metaclass is the class of a class. Its __new__ method runs when Python builds the class object — at import time, not at instantiation. This means any work inside metaclass __new__ (database calls, file reads, network requests) executes synchronously during module loading. A 50ms import becomes 3s if that metaclass queries a slow API or waits on a connection pool. The class object is the return value of metaclass.__new__; if it blocks, everything downstream blocks.

Metaclass __new__ receives the class name, bases, and namespace dict. You can modify the namespace before the class is created — adding methods, validating attributes, or injecting descriptors. But the critical property: this runs once per class definition, at import time, in the importing thread. No lazy evaluation, no deferred execution. If you raise an exception in __new__, the import fails entirely.

Use metaclasses when you need to enforce invariants across a family of classes — ORM model registration, interface validation, or automatic method decoration. Never use them for I/O. If you need per-class configuration from an external source, load it lazily in a classmethod or descriptor, not in __new__. The cost of a metaclass is paid by every developer who imports your package, every time.

How Python Actually Builds a Class — type, __prepare__, __new__, __init__

Before writing a metaclass, you need to understand what happens when the Python interpreter encounters a class block. The process is more mechanical than it looks, and once you see the steps, metaclasses stop being mysterious.

When the interpreter hits a class statement, it does five things in order. First, it resolves which metaclass to use — either the explicit metaclass= keyword argument, the metaclass of the first base class, or type as the default. Second, it calls metaclass.__prepare__(name, bases) to get the namespace dict that the class body will write into — by default this is a plain dict, but you can return anything that implements __setitem__. Third, the class body executes — every assignment, def, and expression runs and writes into that namespace dict. Fourth, metaclass.__new__(mcs, name, bases, namespace) is called with the populated namespace — this is where the actual class object is constructed and returned. Fifth, metaclass.__init__(cls, name, bases, namespace) is called on the class that __new__ just returned — this is where you configure an already-built class.

The critical distinction between __new__ and __init__: __new__ returns the class object, so it is the only hook where you can replace or fundamentally alter what gets built. __init__ receives the class that __new__ already returned — you can add attributes to it, but you cannot change its bases, replace it with a different object, or undo what __new__ did. This distinction catches almost everyone who writes their first metaclass.

The type(name, bases, namespace) three-argument form is not a special function — it is literally the same call path the interpreter uses. Calling type('MyClass', (object,), {'x': 1}) produces a class identical to writing class MyClass: x = 1. Understanding this removes any remaining mystery: metaclasses are just classes whose __new__ and __init__ receive class construction arguments instead of instance construction arguments.

# ================================================================
# 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}')

Dynamic Class Creation with type()

You have already seen that type(name, bases, namespace) is the engine behind every class block. But calling type() directly is not just an educational trick — it is a production technique for building classes dynamically from data, configuration, or runtime conditions.

Why would you create a class dynamically? In database-backed applications, ORMs like SQLAlchemy use this to generate mapped classes from table definitions without hardcoding each one. In plugin systems, you might create a class from a configuration file that specifies method names and attributes. In testing, you can generate mock classes on the fly without writing dozens of stub definitions.

The key insight: when you call type() directly, you bypass the class statement syntax but not the metaclass. If you call type('MyClass', (Base,), {'attr': 1}) and Base uses a custom metaclass, that metaclass is used automatically — Python resolves the metaclass from the bases just as it would with a class statement. This means dynamic class creation respects all the same hooks: __prepare__, __new__, __init__. Any registry or validation logic in the metaclass runs exactly as if the class were defined with the class keyword.

This is most useful when combined with factory functions. You can write a function that inspects a schema, builds a namespace dict with computed methods, and returns a class — all without any class keyword. The resulting class is indistinguishable from one written manually, and Python's type system treats it identically.

A common production pattern: type() inside a metaclass's own __new__ for building subclasses dynamically, or for generating proxy classes that wrap external data sources. Because type() is the default metaclass, calling it with a custom metaclass as the first argument (e.g., CustomMeta('Name', (object,), ns)) allows you to create classes under the control of that exact metaclass — useful when building AST-based libraries or when you need to reproduce a class from a serialised definition.

The performance considerations: type() calls are cheap — they are just function calls — but the metaclass hooks they trigger can be expensive if they do I/O. When creating classes dynamically in a loop, ensure the metaclass's __new__ is lightweight, or cache the generated classes to avoid repeated dynamic construction.

# ================================================================
# Dynamic Class Creation Using type()
# ================================================================

def create_model_class(table_name: str, columns: dict) -> type:
    """
    Create a model class for a given database table.
    Each column becomes an attribute with default value.
    """
    namespace = {'__tablename__': table_name}
    for col_name, col_type in columns.items():
        # Store column type as annotation
        namespace[col_name] = None
        namespace['__annotations__'] = {
            **namespace.get('__annotations__', {}),
            col_name: col_type
        }
    # Add a method to display the object
    def __repr__(self):
        attrs = ', '.join(f'{k}={v}' for k, v in vars(self).items())
        return f'{table_name}({attrs})'
    namespace['__repr__'] = __repr__

    # Dynamically create the class — metaclass resolved from base
    return type(table_name, (object,), namespace)

# Usage:
User = create_model_class('User', {'id': int, 'name': str, 'email': str})
user = User()
user.id = 1
user.name = 'Alice'
print(repr(user))  # User(id=1, name=Alice, email=None)

print(f'type(User).__name__: {type(User).__name__}')  # 'type' (default)
print(f'User is a class: {isinstance(User, type)}')   # True


# ================================================================
# Dynamic Class with Custom Metaclass
# ================================================================

class ValidatingMeta(type):
    """Ensures all attributes have type annotations."""
    def __new__(mcs, name, bases, namespace):
        for key, value in namespace.items():
            if not key.startswith('_') and callable(value):
                if not hasattr(value, '__annotations__') or not value.__annotations__:
                    raise TypeError(f'Method {key} in {name} must have annotations')
        return super().__new__(mcs, name, bases, namespace)

# Create a class with our metaclass dynamically
BaseClass = type('Base', (object,), {}, metaclass=ValidatingMeta)
# But that's not quite right: type() with custom metaclass -> we need to call the metaclass directly
# Better: use the metaclass's __new__ directly
# Actually we can call type() with metaclass kwarg? No, type doesn't accept metaclass.
# Instead, call the metaclass constructor:

MyClass = ValidatingMeta('MyClass', (object,), {
    'x': 5,
    'def method(self, a: int) -> int': lambda self, a: a + 1,  # note: need proper function
})
# Better to define function first:
def method(self, a: int) -> int:
    return a + 1

MyClass = ValidatingMeta('MyClass', (object,), {'x': 5, 'method': method})
print(f'MyClass created with metaclass {type(MyClass).__name__}')  # ValidatingMeta

Writing Metaclasses That Actually Solve Real Problems

Theory lands when you see a genuine use case. Three patterns cover the vast majority of legitimate metaclass use in production codebases today.

Pattern 1 — Auto-Registry: Every subclass of a base class is automatically registered in a lookup table the moment it is defined, without any manual register() call. Plugin systems, command-line tool dispatchers, serialisers, and event handler systems all use this. The alternative — requiring developers to manually call register() after every new class — produces bugs whenever someone forgets, and those bugs are silent: the plugin exists, it just is not reachable.

Pattern 2 — Interface Enforcement: Every concrete subclass is guaranteed to implement certain methods at class definition time, not at instantiation time. This catches missing method implementations in CI rather than in production at 2am when a code path is first exercised. The difference between a metaclass and an ABC here is timing: ABCs raise at instantiation, metaclasses raise when the class is defined.

Pattern 3 — Attribute Validation and Transformation: The metaclass intercepts the namespace before the class is frozen. This is how you enforce that all public methods have docstrings, that attribute names follow a naming convention, or that type annotations are present on every method. None of this is possible with __init_subclass__ because by the time __init_subclass__ fires, the class is already built and the namespace is no longer accessible as a mutable dict.

Importantly: always call super() in every hook. Metaclass inheritance chains are fragile, and skipping super() breaks cooperative multiple inheritance silently. The symptom is a class that works in isolation but produces TypeError or wrong behaviour the moment it is combined with another class hierarchy — typically months after the metaclass was written.

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}')

Singleton Implementation Using Metaclass __call__

The Singleton pattern ensures that a class has only one instance and provides a global point of access to it. Metaclasses offer a clean, Pythonic way to implement Singletons by controlling instance creation via the __call__ method.

When you call MyClass(), Python invokes the metaclass's __call__ method. By default, it calls __new__ on the class and then __init__. If you override __call__ in the metaclass, you can intercept instance creation entirely — returning the same instance every time.

This approach is superior to decorating classes or using a global variable because it is transparent to the user. No special import, no get_instance() method — the class simply behaves as a singleton by default. Any code that uses MyClass() gets the same object, and the instantiation logic is encapsulated in the metaclass.

The trade-off: Singletons are often considered an anti-pattern because they introduce hidden global state. In 2026 production code, prefer dependency injection or module-level caches. However, when you need a genuine singleton — like a configuration manager or a connection pool — the metaclass approach is the cleanest Pythonic implementation.

Performance note: The __call__ hook fires on every instantiation attempt, so keep it lightweight — a simple dict lookup for the cached instance. Avoid I/O or expensive computation there; initialise those in the __init__ of the instance itself (only runs once).

# ================================================================
# Singleton Metaclass Using __call__
# ================================================================

import threading

class SingletonMeta(type):
    """
    Metaclass that implements the Singleton pattern.
    Every class using this metaclass will have exactly one instance.
    """
    _instances = {}
    _lock = threading.Lock()

    def __call__(cls, *args, **kwargs):
        # Double-checked locking for thread safety
        if cls not in cls._instances:
            with cls._lock:
                if cls not in cls._instances:
                    # Create the instance using the parent's __call__
                    instance = super().__call__(*args, **kwargs)
                    cls._instances[cls] = instance
        return cls._instances[cls]


class ConfigurationManager(metaclass=SingletonMeta):
    def __init__(self):
        self._config = {}
        # Simulate loading configuration (would be from file or env)
        self._config['database_url'] = 'postgresql://localhost:5432/mydb'
        self._config['api_key'] = 'some-secret-key'
        print('ConfigurationManager instance created (once)')

    def get(self, key: str) -> str:
        return self._config.get(key, '')


# Usage: both variables point to the same object
config_a = ConfigurationManager()
print(f'Database URL: {config_a.get("database_url")}')

config_b = ConfigurationManager()
print(f'config_a is config_b: {config_a is config_b}')  # True


# ================================================================
# Singleton with Lazy Initialisation
# ================================================================

class ConnectionPool(metaclass=SingletonMeta):
    def __init__(self, max_connections: int = 10):
        self.max_connections = max_connections
        self._connections = []
        print(f'ConnectionPool initialised with max_connections={max_connections}')

# First call initialises with max_connections=20
pool = ConnectionPool(max_connections=20)
# Subsequent calls ignore parameters (singleton already exists)
pool2 = ConnectionPool(max_connections=999)
print(f'pool is pool2: {pool is pool2}')  # True
print(f'pool.max_connections: {pool.max_connections}')  # 20 (first args preserved)

Metaclass vs Class Decorator Comparison Table

Class decorators and metaclasses overlap in capability but differ fundamentally in when and how they act. Understanding these differences is critical for choosing the right tool.

Class Decorators execute after the class has been fully constructed. They receive the class object and can wrap, modify, or replace it. The decorator runs once when the class is defined (assuming the decorator is applied at definition time). They are simple, well-understood, and do not interfere with inheritance or MRO.

Metaclasses execute during class construction itself. They can intercept the namespace before the class is built (via __prepare__), modify the class during creation (__new__), and configure it after creation (__init__). Metaclasses are inherited by subclasses automatically, which is both powerful and dangerous.

Here is the comparison table:

When to choose which: Use a class decorator when you need to add behaviour to an existing class without altering its construction process. Use a metaclass when you need to enforce invariants at class definition time, when you want the behaviour to apply automatically to every subclass, or when you need to customise the namespace before the class body finishes executing.

Real-world examples: Django's models.Model could be implemented with a decorator, but the decorator would have to be manually applied to every model — and it would run after the class is created, making it impossible to rewrite the class's internals as Django does. Similarly, enum.Enum uses a metaclass because it must intercept attribute definitions to create enum members. If you are adding __repr__ or __init__ to a class, use a decorator — not a metaclass.

# ================================================================
# Metaclass vs Class Decorator: Same Goal, Different Timing
# ================================================================

# Goal: Add a 'created_at' timestamp to every class

# ---- Approach 1: Class Decorator ----
import time

def add_timestamp(cls):
    cls.created_at = time.time()
    return cls

@add_timestamp
class DecoratedClass:
    pass

print(f'DecoratedClass.created_at (decorator): {DecoratedClass.created_at}')

# ---- Approach 2: Metaclass ----
class TimestampMeta(type):
    def __new__(mcs, name, bases, namespace):
        cls = super().__new__(mcs, name, bases, namespace)
        cls.created_at = time.time()
        return cls

class MetaClass(metaclass=TimestampMeta):
    pass

print(f'MetaClass.created_at (metaclass): {MetaClass.created_at}')

# Difference: metaclass applies to all subclasses automatically:
class SubMeta(MetaClass):
    pass

print(f'SubMeta.created_at (inherited): {SubMeta.created_at}')  # Has its own timestamp

# With decorator, you must manually apply to each subclass:
@add_timestamp
class SubDecorated(DecoratedClass):
    pass

print(f'SubDecorated.created_at (must decorate): {SubDecorated.created_at}')
print(f'SubDecorated.created_at is same as DecoratedClass.created_at? {
    SubDecorated.created_at == DecoratedClass.created_at
}')
# The decorator ran on SubDecorated, but not automatically

print('\n--- Key difference: inheritance of behaviour ---')
# Metaclass's __new__ runs for each subclass independently; decorator must be repeated.
# But decorator is simpler and easier to understand.

Metaclass Conflicts, MRO Pitfalls, and Production Gotchas

This is where intermediate developers become advanced ones: understanding what breaks when metaclasses collide and what to do about it.

The Metaclass Conflict Error: If you try to create a class that inherits from two classes with different, incompatible metaclasses, Python raises TypeError: metaclass conflict: the metaclass of a derived class must be a (non-strict) subclass of the metaclasses of all its bases. This happens in real projects when you combine a Django model (metaclass: ModelBase) with a third-party mixin that uses its own metaclass, or when two libraries that each bring metaclass-based functionality are composed in the same class hierarchy. The fix is a merged metaclass that inherits from both — Python's MRO then chains their __new__ methods cooperatively via super().

Performance at Import Time: Metaclass __new__ runs once per class definition, which happens at import time. The performance cost is not per-instance and not per-call — it is per-import. That means heavy computation in __new__ adds to startup latency and to pytest collection time, both of which compound as the codebase grows. Profile with python -X importtime your_module.py before and after adding any metaclass to a high-import-count module.

__prepare__ and Custom Namespaces: The __prepare__ hook returns the dict-like object that the class body writes into. Since Python 3.7 this is an ordered dict by default, so __prepare__ is only needed when you want non-dict semantics — for example, a namespace that raises on duplicate attribute names (Python normally overwrites silently) or a namespace that type-checks entries as they are assigned.

MRO Order in Merged Metaclasses: When you write class MergedMeta(MetaA, MetaB): pass, the MRO determines the order in which __new__ and __init__ fire. Always put the more specific or more critical metaclass first. Reversing the order can cause one metaclass's transformations to be undone or overwritten by the other, producing behaviour that is correct in unit tests but wrong when both metaclasses are active.

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__}')

Metaclass Inheritance — Why Your Child Classes Suddenly Break

Metaclasses propagate through inheritance. If Parent uses Meta, every subclass of Parent also uses Meta — whether you want it or not. This is not a 'feature you can opt into'. It's a viral constraint.

The worst production bug I debugged was a TypeError from a metaclass conflict. Two unrelated metaclasses both applied to the same class through diamond inheritance. Python's MRO couldn't merge them, and the class definition failed at import time — not at runtime. Your app crashed before a single request.

You cannot simply inherit from two classes with different metaclasses unless one metaclass is a subclass of the other. Otherwise, you get TypeError: metaclass conflict. The fix: create a unifying metaclass that inherits from both conflicting metaclasses. That forces the MRO to accept it.

// io.thecodeforge — python tutorial

class MetaA(type):
    def __new__(cls, name, bases, dct):
        dct['from_a'] = True
        return super().__new__(cls, name, bases, dct)

class MetaB(type):
    def __new__(cls, name, bases, dct):
        dct['from_b'] = True
        return super().__new__(cls, name, bases, dct)

class BaseA(metaclass=MetaA):
    pass

class BaseB(metaclass=MetaB):
    pass

# This will crash:
# class Child(BaseA, BaseB):
#     pass
# TypeError: metaclass conflict

# Fix: create unified metaclass
class MetaAB(MetaA, MetaB):
    pass

class BaseA_AB(metaclass=MetaAB):
    pass

class BaseB_AB(metaclass=MetaAB):
    pass

class SafeChild(BaseA_AB, BaseB_AB):
    pass

print(SafeChild.from_a)   # True
print(SafeChild.from_b)   # True

Dynamic Class Generation — Stop Copy-Pasting Class Definitions

You don't need a metaclass for every dynamic class problem. Sometimes you just need type(name, bases, dict) at runtime. This is how frameworks like Django and SQLAlchemy generate hundreds of model classes without you writing each one.

The classic use case: you have a set of configuration objects that differ only by a few attributes. Instead of writing ten nearly identical classes, generate them in a loop using type(). Each call to type() is a class creation instruction — same as class keyword, just programmatic.

Where this fails is when you need cross-cutting behavior — like auto-registering every subclass, or enforcing interface contracts. For that, a metaclass gives you hooks at class creation time. For everything else, type() is cleaner, simpler, and won't cause metaclass conflict nightmares.

// io.thecodeforge — python tutorial

def make_model(database, table_name):
    def save(self):
        print(f"Saving {self} to {database}.{table_name}")
    
    # Dynamically create a class with a save method
    cls = type(table_name.title(), (object,), {
        '__init__': lambda self, **kwargs: self.__dict__.update(kwargs),
        '__repr__': lambda self: f"{table_name}({self.__dict__})",
        'save': save
    })
    return cls

UserModel = make_model('production_db', 'users')
OrderModel = make_model('production_db', 'orders')

user = UserModel(name='Alice', email='alice@ex.com')
order = OrderModel(id=101, amount=250.0)

user.save()
order.save()

Old-Style vs. New-Style Classes — The Legacy Landmine You Inherit

If you touch Python 2 code, or Python 3 code that was ported lazily, you will encounter old-style classes. These do not inherit from object. They do not support metaclasses. They use a different method resolution order — depth-first, left-to-right — which is wrong for any real diamond inheritance.

New-style classes (Python 2.2+, and all classes in Python 3) inherit from object by default. They support type as the default metaclass, descriptors, properties, super(), and proper C3 linearization MRO.

The rule is simple: every class you write in Python 3 is a new-style class. But if you see class Foo: without object in Python 2 compat code, or if you see type.__new__ failing silently, you're dealing with an old-style class that doesn't invoke the metaclass.

Metaclasses only work on new-style classes. Full stop. If you're maintaining legacy code and your metaclass isn't firing, check whether your classes explicitly inherit from object.

// io.thecodeforge — python tutorial

class OldStyle:
    pass

class NewStyle(object):
    pass

# Metaclass only works on new-style
class Meta(type):
    def __new__(cls, name, bases, dct):
        dct['injected'] = True
        return super().__new__(cls, name, bases, dct)

# This old-style approach won't trigger the metaclass
class OldWithMeta(OldStyle, metaclass=Meta):
    pass

# In Python 3 this actually works because OldStyle inherits from object implicitly
# But in Python 2, this breaks silently

print(hasattr(OldWithMeta, 'injected'))  # True in Python 3, but the syntax is valid

# Real legacy problem:
# class OldLegacy:
#     pass
# class Derived(OldLegacy, metaclass=SomeMeta):  # SyntaxError in Python 2
#     pass

print("New-style classes support metaclasses. Old-style in Python 2 don't.")

Stop Writing Metaclasses That Do Nothing — *init_subclass* Is Right There

Every week I see someone reinvent the wheel with a metaclass just to run code when a subclass is created. They reach for the heavy artillery when a simple class method does the job better — and with zero MRO headaches.

The rule is brutal: if your metaclass only hooks class creation to validate, register, or modify subclasses, you don't need a metaclass. Python 3.6 gave us __init_subclass__. It runs automatically when any class inherits from yours. No metaclass conflicts. No __prepare__ ceremony. Just a clean hook that behaves exactly like a classmethod.

Why this matters: metaclasses multiply complexity. __init_subclass__ does not. You can add it to a mixin, an abstract base, or a utility parent. It inherits normally. It doesn't break MRO when someone else's metaclass shows up. It's the production-safe alternative everyone overlooks.

// io.thecodeforge — python tutorial

class PluginBase:
    registry = {}

    @classmethod
    def __init_subclass__(cls, name=None, **kwargs):
        super().__init_subclass__(**kwargs)
        alias = name or cls.__name__.lower()
        if alias in cls.registry:
            raise ValueError(f"Plugin '{alias}' already registered")
        cls.registry[alias] = cls

class LogPlugin(PluginBase, name="logger"):
    pass

class AuditPlugin(PluginBase, name="audit"):
    pass

print(PluginBase.registry)

Metaclass `__set_name__` — The Descriptor Hook That’s Better Than the Alternative

Every time you write a descriptor class, you need to know which class owns it and what attribute name it's bound to. Most devs hack this with __init__ parameters or post-creation patching. Both are fragile. Both break when subclassing or reusing the descriptor.

The right tool is __set_name__. It fires when the metaclass builds the owning class, right after __new__ creates it. It receives the owner class and the attribute name. No magic strings, no later fixups. This is the pattern used by @property, dataclasses, and SQLAlchemy.

Why you need this: without __set_name__, you're guessing names or passing them manually — both are error-prone in production. With it, the metaclass guarantees every descriptor knows its identity automatically, at import time, before any instance is created. That's the kind of guarantee that prevents runtime bugs in your framework code.

// io.thecodeforge — python tutorial

class ValidatedField:
    def __set_name__(self, owner, name):
        self.name = name
        self.private_name = f'_{name}'

    def __get__(self, obj, objtype=None):
        return getattr(obj, self.private_name)

    def __set__(self, obj, value):
        if not isinstance(value, str):
            raise TypeError(f'{self.name} must be a string')
        setattr(obj, self.private_name, value)

class User:
    username = ValidatedField()
    email = ValidatedField()

    def __init__(self, username, email):
        self.username = username
        self.email = email

u = User('alice', 'alice@example.com')
print(u.username)

# u.username = 42  # raises TypeError

Metaclasses vs Class Decorators: When to Use Each

Both metaclasses and class decorators can modify class behavior, but they operate at different stages and have distinct use cases. Class decorators run after the class is created, making them ideal for simple modifications like adding methods or attributes, registering classes, or applying transformations that don't require altering the class creation process. Metaclasses, on the other hand, intercept the class creation itself, allowing you to modify the class body, enforce constraints, or inject dependencies before the class object exists.

Consider a scenario where you want to automatically add a created_at timestamp to every instance. A class decorator can easily do this:

```python def add_timestamp(cls): original_init = cls.__init__ def new_init(self, args, kwargs): self.created_at = datetime.now() original_init(self, args, **kwargs) cls.__init__ = new_init return cls

@add_timestamp class MyClass: pass ```

But if you need to ensure that all subclasses also get this behavior, a metaclass is better because it applies to the entire inheritance hierarchy:

```python class TimestampMeta(type): def __call__(cls, args, kwargs): instance = super().__call__(args, **kwargs) instance.created_at = datetime.now() return instance

class MyBase(metaclass=TimestampMeta): pass

class MySubclass(MyBase): pass # automatically gets timestamp ```

When to use each: - Class decorator: Simple, single-class modifications; no inheritance concerns; when you want to keep things explicit and easy to debug. - Metaclass: When you need to enforce patterns across an entire class hierarchy; when you need to modify the class before it's fully constructed; when you're building frameworks like ORMs or validation systems.

A good rule of thumb: if you can solve it with a class decorator, do so. Metaclasses add complexity and should be reserved for problems that genuinely require them.

from datetime import datetime

# Class decorator approach
def add_timestamp(cls):
    original_init = cls.__init__
    def new_init(self, *args, **kwargs):
        self.created_at = datetime.now()
        original_init(self, *args, **kwargs)
    cls.__init__ = new_init
    return cls

@add_timestamp
class MyClass:
    pass

# Metaclass approach
class TimestampMeta(type):
    def __call__(cls, *args, **kwargs):
        instance = super().__call__(*args, **kwargs)
        instance.created_at = datetime.now()
        return instance

class MyBase(metaclass=TimestampMeta):
    pass

class MySubclass(MyBase):
    pass

Singleton Pattern with Metaclass

The singleton pattern ensures a class has only one instance and provides a global point of access. While there are many ways to implement singletons in Python, using a metaclass is one of the cleanest approaches because it centralizes the logic and works with inheritance.

The idea is to override the __call__ method of the metaclass, which is invoked when you create an instance of the class. By storing the instance in the metaclass and returning it on subsequent calls, you guarantee only one instance exists.

Here's a simple singleton metaclass:

```python class SingletonMeta(type): _instances = {}

def __call__(cls, args, kwargs): if cls not in cls._instances: cls._instances[cls] = super().__call__(args, **kwargs) return cls._instances[cls]

class Database(metaclass=SingletonMeta): def __init__(self): print("Connecting to database...")

# Usage db1 = Database() # prints "Connecting to database..." db2 = Database() # does not print; returns same instance print(db1 is db2) # True ```

How it works: - SingletonMeta._instances is a dictionary mapping classes to their single instances. - When Database() is called, SingletonMeta.__call__ runs. - If the class is not in _instances, it creates the instance via super().__call__() and stores it. - Subsequent calls return the cached instance.

Thread safety: The above implementation is not thread-safe. For production, add a lock:

```python import threading

class ThreadSafeSingletonMeta(type): _instances = {} _lock = threading.Lock()

def __call__(cls, args, kwargs): if cls not in cls._instances: with cls._lock: if cls not in cls._instances: cls._instances[cls] = super().__call__(args, **kwargs) return cls._instances[cls] ```

When to use metaclass singletons: They are ideal for resources like database connections, configuration managers, or logging services where you want a single point of control. However, be aware that singletons can make testing difficult and introduce hidden global state.

import threading

class SingletonMeta(type):
    _instances = {}
    _lock = threading.Lock()

    def __call__(cls, *args, **kwargs):
        if cls not in cls._instances:
            with cls._lock:
                if cls not in cls._instances:
                    cls._instances[cls] = super().__call__(*args, **kwargs)
        return cls._instances[cls]

class Database(metaclass=SingletonMeta):
    def __init__(self):
        print("Connecting to database...")

# Test
db1 = Database()
db2 = Database()
assert db1 is db2
print("Singleton works!")

ORM Implementation Pattern with Metaclasses

Object-Relational Mappers (ORMs) like SQLAlchemy or Django's ORM use metaclasses to convert class definitions into database table schemas. The metaclass intercepts class creation to read attributes, map them to columns, and register the class with a global registry.

Here's a simplified ORM metaclass that automatically creates a table for each class and provides a save() method:

```python class ModelMeta(type): def __new__(mcs, name, bases, namespace): if name == 'Model': return super().__new__(mcs, name, bases, namespace) # Collect fields (attributes that are Field instances) fields = {} for key, value in namespace.items(): if isinstance(value, Field): fields[key] = value # Store fields in a special attribute namespace['_fields'] = fields namespace['_table_name'] = name.lower() cls = super().__new__(mcs, name, bases, namespace) # Register the model (simulate table creation) print(f"Creating table {cls._table_name} with columns: {list(fields.keys())}") return cls

class Field: def __init__(self, field_type): self.field_type = field_type

class Model(metaclass=ModelMeta): def save(self): # Simulate INSERT fields = self._fields values = {name: getattr(self, name) for name in fields} print(f"INSERT INTO {self._table_name} ({', '.join(values.keys())}) VALUES ({', '.join(repr(v) for v in values.values())})")

class User(Model): name = Field(str) age = Field(int)

# Usage user = User() user.name = "Alice" user.age = 30 user.save() ```

How it works: - ModelMeta.__new__ runs when any class using it as metaclass is defined. - It scans the class namespace for Field instances and collects them into _fields. - It sets a _table_name based on the class name. - The base Model class provides a save() method that uses the collected metadata. - When User is defined, the metaclass prints "Creating table user with columns: ['name', 'age']".

Real-world considerations: - Real ORMs handle relationships, indexes, migrations, and much more. - They often use __init_subclass__ for simpler cases, but metaclasses give full control over class creation. - The pattern above is a minimal example; production ORMs use sophisticated descriptor protocols and caching.

This pattern demonstrates how metaclasses can transform declarative class definitions into active database operations, reducing boilerplate and enforcing consistency.

class ModelMeta(type):
    def __new__(mcs, name, bases, namespace):
        if name == 'Model':
            return super().__new__(mcs, name, bases, namespace)
        
        fields = {}
        for key, value in namespace.items():
            if isinstance(value, Field):
                fields[key] = value
        
        namespace['_fields'] = fields
        namespace['_table_name'] = name.lower()
        
        cls = super().__new__(mcs, name, bases, namespace)
        print(f"Creating table {cls._table_name} with columns: {list(fields.keys())}")
        return cls

class Field:
    def __init__(self, field_type):
        self.field_type = field_type

class Model(metaclass=ModelMeta):
    def save(self):
        fields = self._fields
        values = {name: getattr(self, name) for name in fields}
        print(f"INSERT INTO {self._table_name} ({', '.join(values.keys())}) VALUES ({', '.join(repr(v) for v in values.values())})")

class User(Model):
    name = Field(str)
    age = Field(int)

# Test
user = User()
user.name = "Alice"
user.age = 30
user.save()