Metaclasses & Descriptors

There is no TypeScript equivalent — and that is the point

Descriptors and metaclasses are two of Python’s most powerful runtime features. TypeScript has decorators (stage-3, experimental), but they are much more limited. Python’s descriptor protocol and metaclass system operate at a lower level: they control how attribute access and class creation work at runtime. Understanding them explains how @property, @dataclass, and ORMs like SQLAlchemy actually work under the hood.

Descriptors: controlled attribute access

A descriptor is any object that defines __get__, __set__, or __delete__. When a descriptor instance is assigned as a class attribute, Python calls these methods instead of doing a plain dictionary lookup every time you access the attribute on an instance.

// TypeScript — closest analogy: getter/setter
class Temperature {
  private _celsius: number;

  constructor(celsius: number) {
    this._celsius = celsius;
  }

  get fahrenheit(): number {
    return this._celsius * 9/5 + 32;
  }

  set fahrenheit(value: number) {
    this._celsius = (value - 32) * 5/9;
  }
}

const t = new Temperature(100);
console.log(t.fahrenheit);  // 212
t.fahrenheit = 32;
console.log(t.fahrenheit);  // 32

# Python — descriptor protocol (reusable across classes)
class Validated:
    """Descriptor: ensures field is numeric."""
    def __set_name__(self, owner, name):
        self._name = name  # called at class creation

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self   # class-level access
        return getattr(obj, f"_{self._name}", None)

    def __set__(self, obj, value):
        if not isinstance(value, (int, float)):
            raise TypeError(
                f"{self._name} must be numeric, "
                f"got {type(value).__name__}"
            )
        setattr(obj, f"_{self._name}", value)

class Product:
    price = Validated()      # descriptor instance as class attr
    quantity = Validated()

    def __init__(self, price: float, quantity: int) -> None:
        self.price = price
        self.quantity = quantity

    def total(self) -> float:
        return self.price * self.quantity

item = Product(9.99, 3)
print(item.total())    # 29.97
item.price = "free"    # TypeError: price must be numeric

The key insight: the Validated descriptor can be reused on any number of classes and any number of attributes. TypeScript getters/setters are per-class and per-property — you cannot share one definition.

set_name: descriptor self-registration

__set_name__ is called by Python at class creation time (when the class body is executed), giving the descriptor the name of the attribute it was assigned to. This is why you do not need to write price = Validated("price") — Python injects the name automatically.

Try it — descriptor demo

Open in an online REPL

class Validated:
    def __set_name__(self, owner, name):
        self._name = name

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return getattr(obj, f"_{self._name}", None)

    def __set__(self, obj, value):
        if not isinstance(value, (int, float)):
            raise TypeError(
                f"{self._name} must be numeric, got {type(value).__name__}"
            )
        setattr(obj, f"_{self._name}", value)

class Product:
    price = Validated()
    quantity = Validated()

    def __init__(self, price: float, quantity: int) -> None:
        self.price = price
        self.quantity = quantity

    def total(self) -> float:
        return self.price * self.quantity

item = Product(9.99, 3)
print(f"Total: {item.total()}")

item.price = 19.99
print(f"Updated total: {item.total()}")

try:
    item.price = "free"
except TypeError as e:
    print(f"Caught: {e}")

🟦 Metaclasses: classes that create classes

In Python, everything is an object — including classes. A class is an instance of its metaclass. The default metaclass is type. When Python processes a class Foo: ... statement, it calls type('Foo', bases, namespace) to construct the class object.

You can replace type with your own metaclass by passing metaclass=MyMeta. This lets you intercept and modify class creation — adding methods, enforcing conventions, or implementing patterns like singletons.

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

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

class AppConfig(metaclass=SingletonMeta):
    def __init__(self):
        self.debug = False

a = AppConfig()
b = AppConfig()
print(a is b)   # True — same object

When do metaclasses appear in the wild?

ORMs: SQLAlchemy uses a metaclass to process Column() annotations and register models.
Django: models.Model uses a metaclass to build database schemas from class bodies.
@dataclass: Not a metaclass — it is a class decorator. But it inspects __annotations__ to generate __init__, similar to what a metaclass would do.

The rule of thumb: if you find yourself needing to modify all classes in a hierarchy at creation time, that is a metaclass use case. For everything else, a class decorator or descriptor is simpler and more readable.