Descriptors

An object that defines __get__, __set__ or __delete__ and is assigned as a class attribute. Python then routes attribute access on instances through it. This is the mechanism behind property, classmethod, staticmethod, bound methods and every ORM field you have used.

class Descriptor:
    def __get__(self, obj, objtype=None): ...
    def __set__(self, obj, value): ...
    def __delete__(self, obj): ...
    def __set_name__(self, owner, name): ...

obj is the instance (or None when accessed on the class), objtype the class. __set_name__ runs once at class creation and tells the descriptor which attribute name it was bound to.

Data vs non-data, and why it matters

The single distinction everything else follows from:

c.__dict__["d"] = "from instance dict"
c.d        # "from descriptor"      — data wins
c.n        # "from instance dict"   — non-data loses

That is precisely why you cannot shadow a @property by assigning to the instance — property defines __set__, so it is a data descriptor — while functools.cached_property can cache into the instance __dict__, because it deliberately defines only __get__.

The full lookup order

For obj.x, Python walks:

1. Data descriptor on type(obj) (or its MRO)
2. obj.__dict__["x"]
3. Non-data descriptor, or plain class attribute
4. __getattr__, if defined

Most surprising attribute behaviour in Python is explained by this list.

The bug everyone writes first

State belongs on the instance, not on the descriptor. A descriptor is one object shared by every instance of the class:

class Broken:
    def __get__(self, obj, objtype=None):
        return self.value
    def __set__(self, obj, value):
        self.value = value      # on the descriptor!

a1, a2 = A(), A()
a1.x = 1
a2.x = 2
a1.x        # 2 — a2 overwrote it

The fix is to key storage off the instance, using the name __set_name__ handed you:

class Field:
    def __set_name__(self, owner, name):
        self.attr = "_" + name

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self          # accessed on the class
        return getattr(obj, self.attr)

    def __set__(self, obj, value):
        setattr(obj, self.attr, value)

Gotcha: the if obj is None: return self guard is not optional. Without it, A.x raises instead of returning the descriptor, which breaks help(), inspect, and anything introspecting the class.

A worked example: validation

The case that justifies a descriptor over @property — the behaviour is reused across several fields:

class Positive:
    def __set_name__(self, owner, name):
        self.attr = "_" + name

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

    def __set__(self, obj, value):
        if value <= 0:
            raise ValueError(f"{self.attr} must be > 0")
        setattr(obj, self.attr, value)


class Product:
    price = Positive()
    stock = Positive()

Two fields, one validation rule, no repetition. With @property this is the same nine lines written twice.

What is already a descriptor

class C:
    def method(self): ...

C.__dict__["method"].__get__       # functions have it

Functions are non-data descriptors — that is how obj.method produces a bound method: __get__ returns a partial with self applied. classmethod, staticmethod and property are the same machinery, and __slots__ creates one data descriptor per slot.

Knowing this reframes the question “how does self get passed?” from magic to a protocol you could implement yourself.

cached_property and the precedence trick

from functools import cached_property

class Report:
    @cached_property
    def rows(self):
        return expensive_query()

First access computes and writes rows into the instance __dict__. Every later access finds it at step 2 of the lookup and never reaches the descriptor. It works only because cached_property is non-data — which is also why you cannot use it on a class with __slots__.

When to reach for one

For a single attribute a descriptor is over-engineering. The moment you are writing the third near-identical @property, it stops being.

Related

• dataclasses vs Pydantic v2 vs attrs — the declarative alternative
• Magic Methods and Attributes in Python — __getattr__ vs __getattribute__
• Encapsulation in Python — where @property fits