Metaclasses & the Class Creation Protocol

# Every class is an instance of type
print(type(int))      # <class 'type'>
print(type(str))      # <class 'type'>
print(type(list))     # <class 'type'>

class MyClass:
    pass

print(type(MyClass))  # <class 'type'>
print(isinstance(MyClass, type))  # True

# type is its own metaclass
print(type(type))     # <class 'type'>

# The type hierarchy
print(issubclass(type, object))   # True
print(issubclass(object, type))   # False
print(isinstance(type, object))   # True — type is an instance of object

# type(name, bases, namespace) creates a new class
MyDynamic = type("MyDynamic", (object,), {
    "x": 42,
    "greet": lambda self: f"Hello from {type(self).__name__}",
})

obj = MyDynamic()
print(obj.greet())   # Hello from MyDynamic
print(obj.x)         # 42
print(type(MyDynamic))   # <class 'type'>

# This is EXACTLY what the `class` statement does internally

class TracingMeta(type):
    @classmethod
    def __prepare__(mcs, name, bases, **kwargs):
        print(f"  __prepare__({name!r}, {[b.__name__ for b in bases]})")
        return super().__prepare__(name, bases, **kwargs)   # returns a dict

    def __new__(mcs, name, bases, namespace, **kwargs):
        print(f"  __new__({name!r}, attrs={list(namespace.keys())})")
        return super().__new__(mcs, name, bases, namespace)

    def __init__(cls, name, bases, namespace, **kwargs):
        print(f"  __init__({name!r})")
        super().__init__(name, bases, namespace)

class Base(metaclass=TracingMeta):
    x = 1

# Output:
#   __prepare__('Base', [])
#   __new__('Base', attrs=['__module__', '__qualname__', 'x'])
#   __init__('Base')

class Child(Base):
    y = 2

# Output:
#   __prepare__('Child', ['Base'])
#   __new__('Child', attrs=['__module__', '__qualname__', 'y'])
#   __init__('Child')

import re

class InterfaceMeta(type):
    """
    Enforces that every concrete (non-abstract) subclass:
    1. Implements all methods listed in `__required_methods__`
    2. Uses snake_case names for public methods
    3. Has a docstring
    """
    _SNAKE = re.compile(r'^[a-z_][a-z0-9_]*$')

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

        # Skip the base class itself
        if not bases:
            return cls

        required = set()
        for base in bases:
            required.update(getattr(base, '__required_methods__', []))

        # Check all required methods are implemented
        for method_name in required:
            if not callable(getattr(cls, method_name, None)):
                raise TypeError(
                    f"Class '{name}' must implement '{method_name}()'"
                )

        # Enforce snake_case on public methods
        for attr, val in namespace.items():
            if callable(val) and not attr.startswith('_'):
                if not mcs._SNAKE.match(attr):
                    raise NameError(
                        f"Method '{attr}' in '{name}' must be snake_case"
                    )

        # Enforce docstring
        if not cls.__doc__:
            raise TypeError(f"Class '{name}' must have a docstring")

        return cls


class Storage(metaclass=InterfaceMeta):
    """Abstract base for storage backends."""
    __required_methods__ = ["read", "write", "delete"]


class FileStorage(Storage):
    """File-based storage backend."""

    def read(self, key: str) -> bytes:
        """Read bytes from file."""
        return open(key, "rb").read()

    def write(self, key: str, data: bytes) -> None:
        """Write bytes to file."""
        open(key, "wb").write(data)

    def delete(self, key: str) -> None:
        """Delete a file."""
        import os; os.unlink(key)


# This will raise TypeError — missing `delete`
try:
    class BadStorage(Storage):
        """Missing delete method."""
        def read(self, key): pass
        def write(self, key, data): pass
except TypeError as e:
    print(e)  # Class 'BadStorage' must implement 'delete()'

class PluginBase:
    """
    Subclasses automatically register themselves in _registry
    via __init_subclass__.
    """
    _registry: dict[str, type] = {}

    def __init_subclass__(cls, plugin_name: str = None, **kwargs):
        super().__init_subclass__(**kwargs)   # always call super()
        name = plugin_name or cls.__name__.lower()
        if name in PluginBase._registry:
            raise ValueError(f"Plugin '{name}' already registered")
        PluginBase._registry[name] = cls
        print(f"  Registered plugin: '{name}' → {cls.__name__}")

class JSONPlugin(PluginBase, plugin_name="json"):
    def process(self, data): return f"JSON: {data}"

class XMLPlugin(PluginBase, plugin_name="xml"):
    def process(self, data): return f"XML: {data}"

class CSVPlugin(PluginBase):          # uses class name as key: 'csvplugin'
    def process(self, data): return f"CSV: {data}"

print(PluginBase._registry)
# {'json': JSONPlugin, 'xml': XMLPlugin, 'csvplugin': CSVPlugin}

plugin = PluginBase._registry["json"]()
print(plugin.process({"key": "value"}))

class Validator(PluginBase, plugin_name="validate"):
    """Receives plugin_name='validate' from the class statement."""
    def process(self, data): return f"VALID: {data}"

from __future__ import annotations
from typing import TypeVar, Generic

T = TypeVar("T")

# ── Standard library Generic uses __class_getitem__ ──
# list[int], dict[str, int] work because list.__class_getitem__ returns a GenericAlias

print(list[int])         # list[int]   — a types.GenericAlias
print(dict[str, int])    # dict[str, int]

# ── Custom generic class ──
class Stack:
    """A typed stack using __class_getitem__."""

    def __class_getitem__(cls, item):
        """Called when Stack[int] is written."""
        # Return a GenericAlias — allows Stack[int] as a type hint
        import types
        return types.GenericAlias(cls, (item,))

    def __init__(self):
        self._data: list = []

    def push(self, item) -> None:
        self._data.append(item)

    def pop(self):
        return self._data.pop()

    def __repr__(self):
        return f"Stack({self._data!r})"

# Now Stack[int] is valid in type hints
def process(stack: Stack[int]) -> int:
    return stack.pop()

s: Stack[int] = Stack()
s.push(1); s.push(2)
print(process(s))        # 2
print(Stack[int])        # stack.Stack[int]

# ── Metadata-carrying generic alias ──
class TypedCollection:
    _item_type: type = object

    def __class_getitem__(cls, item_type):
        new_cls = type(
            f"{cls.__name__}[{item_type.__name__}]",
            (cls,),
            {"_item_type": item_type},
        )
        return new_cls

    def append(self, item):
        if not isinstance(item, type(self)._item_type):
            raise TypeError(
                f"Expected {type(self)._item_type.__name__}, "
                f"got {type(item).__name__}"
            )
        self._items = getattr(self, "_items", [])
        self._items.append(item)

IntCollection = TypedCollection[int]
c = IntCollection()
c.append(42)
try:
    c.append("hello")
except TypeError as e:
    print(e)  # Expected int, got str

from collections import OrderedDict

class OrderedMeta(type):
    """Metaclass that preserves declaration order of all attributes."""

    @classmethod
    def __prepare__(mcs, name, bases, **kwargs):
        return OrderedDict()   # class body written into an OrderedDict

    def __new__(mcs, name, bases, namespace, **kwargs):
        # namespace is the OrderedDict we returned from __prepare__
        cls = super().__new__(mcs, name, bases, dict(namespace))
        cls._field_order = [
            k for k in namespace
            if not k.startswith("__") and not callable(namespace[k])
        ]
        return cls

class Schema(metaclass=OrderedMeta):
    """Preserves field declaration order."""
    first_name: str = ""
    last_name:  str = ""
    age:        int = 0
    email:      str = ""

    def full_name(self):
        return f"{self.first_name} {self.last_name}"

print(Schema._field_order)
# ['first_name', 'last_name', 'age', 'email'] — guaranteed order

# ── Counting class: use a custom namespace to auto-number fields ──
class NumberedNamespace(dict):
    def __init__(self):
        super().__init__()
        self._counter = 0

    def __setitem__(self, key, value):
        if not key.startswith("_") and isinstance(value, str) and value == "auto":
            value = self._counter
            self._counter += 1
        super().__setitem__(key, value)

class NumberedMeta(type):
    @classmethod
    def __prepare__(mcs, name, bases, **kwargs):
        return NumberedNamespace()

class Fields(metaclass=NumberedMeta):
    first = "auto"
    second = "auto"
    third = "auto"

print(Fields.first, Fields.second, Fields.third)   # 0 1 2

class MetaA(type):
    def __new__(mcs, name, bases, ns):
        print(f"MetaA creating {name}")
        return super().__new__(mcs, name, bases, ns)

class MetaB(type):
    def __new__(mcs, name, bases, ns):
        print(f"MetaB creating {name}")
        return super().__new__(mcs, name, bases, ns)

class A(metaclass=MetaA): pass
class B(metaclass=MetaB): pass

# This raises: TypeError: metaclass conflict: the metaclass of a derived class
# must be a (non-strict) subclass of the metaclasses of all its bases
try:
    class C(A, B): pass
except TypeError as e:
    print(e)

# Fix: create a combined metaclass
class MetaAB(MetaA, MetaB): pass   # inherits from both

class C(A, B, metaclass=MetaAB): pass   # now works

class GenericBase:
    """Supports MyClass[T] in inheritance: class Foo(GenericBase[int])."""

    def __class_getitem__(cls, params):
        class _GenericAlias:
            def __mro_entries__(self, bases):
                # Replace this alias with the actual class in the MRO
                return (cls,)
            def __repr__(self):
                return f"{cls.__name__}[{params!r}]"
        return _GenericAlias()

class IntList(GenericBase[int]):
    """MRO resolves to: IntList → GenericBase → object."""
    pass

print(IntList.__bases__)    # (<class 'GenericBase'>,)
print(IntList.__mro__)      # (IntList, GenericBase, object)

class SingletonMeta(type):
    """Metaclass that ensures only one instance per class."""
    _instances: dict = {}

    def __call__(cls, *args, **kwargs):
        # __call__ on the metaclass intercepts instance creation
        if cls not in cls._instances:
            # super().__call__ runs cls.__new__ then cls.__init__
            cls._instances[cls] = super().__call__(*args, **kwargs)
        return cls._instances[cls]


class Config(metaclass=SingletonMeta):
    def __init__(self, debug: bool = False):
        self.debug = debug

c1 = Config(debug=True)
c2 = Config()
print(c1 is c2)    # True — same object
print(c2.debug)    # True — init only ran once

# Reset for testing
del SingletonMeta._instances[Config]
c3 = Config(debug=False)
print(c3 is c1)    # False — fresh instance


class BorgMeta(type):
    """
    Borg pattern: every instance is distinct but shares __dict__.
    All instances share state without being the same object.
    """
    def __new__(mcs, name, bases, namespace):
        cls = super().__new__(mcs, name, bases, namespace)
        cls._shared_state: dict = {}
        return cls

    def __call__(cls, *args, **kwargs):
        instance = cls.__new__(cls, *args, **kwargs)
        instance.__dict__ = cls._shared_state   # share the dict
        instance.__init__(*args, **kwargs)
        return instance


class AppState(metaclass=BorgMeta):
    def __init__(self, **kw):
        self.__dict__.update(kw)

s1 = AppState(x=1)
s2 = AppState(y=2)
print(s1 is s2)     # False — distinct objects
print(s1.y)         # 2 — shared state
print(s2.x)         # 1 — shared state

class AbstractMeta(type):
    """
    Marks methods decorated with @abstract as requiring implementation.
    Raises TypeError when an abstract class is instantiated directly.
    """
    def __new__(mcs, name, bases, namespace):
        abstract_methods = set()

        # Collect from bases
        for base in bases:
            abstract_methods.update(getattr(base, "_abstract_methods", set()))

        # Add newly marked abstracts, remove ones that are implemented
        for k, v in namespace.items():
            if getattr(v, "_abstract", False):
                abstract_methods.add(k)
            elif k in abstract_methods:
                abstract_methods.discard(k)

        cls = super().__new__(mcs, name, bases, namespace)
        cls._abstract_methods = frozenset(abstract_methods)
        return cls

    def __call__(cls, *args, **kwargs):
        if cls._abstract_methods:
            raise TypeError(
                f"Cannot instantiate abstract class '{cls.__name__}' — "
                f"unimplemented: {sorted(cls._abstract_methods)}"
            )
        return super().__call__(*args, **kwargs)


def abstract(fn):
    """Decorator to mark a method as abstract."""
    fn._abstract = True
    return fn


class Shape(metaclass=AbstractMeta):
    @abstract
    def area(self) -> float: ...

    @abstract
    def perimeter(self) -> float: ...

    def describe(self) -> str:
        return f"{type(self).__name__}: area={self.area():.2f}"


class Circle(Shape):
    def __init__(self, r: float): self.r = r
    def area(self)      -> float: import math; return math.pi * self.r ** 2
    def perimeter(self) -> float: import math; return 2 * math.pi * self.r


c = Circle(5)
print(c.describe())   # Circle: area=78.54

try:
    Shape()
except TypeError as e:
    print(e)   # Cannot instantiate abstract class 'Shape' — unimplemented: ['area', 'perimeter']

# ── Real ABCMeta (stdlib) ──
from abc import ABCMeta, abstractmethod

class Repository(metaclass=ABCMeta):
    @abstractmethod
    def find(self, id: int): ...

    @abstractmethod
    def save(self, entity) -> None: ...

    def find_all(self) -> list:   # concrete method
        return []

class FieldDescriptor:
    """Data descriptor for a model field."""
    def __set_name__(self, owner, name):
        self.name = name
        self.private = f"_{name}"

    def __init__(self, field_type: type, **opts):
        self.field_type = field_type
        self.opts = opts

    def __get__(self, obj, objtype=None):
        if obj is None: return self
        return getattr(obj, self.private, None)

    def __set__(self, obj, value):
        if value is not None and not isinstance(value, self.field_type):
            raise TypeError(f"Field '{self.name}': expected {self.field_type.__name__}")
        setattr(obj, self.private, value)


class ModelMeta(type):
    """
    Metaclass that:
    1. Collects all FieldDescriptor declarations into _meta.fields
    2. Injects a primary key if none is declared
    3. Generates __repr__ automatically
    4. Provides a classmethod .objects.all() stub
    """

    def __new__(mcs, name, bases, namespace, **kwargs):
        fields = {}

        # Inherit fields from base classes
        for base in bases:
            fields.update(getattr(base, "_fields", {}))

        # Collect FieldDescriptor instances from current namespace
        for k, v in list(namespace.items()):
            if isinstance(v, FieldDescriptor):
                fields[k] = v

        # Auto-inject 'id' primary key if not declared
        if "id" not in fields and name != "Model":
            id_field = FieldDescriptor(int, primary_key=True)
            id_field.name    = "id"
            id_field.private = "_id"
            namespace["id"]  = id_field
            fields["id"]     = id_field

        namespace["_fields"] = fields
        cls = super().__new__(mcs, name, bases, namespace)

        # Inject __repr__
        def _repr(self):
            parts = ", ".join(
                f"{k}={getattr(self, k)!r}"
                for k in self._fields
                if getattr(self, k) is not None
            )
            return f"{type(self).__name__}({parts})"
        cls.__repr__ = _repr

        return cls


class Model(metaclass=ModelMeta):
    """Base model class."""
    def __init__(self, **kwargs):
        for k, v in kwargs.items():
            setattr(self, k, v)


class User(Model):
    username = FieldDescriptor(str)
    email    = FieldDescriptor(str)
    age      = FieldDescriptor(int)


class Post(Model):
    title   = FieldDescriptor(str)
    body    = FieldDescriptor(str)
    user_id = FieldDescriptor(int)


u = User(username="alice", email="alice@example.com", age=30)
print(u)           # User(id=None, username='alice', email='alice@example.com', age=30)

p = Post(title="Hello", body="World", user_id=1)
print(p)           # Post(id=None, title='Hello', body='World', user_id=1)

print(User._fields.keys())   # dict_keys(['id', 'username', 'email', 'age'])