What makes a Python class a descriptor, and what do __get__, __set__ and __delete__ do?

### The definition A **descriptor** is not a special kind of syntax; it is a *protocol*, exactly like iteration. Any class that defines one or more of these three methods on **its own type** is a descriptor: ```python def __get__(self, obj, objtype=None): ... # reading obj.attr def __set__(self, obj, value): ... # writing obj.attr = value def __delete__(self, obj): ... # removing del obj.attr ``` Two conditions must both hold for the protocol to fire. First, the methods live on the **type** of the attribute value, not on the value's instance dictionary — Python looks up dunders on the type, so setting `d.__get__ = f` on an object `d` does nothing. Second, the descriptor object must be reachable as a **class attribute** of the class whose instances you are touching (its own class body or somewhere in its MRO). A descriptor stored in an *instance's* `__dict__` is inert: `obj.attr` finds it and hands it back unchanged. ### What the arguments mean `__get__` receives `(self, obj, objtype=None)` where `self` is the descriptor object, `obj` is the instance the attribute was reached through, and `objtype` is the owning class. When the attribute is reached through the **class** rather than an instance — `Collector.label` — `obj` is `None`. The near-universal convention is to return `self` in that case so that `Collector.label` yields the descriptor for introspection, and only instance access computes a value. `__set__` and `__delete__` always get a real instance, because assigning to a class attribute goes through the metaclass, not through this descriptor. ### Where the call actually happens Attribute access on an ordinary object is implemented by `object.__getattribute__`. It searches `type(obj).__mro__` for the name, checks whether what it found is a descriptor, and if so calls `__get__`; assignment is implemented by `object.__setattr__`, which calls `__set__` when the class attribute defines it and otherwise writes into `obj.__dict__`. So descriptors are not a bolt-on: they are a documented step inside the ordinary attribute machinery, which is why you can bypass them for debugging with `inspect.getattr_static`, which returns the descriptor object itself rather than invoking it. ### Why the protocol exists Descriptors let you attach *behaviour* to what looks to callers like a plain attribute, and to do it **once, per class**, rather than writing the same accessor code in every method that touches the value. Validation, type coercion, unit conversion, lazy computation, logging and read-only enforcement all become a small reusable class you declare in the class body. Crucially, they are also how the language implements itself: plain functions define `__get__`, which is what turns `Collector.sample` into a bound method when you fetch it through an instance; `property`, `classmethod` and `staticmethod` are descriptor types written in C; and `__slots__` generates one descriptor per slot. ### A worked shape ```python class Utf8Text: def __get__(self, obj, objtype=None): if obj is None: return self return obj.__dict__["_label"] def __set__(self, obj, value): if isinstance(value, bytes): value = value.decode("utf-8") obj.__dict__["_label"] = value ``` A sensor-telemetry collector whose device link sometimes yields `bytes` and sometimes `str` normalises the encoding mismatch at exactly one place — the assignment — rather than at every read site. Callers write `collector.label = raw` and never learn that anything happened. ### The edges worth knowing `__delete__` is spelled that way and is *not* `__del__`: `__del__` is the finalizer that runs when an object is about to be destroyed, while `__delete__` runs on `del obj.attr`. Confusing the two is a classic slip. Raising `AttributeError` from `__get__` is meaningful rather than merely fatal: it is the signal that makes `hasattr` return `False` and triggers the class's `__getattr__` fallback. A descriptor that defines only `__get__` behaves very differently from one that also defines `__set__` when the instance dictionary holds the same name — that precedence rule is the other half of the protocol. And because the descriptor object itself is created once, at class-definition time, any state you store on `self` is shared by every instance of the owner class, which is a bug source rather than a feature. ### One more thing the definition implies Because the protocol is checked on the *type*, descriptors compose with inheritance the way any class attribute does: a subclass inherits the same descriptor object, and rebinding the name in the subclass body replaces it for that branch of the MRO only. And because `__get__` runs arbitrary code, an attribute that looks free can do real work — a network call, a lock acquisition, a lazy import. That is the standing cost of the protocol: it buys clean call sites by making the cost of an attribute invisible, so a descriptor that does anything expensive or blocking deserves a name and a docstring that say so.