Дескрипторы: одно правило приоритета, из которого растут property, методы и слоты

База: почему точка — не всегда чтение поля

Привычное представление об атрибуте простое: у объекта есть словарь, и obj.attr достаёт оттуда значение. Пока в классе лежат только данные, так оно и есть.

Но два инструмента, которыми пользуются каждый день, в эту картину не укладываются.

Первый — свойство. Обращение obj.price выглядит как чтение поля, а на самом деле выполняет код: тело метода, помеченного @property. Никакого значения price в экземпляре может не быть вовсе.

Второй — обычный метод. В классе лежит одна функция на весь класс. Но Класс.метод даёт саму эту функцию, а экземпляр.метод — уже связанный метод, который сам подставит экземпляр первым аргументом. Объект в классе один, а результат обращения зависит от того, у кого спросили.

Отсюда и вопрос, на который отвечает весь урок: кто и в какой момент превращает объект, лежащий в классе, в то, что возвращает точка?

Ответ: сам этот объект. В языке есть договорённость: если у объекта, найденного в классе, определён один из трёх специальных методов — __get__, __set__, __delete__, — то обращение к атрибуту не отдаёт его самого, а зовёт его метод и отдаёт результат. Такие объекты называются дескрипторами, а три метода — протоколом дескрипторов. Свойство и функция устроены именно так; ничего специального под них в языке не заводили.

Второе, что нужно знать сразу, — кто сильнее. Значение под тем же именем может лежать и в самом экземпляре, и тогда на одно обращение два претендента: запись в экземпляре и дескриптор в классе. Побеждает не всегда экземпляр. Дескриптор, у которого есть __set__ или __delete__ (такой называют дескриптором данных), сильнее словаря экземпляра; дескриптор, у которого есть только __get__, — слабее.

Этого уже достаточно, чтобы ответить на базовый вопрос собеседования. Дальше — про то, откуда дескриптор узнаёт своё имя, почему из одной строчки приоритета следуют и работающий кеш cached_property, и падение @classmethod под чужим декоратором, и сколько всё это стоит.

Механизм 1: что такое дескриптор

Определение целиком укладывается в одно предложение справочника:

«Любой из этих» — это __get__, __set__, __delete__. Минимальный дескриптор занимает три строки:

class Loud:
    def __get__(self, obj, owner=None):
        return "меня спросили"
 
class Thing:
    attr = Loud()
 
print(Thing().attr)      # меня спросили

Здесь стоит развести две вещи, которые обычно склеивают в одну.

Дескриптор — это свойство объекта, а не его места. Дескриптором объект делает его ТИП: если тип реализует __get__, __set__ или __delete__, объект — дескриптор, где бы он ни лежал.

Автоматически вызывается протокол только при одном условии — когда объект найден поиском в ТИПЕ того, у кого спрашивают атрибут. Это уже правило поиска атрибута, а не определение дескриптора, и именно оно объясняет следующий пример: Loud() в экземпляре остаётся дескриптором, но никто его не зовёт.

t = Thing()
t.other = Loud()
print(t.other)           # <__main__.Loud object at 0x...> — просто объект

Механизм 2: одно правило приоритета

Дальше всё держится на различении, которое стоит выучить дословно:

И сразу же — зачем это различение нужно:

Проверяется это опытом, в котором всё одинаково, кроме наличия __set__:

class Data:
    def __get__(self, obj, owner=None): return "из дескриптора данных"
    def __set__(self, obj, value): obj.__dict__["data"] = f"перехвачено: {value}"
 
class NonData:
    def __get__(self, obj, owner=None): return "из дескриптора не-данных"
 
class Both:
    data = Data()
    plain = NonData()
 
obj = Both()
obj.__dict__["data"] = "положено прямо в __dict__"
obj.__dict__["plain"] = "положено прямо в __dict__"
 
print(obj.data)     # из дескриптора данных        <- дескриптор победил
print(obj.plain)    # положено прямо в __dict__    <- словарь победил

В словаре экземпляра лежит одно и то же, а результат разный. Единственное различие между Data и NonData — три слова def __set__(self, obj, value).

Полная цепочка поиска записана в руководстве по дескрипторам тоже одним предложением:

Ниже та же цепочка проиграна по шагам. Переключатель меняет только то, что лежит в классе, — и видно, на каком шаге поиск останавливается.

Механизм 3: откуда дескриптор знает своё имя

Дескриптор — один объект на весь класс, и на двух атрибутах это был бы один и тот же объект. Различить их он может только по имени, а имя ему выдают в момент создания класса:

class Named:
    def __set_name__(self, owner, name):
        self.name = name
        print(f"__set_name__: класс {owner.__name__}, имя {name!r}")
    def __get__(self, obj, owner=None):
        return f"я знаю, что меня зовут {self.name}"
 
class WithNames:
    first = Named()
    second = Named()

__set_name__: класс WithNames, имя 'first'
__set_name__: класс WithNames, имя 'second'

Обе строки печатаются при выполнении class, а не при первом обращении. Оговорка из того же абзаца справочника важна на практике: если атрибут класса присвоен уже после создания класса, __set_name__ автоматически не вызовется.

Механизм 4: вы уже ими пользуетесь

Ощущение «дескрипторы — редкая экзотика» держится ровно до одной проверки: спросить у встроенных объектов, есть ли у них методы протокола.

Одинаково на 3.11, 3.12, 3.13 и 3.14. Справочник говорит про методы прямо:

Отсюда, кстати, ответ на вопрос, который обычно задают отдельно: почему obj.method = something работает, а obj.prop = something падает. Метод — дескриптор не-данных, его можно перекрыть записью в экземпляр. property — дескриптор данных, и он перехватывает саму запись.

Механизм 5: почему @classmethod под чужим декоратором ломается

Это то место, ради которого урок и написан: в уроке про декораторы сказано, что @staticmethod и @classmethod ставятся самыми верхними, — а причина называлась словом «дескриптор» без объяснения. Вот она.

Декоратор получает не функцию, а объект staticmethod или classmethod — тот самый дескриптор. Обёртка внутри декоратора делает f(*args, **kwargs), и дальше всё решает одна проверка:

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

Объект staticmethod вызываем начиная с 3.10 — документация фиксирует это отдельной строкой Changed in version 3.10: Static methods are now callable (Изменено в версии 3.10: статические методы теперь вызываемы). У classmethod такой строки нет, и объект остаётся невызываемым. Проверено на 3.11, 3.12, 3.13 и 3.14 — во всех четырёх одинаково.

Практическое следствие неприятнее самой асимметрии: класс определяется молча. functools.wraps копирует атрибуты через try/except и о дескриптор не спотыкается, так что ошибка возникает не при построении класса, а при первом вызове — TypeError: 'classmethod' object is not callable.

Механизм 6: cached_property — кеш держится на приоритете

functools.cached_property — самый наглядный пример того, что правило приоритета не абстракция. Смотреть надо на __get__:

# Lib/functools.py:1110–1134, тег v3.14.5, сокращено
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

Дескриптор кладёт результат в словарь экземпляра под своим же именем. И поскольку он дескриптор НЕ данных, со следующего обращения словарь оказывается сильнее — и __get__ больше не вызывают вовсе. Кеш здесь не хитрость, а прямое следствие приоритета:

class Lazy:
    @functools.cached_property
    def heavy(self):
        print("тело выполнено")
        return "посчитано"
 
lazy = Lazy()
print(lazy.__dict__)   # {}
lazy.heavy             # тело выполнено
print(lazy.__dict__)   # {'heavy': 'посчитано'}
lazy.heavy             # тишина: дескриптора не спрашивали

Отсюда же и два ограничения, которые обычно узнают на своей шкуре. С __slots__ cached_property не работает: складывать некуда, __dict__ нет. И сбросить кеш можно только del obj.attr — то есть удалением записи из словаря, а не обращением к дескриптору.

Глубже: правило целиком — четыре ветки object.__getattribute__

Правило приоритета выше — это сокращение. Полностью логика точки записана в object.__getattribute__, и документация приводит её эквивалент на самом Python:

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)

Читать его стоит как список из четырёх веток по порядку: дескриптор данных, словарь экземпляра, дескриптор не-данных, переменная класса. Правило приоритета, названное выше, — это две пары соседних веток: ветка 1 сильнее ветки 2, а ветка 2 сильнее ветки 3.

Что этот псевдокод действительно эквивалентен точке, проверяется запуском: один класс, пять имён, каждое достаётся и точкой, и псевдокодом (bench/attr-lookup/getattribute_equivalent.py, вывод одинаков на 3.11–3.14; здесь и ниже он сокращён до относящихся к делу строк):

3) какая ветка псевдокода сработала:
   data    -> ветка 1 (data descriptor): __dict__ экземпляра ПРОИГНОРИРОВАН
   nondata -> ветка 2 (instance variable): __dict__ экземпляра ПОБЕДИЛ
   plain   -> ветка 2 (instance variable)
   own     -> ветка 2 (instance variable)
   method  -> ветка 3 (non-data descriptor), функция сама дескриптор: True | __set__: False

Строка method — ответ на вопрос, почему обычный метод вообще работает: функция и есть дескриптор не-данных, и связанный метод получается на ветке 3.

Чего в этом коде нет — это __getattr__. Крючка на промах в псевдокоде не видно, и это не упущение:

Проверено на классе с __getattr__: точка зовёт запасной путь, прямой вызов object.__getattribute__ — нет, он падает AttributeError. Это ровно та разница, из-за которой прокси, написанный «через super().__getattribute__», теряет свой же __getattr__.

И ещё одна строка псевдокода, которую стоит запомнить отдельно: objtype = type(obj). Из неё следует весь раздел ниже.

Глубже: тот же поиск на этаж выше — дескриптор на метаклассе

C.x и c.x — это два разных поиска, и разные они ровно на одну строку псевдокода. У экземпляра objtype = type(obj) даёт класс, у класса — метакласс. Документация формулирует это как отдельный, но такой же алгоритм:

И там же — про разницу вызовов:

Практическое следствие сильнее, чем звучит (bench/attr-lookup/metaclass_descriptor.py, вывод одинаков на 3.11–3.14):

2) C.on_meta -> <на-метаклассе>
   на-метаклассе.__get__(obj=класс C, objtype=Meta)

3) C().on_meta -> AttributeError: 'C' object has no attribute 'on_meta'
   вызовов __get__: нет
   C.__mro__      : ['C', 'object']
   type(C).__mro__: ['Meta', 'type', 'object']

Дескриптор на метаклассе у экземпляра не «не срабатывает» — его там нет. Ноль вызовов __get__ и обычный AttributeError, потому что метакласса нет в type(c).__mro__. Это единственный способ сделать атрибут, который виден у класса и невидим у экземпляра, — и одновременно самая частая причина недоумения, когда его пытаются прочитать у экземпляра.

Правило приоритета при этом одно на оба этажа:

6) дескриптор не-данных на метаклассе:
   после E.nd = 'перекрыто' -> перекрыто | в E.__dict__: True
   __dict__ КЛАССА перекрывает дескриптор не-данных метакласса,
   ровно как __dict__ экземпляра перекрывает дескриптор не-данных класса

7) имя `both` объявлено и на метаклассе, и на классе:
   F.both   -> <метакласс>
   F().both -> <класс>
   F.both ВЫИГРАЛ у F.__dict__['both']: дескриптор ДАННЫХ на type(F)
   перекрывает словарь самого F — тем же правилом

То есть выучив четыре ветки один раз, вы получаете и поведение метаклассов: там те же ветки, только vars(экземпляра) заменён на MRO класса.

Есть и мелочь, о которую спотыкаются при переносе дескриптора между этажами: __set_name__ зовётся только у дескрипторов, лежащих в теле своего класса. У дескриптора на метаклассе owner — это метакласс, а не класс, который им пользуется.

Глубже: что это стоит

Шесть способов добыть одно и то же значение, замерено подряд в одном процессе, Python 3.13.7, лучшее из девяти прогонов по 200 000 обращений:

Первое, что видно: «дескриптор» сам по себе не стоит ничего. Слот __slots__ — полноценный дескриптор данных, и он ×1,00. Дорог не протокол, а геттер, написанный на Python: property ×2,06, свой дескриптор ×6,31.

Второе интереснее, потому что опровергает ожидание. Прогретый cached_property должен был сравняться с обычным атрибутом: значение уже в __dict__, дескриптор не-данных слабее словаря, спрашивать его незачем. Измерено — устойчивые ×1,84.

Причина видна в специализированном байткоде:

def read(o):
    return o.value
 
# после двухсот вызовов, dis.get_instructions(read, adaptive=True)
# обычный атрибут  -> LOAD_ATTR_INSTANCE_VALUE
# cached_property  -> LOAD_ATTR

Обычному атрибуту интерпретатор подставляет специализированную инструкцию, которая читает значение из экземпляра напрямую. Атрибуту, за которым в типе всё-таки лежит дескриптор, — не подставляет: проверить тип придётся на каждом обращении, потому что дескриптор мог бы оказаться дескриптором данных.

Практический вывод узкий и честный: cached_property избавляет от повторного вычисления, но не превращает атрибут в обычный. Если считать нечего, а обращений миллионы, обычное поле в __init__ дешевле почти вдвое.

Глубже: история версий

Как отвечать на собеседовании

Короткий ответ: дескриптор — это объект, который лежит в классе и вмешивается в обращение к атрибуту экземпляра; признак один — у его типа есть __get__, __set__ или __delete__. Всё поведение выводится из одной строки приоритета: дескриптор данных (есть __set__ или __delete__) сильнее словаря экземпляра, дескриптор не-данных (только __get__) — слабее. property, обычный метод, staticmethod, classmethod, слот и cached_property уже дескрипторы.

Этого достаточно, чтобы ответить верно. Дальше — то, что добавляют, если собеседник копает.

Если интервьюер копает глубже

Если спросят, зачем это знать, лучший ответ — вывести из той же строки два следствия: cached_property кеширует потому, что он дескриптор не-данных и после записи в __dict__ его больше не спрашивают; а дескриптор, положенный в экземпляр, не работает вовсе, потому что искать его будут в классе.

Дальше спросят

Частые заблуждения

Практика

Две задачи. Сначала ответьте, потом сверьтесь с настоящим выводом: в обеих правильный ответ взят из прогона скрипта, а не назначен.

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

Проверьте себя

Чем измерено

Числа этой статьи получены этими скриптами. Каждый открывается прямо отсюда — вместе с записью прогона: на чём считали, что получилось и с каким разбросом.

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