Descriptors: one precedence rule that property, methods and slots all grow out of

Base: why a dot is not always a field read

The usual picture of an attribute is simple: an object has a dictionary, and obj.attr takes the value out of it. As long as a class holds nothing but data, that picture holds.

Two tools people use every day do not fit into it.

The first is a property. obj.price looks like reading a field, yet it runs code: the body of a method marked @property. There may be no price stored on the instance at all.

The second is an ordinary method. The class holds one function for the whole class. But Class.method gives back that very function, while instance.method gives a bound method that will pass the instance as the first argument by itself. One object on the class, and the result of the access depends on who was asked.

Which raises the question this whole lesson answers: who turns the object lying on the class into what the dot returns, and when?

The answer is: that object itself. The language has a convention — if an object found on the class defines one of three special methods, __get__, __set__ or __delete__, then attribute access does not hand back the object but calls its method and hands back the result. Such objects are called descriptors, and the three methods are the descriptor protocol. A property and a function are built exactly that way; nothing special was added to the language for them.

The second thing to know straight away is who wins. A value under the same name may also sit on the instance, and then one access has two candidates: the entry on the instance and the descriptor on the class. The instance does not always win. A descriptor with __set__ or __delete__ (a data descriptor) outranks the instance dictionary; a descriptor with only __get__ is outranked by it.

That is already enough to answer the basic interview question. Everything below is about how a descriptor learns its own name, why that one line of precedence gives both a working cached_property cache and the @classmethod failure under someone else's decorator, and what all of it costs.

Mechanism 1: what a descriptor is

The whole definition fits into one sentence of the reference:

"Any of these" means __get__, __set__, __delete__. The smallest possible descriptor is three lines:

class Loud:
    def __get__(self, obj, owner=None):
        return "somebody asked for me"
 
class Thing:
    attr = Loud()
 
print(Thing().attr)      # somebody asked for me

This is the place to separate two things usually glued together.

Being a descriptor is a property of the object, not of where it sits. What makes an object a descriptor is its TYPE: if the type implements __get__, __set__ or __delete__, the object is a descriptor wherever it lives.

The protocol is invoked automatically under one condition only — when the object is found by looking it up on the TYPE of whatever is being asked for an attribute. That is already a rule of attribute lookup, not the definition of a descriptor, and it is what explains the next example: Loud() on an instance is still a descriptor, but nobody calls it.

t = Thing()
t.other = Loud()
print(t.other)           # <__main__.Loud object at 0x...> — just an object

Mechanism 2: one precedence rule

Everything after this rests on a distinction worth memorising verbatim:

And immediately, why the distinction is there at all:

It is checked by an experiment in which everything is identical except the presence of __set__:

class Data:
    def __get__(self, obj, owner=None): return "from the data descriptor"
    def __set__(self, obj, value): obj.__dict__["data"] = f"intercepted: {value}"
 
class NonData:
    def __get__(self, obj, owner=None): return "from the non-data descriptor"
 
class Both:
    data = Data()
    plain = NonData()
 
obj = Both()
obj.__dict__["data"] = "put straight into __dict__"
obj.__dict__["plain"] = "put straight into __dict__"
 
print(obj.data)     # from the data descriptor      <- the descriptor won
print(obj.plain)    # put straight into __dict__    <- the dictionary won

The instance dictionary holds the same thing in both cases and the result differs. The only difference between Data and NonData is three words: def __set__(self, obj, value).

The full lookup chain is written down in the descriptor guide as a single sentence too:

Below, that same chain is played out step by step. The toggle changes only what sits on the class — and you can see which step the search stops at.

Mechanism 3: how a descriptor learns its own name

A descriptor is one object for the whole class, and on two attributes it would be the same object. The only way it can tell them apart is by name, and the name is handed to it when the class is created:

class Named:
    def __set_name__(self, owner, name):
        self.name = name
        print(f"__set_name__: class {owner.__name__}, name {name!r}")
    def __get__(self, obj, owner=None):
        return f"I know I am called {self.name}"
 
class WithNames:
    first = Named()
    second = Named()

__set_name__: class WithNames, name 'first'
__set_name__: class WithNames, name 'second'

Both lines print while class executes, not on first access. The caveat from the same paragraph of the reference matters in practice: if a class attribute is assigned after the class has been created, __set_name__ will not be called automatically.

Mechanism 4: you already use them

The feeling that descriptors are rare exotica lasts exactly until one check: asking the built-ins whether they have the protocol's methods.

Identical on 3.11, 3.12, 3.13 and 3.14. About methods the reference is explicit:

This, incidentally, answers a question usually asked separately: why obj.method = something works while obj.prop = something raises. A method is a non-data descriptor and an instance entry shadows it. property is a data descriptor, and it intercepts the write itself.

Mechanism 5: why @classmethod breaks under someone else's decorator

This is the passage the lesson was written for: the decorators lesson says @staticmethod and @classmethod go outermost — and the reason was named "descriptor" without ever being explained. Here it is.

The decorator receives not a function but a staticmethod or classmethod object — the descriptor itself. The wrapper inside the decorator calls f(*args, **kwargs), and from there one check decides everything:

class Sample:
    @staticmethod
    def static(): pass
    @classmethod
    def klass(cls): pass
 
print(callable(Sample.__dict__["static"]))   # True
print(callable(Sample.__dict__["klass"]))    # False

A staticmethod object has been callable since 3.10 — the documentation records it in its own line, Changed in version 3.10: Static methods are now callable. classmethod has no such line, and the object stays non-callable. Verified on 3.11, 3.12, 3.13 and 3.14 — identical in all four.

The practical consequence is nastier than the asymmetry itself: the class is defined silently. functools.wraps copies attributes through try/except and does not trip over the descriptor, so the error appears not while the class is being built but on the first call — TypeError: 'classmethod' object is not callable.

Mechanism 6: cached_property — the cache rests on precedence

functools.cached_property is the clearest demonstration that the precedence rule is not an abstraction. Look at __get__:

# Lib/functools.py:1110–1134, tag v3.14.5, abridged
def __get__(self, instance, owner=None):
    ...
    cache = instance.__dict__
    val = cache.get(self.attrname, _NOT_FOUND)
    if val is _NOT_FOUND:
        val = self.func(instance)
        cache[self.attrname] = val
    return val

The descriptor puts the result into the instance dictionary under its own name. And because it is a NON-data descriptor, from the next access on the dictionary outranks it — and __get__ is never called again. The cache here is not a trick but a direct consequence of precedence:

class Lazy:
    @functools.cached_property
    def heavy(self):
        print("body ran")
        return "computed"
 
lazy = Lazy()
print(lazy.__dict__)   # {}
lazy.heavy             # body ran
print(lazy.__dict__)   # {'heavy': 'computed'}
lazy.heavy             # silence: the descriptor was never asked

The same fact explains two limitations usually learned the hard way. cached_property does not work with __slots__: there is nowhere to put the value, there is no __dict__. And the only way to clear the cache is del obj.attr — that is, by removing the dictionary entry, not by talking to the descriptor.

Deeper: the whole rule — the four branches of object.__getattribute__

The precedence rule above is an abbreviation. The full logic of the dot is written down in object.__getattribute__, and the documentation gives its equivalent in Python itself:

def object_getattribute(obj, name):
    "Emulate PyObject_GenericGetAttr() in Objects/object.c"
    null = object()
    objtype = type(obj)
    cls_var = find_name_in_mro(objtype, name, null)
    descr_get = getattr(type(cls_var), '__get__', null)
    if descr_get is not null:
        if (hasattr(type(cls_var), '__set__')
            or hasattr(type(cls_var), '__delete__')):
            return descr_get(cls_var, obj, objtype)     # data descriptor
    if hasattr(obj, '__dict__') and name in vars(obj):
        return vars(obj)[name]                          # instance variable
    if descr_get is not null:
        return descr_get(cls_var, obj, objtype)         # non-data descriptor
    if cls_var is not null:
        return cls_var                                  # class variable
    raise AttributeError(name)

Read it as a list of four branches in order: data descriptor, instance dictionary, non-data descriptor, class variable. The precedence rule from the section above is two pairs of neighbouring branches: branch 1 beats branch 2, and branch 2 beats branch 3.

That the pseudocode really is equivalent to the dot can be checked by running it: one class, five names, each fetched both ways (bench/attr-lookup/getattribute_equivalent.py, identical output on 3.11–3.14; here and below it is abridged to the relevant lines and its labels translated):

3) which branch of the pseudocode fired:
   data    -> branch 1 (data descriptor): the instance __dict__ was IGNORED
   nondata -> branch 2 (instance variable): the instance __dict__ WON
   plain   -> branch 2 (instance variable)
   own     -> branch 2 (instance variable)
   method  -> branch 3 (non-data descriptor), the function is itself a descriptor: True | __set__: False

(Labels translated from the script's output.) That method line answers why an ordinary method works at all: a function is a non-data descriptor, and the bound method comes out of branch 3.

What is not in this code is __getattr__. The hook for a miss is nowhere in the pseudocode, and that is not an omission:

Checked on a class with a __getattr__: the dot calls the fallback, a direct object.__getattribute__ does not — it raises AttributeError. That is exactly the difference that makes a proxy written "through super().__getattribute__" lose its own __getattr__.

And one more line of the pseudocode worth memorising on its own: objtype = type(obj). The whole of the next section follows from it.

Deeper: the same lookup one floor up — a descriptor on the metaclass

C.x and c.x are two different lookups, and they differ by exactly one line of pseudocode. For an instance, objtype = type(obj) gives the class; for a class, the metaclass. The documentation states it as a separate but identical algorithm:

And in the same place, on the difference between the calls:

The practical consequence is stronger than it sounds (bench/attr-lookup/metaclass_descriptor.py, identical output on 3.11–3.14):

2) C.on_meta -> <on-the-metaclass>
   on-the-metaclass.__get__(obj=class C, objtype=Meta)

3) C().on_meta -> AttributeError: 'C' object has no attribute 'on_meta'
   calls to __get__: none
   C.__mro__      : ['C', 'object']
   type(C).__mro__: ['Meta', 'type', 'object']

(Labels translated from the script's output.) A descriptor on the metaclass does not "fail to fire" for an instance — for the instance it does not exist. Zero calls to __get__ and an ordinary AttributeError, because the metaclass is not in type(c).__mro__. This is the only way to make an attribute visible on the class and invisible on the instance — and, at the same time, the commonest cause of bafflement when someone tries to read it off an instance.

The precedence rule, meanwhile, is one rule for both floors:

6) a non-data descriptor on the metaclass:
   after E.nd = 'overridden' -> overridden | in E.__dict__: True
   the CLASS __dict__ overrides the metaclass's non-data descriptor,
   exactly as the instance __dict__ overrides the class's non-data descriptor

7) the name `both` is declared on the metaclass and on the class:
   F.both   -> <metaclass>
   F().both -> <class>
   F.both BEAT F.__dict__['both']: a DATA descriptor on type(F)
   overrides F's own dictionary — by the same rule

So learning the four branches once buys you the behaviour of metaclasses as well: the same branches, with vars(instance) replaced by the class's MRO.

There is one small thing people trip over when moving a descriptor between floors: __set_name__ is called only for descriptors sitting in the body of their own class. For a descriptor on the metaclass, owner is the metaclass, not the class that uses it.

Deeper: what it costs

Six ways to fetch the same value, measured back to back in one process, Python 3.13.7, best of nine runs of 200,000 accesses:

The first thing this shows: "being a descriptor" costs nothing by itself. A __slots__ slot is a full data descriptor and it is ×1.00. What is expensive is a getter written in Python: property ×2.06, a hand-written descriptor ×6.31.

The second is more interesting, because it refutes an expectation. A warmed cached_property should have matched a plain attribute: the value is already in __dict__, a non-data descriptor is outranked by the dictionary, there is nothing to ask it about. Measured — a steady ×1.84.

The reason is visible in the specialised bytecode:

def read(o):
    return o.value
 
# after two hundred calls, dis.get_instructions(read, adaptive=True)
# an ordinary attribute -> LOAD_ATTR_INSTANCE_VALUE
# cached_property       -> LOAD_ATTR

For an ordinary attribute the interpreter substitutes a specialised instruction that reads the value straight out of the instance. For an attribute with a descriptor still sitting on the type it cannot: the type has to be checked on every access, because that descriptor might have turned out to be a data one.

The practical conclusion is narrow and honest: cached_property saves you the recomputation but does not turn the attribute into an ordinary one. If there is nothing to compute and there are millions of accesses, a plain field set in __init__ is almost twice as cheap.

Deeper: version history

How to answer in an interview

The short answer: a descriptor is an object that lives on the class and intervenes in attribute access on an instance; the single criterion is that its type has __get__, __set__ or __delete__. All the behaviour follows from one line of precedence: a data descriptor (one with __set__ or __delete__) outranks the instance dictionary, a non-data descriptor (only __get__) is outranked by it. property, an ordinary method, staticmethod, classmethod, a slot and cached_property already are descriptors.

That is enough to answer correctly. Beyond it is what you add if the interviewer digs.

If the interviewer digs deeper

If asked why this is worth knowing, the best answer derives two consequences from that same line: cached_property caches because it is a non-data descriptor and stops being consulted once the value is in __dict__; and a descriptor placed on the instance does not work at all, because the lookup goes to the class.

Next they ask

Common misconceptions

Practice

Two exercises. Answer first, then check against the real output: in both, the right answer comes from a recorded run rather than from an editor.

class Data:
  def __get__(self, obj, cls):
      return "descriptor"

  def __set__(self, obj, value):
      pass


class NonData:
  def __get__(self, obj, cls):
      return "descriptor"


class C:
  data = Data()
  nondata = NonData()


c = C()
c.__dict__["data"] = "instance dict"
c.__dict__["nondata"] = "instance dict"

print(c.data)
print(c.nondata)

descriptor
instance dict

instance dict
instance dict

descriptor
descriptor

instance dict
descriptor

Check yourself

What measured this

The numbers in this article come from these scripts. Each one opens from here, together with the record of the run: what it was measured on, what came out, and with what spread.

• bench/descriptors/cost.py
• bench/descriptors/protocol.py
• bench/attr-lookup/getattribute_equivalent.py
• bench/attr-lookup/metaclass_descriptor.py