obj.x насквозь

Начать надо не с определения, а с задачи, которую дескриптор решает.

Атрибут на классе — один на всех. C.x = 1 означает, что у каждого инстанса x равен единице, и это одно и то же значение. Вопрос: как сделать так, чтобы атрибут лежал на классе — то есть был общим объявлением, — но отвечал по-разному для каждого инстанса, а то и вычислялся в момент обращения?

Ответ Python: пусть объект, лежащий на классе, сам решает, что вернуть. Для этого он должен уметь принять вопрос — то есть иметь метод __get__.

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

class Probe:
    def __get__(self, obj, objtype=None):
        print(f"__get__ вызван: obj={obj!r}, objtype={objtype.__name__}")
        return 42

class C:
    x = Probe()

c = C()
print(c.x)
# → __get__ вызван: obj=<__main__.C object at 0x...>, objtype=C
# → 42

print(C.x)
# → __get__ вызван: obj=None, objtype=C
# → 42

Обрати внимание на главное: c.x вернуло 42, а не объект Probe. Хотя на классе лежит именно Probe. Это и есть перехват — обычный поиск атрибута нашёл бы объект и вернул его как есть, а здесь вместо возврата произошёл вызов.

Три аргумента __get__. self — сам дескриптор, он один на класс. obj — инстанс, через который читают; именно он позволяет отвечать по-разному для разных объектов. objtype — класс.

Когда читают через класс, а не через инстанс, obj равен None. Отсюда идиома, которую видно в любом дескрипторе: if obj is None: return self — «меня спрашивают у класса, инстанса нет, верну себя». Именно поэтому SomeClass.some_property печатает <property object>, а не значение.

Написать property самому

Проверка понимания: property — не синтаксис языка и не встроенная магия, а обычный класс с __get__ и __set__. Вот рабочая версия, укладывающаяся в двенадцать строк:

class MyProperty:
    def __init__(self, fget=None, fset=None):
        self.fget, self.fset = fget, fset

    def __get__(self, obj, objtype=None):
        if obj is None: return self            # спросили у класса
        if self.fget is None: raise AttributeError("нет геттера")
        return self.fget(obj)                  # зовём функцию, подставив инстанс

    def __set__(self, obj, value):
        if self.fset is None: raise AttributeError("только для чтения")
        self.fset(obj, value)

    def setter(self, fset):                    # чтобы работал @celsius.setter
        return MyProperty(self.fget, fset)


class Temp:
    def __init__(self, c): self._c = c

    @MyProperty
    def celsius(self): return self._c

    @celsius.setter
    def celsius(self, v):
        if v < -273.15: raise ValueError("ниже абсолютного нуля")
        self._c = v


t = Temp(20)
print(t.celsius)          # → 20
t.celsius = 25
print(t.celsius)          # → 25
t.celsius = -300          # → ValueError: ниже абсолютного нуля

Ни одной специальной конструкции здесь нет. @MyProperty — обычный декоратор: он получает функцию celsius и кладёт на класс вместо неё объект MyProperty. Дальше при t.celsius срабатывает __get__, при t.celsius = 25 — __set__. Настоящий property устроен ровно так же, только написан на C и умеет ещё deleter и докстроку.

Как дескриптор узнаёт своё имя

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

Для этого есть __set_name__ (с версии 3.6): интерпретатор вызывает его при создании класса и сообщает дескриптору владельца и имя.

class Field:
    def __set_name__(self, owner, name):
        print(f"__set_name__: {owner.__name__}.{name}")
        self.name = "_" + name

    def __get__(self, obj, objtype=None):
        if obj is None: return self
        return obj.__dict__.get(self.name)

    def __set__(self, obj, value):
        obj.__dict__[self.name] = value


class Point:
    x = Field()
    y = Field()
# → __set_name__: Point.x
# → __set_name__: Point.y

p = Point()
p.x, p.y = 1, 2
print(p.x, p.y)        # → 1 2
print(p.__dict__)      # → {'_x': 1, '_y': 2}

До 3.6 имя приходилось передавать руками — x = Field("x"), — и это была классическая причина заводить метакласс. __set_name__ убрал такую необходимость и вместе с __init_subclass__ закрыл большинство сценариев, ради которых метаклассы писали (урок 07).

Дескриптор данных против не-данных: зачем вообще делить

Теперь ключевой вопрос, ответ на который обычно просто запоминают. Почему одни дескрипторы имеют приоритет над словарём инстанса, а другие нет?

Потому что это две разные задачи, и им нужно противоположное поведение.

Метод должен быть затеняем. Функция — дескриптор не-данных, и поэтому значение в словаре инстанса перебивает её. Это не недосмотр, а необходимая возможность: подмена метода на одном объекте.

class Service:
    def send(self): return "настоящая отправка"

s = Service()
s.send = lambda: "заглушка"        # только на этом объекте

print(s.send())              # → заглушка
print(Service().send())      # → настоящая отправка

На этом стоят моки в тестах, обёртки вокруг конкретного объекта, отладочные подмены. Будь функция дескриптором данных, ничего этого не работало бы.

Валидация затеняема быть не должна. Если бы property можно было перебить записью в словарь инстанса, любую проверку можно было бы обойти — случайно или намеренно:

class Account:
    @property
    def balance(self): return self._b

    @balance.setter
    def balance(self, v):
        if v < 0: raise ValueError("отрицательный баланс")
        self._b = v

a = Account()
a.balance = 100
a.__dict__["balance"] = -999       # положили в обход сеттера

print(a.__dict__)      # → {'_b': 100, 'balance': -999}
print(a.balance)       # → 100   дескриптор данных отвечает первым

Значение в словаре есть, оно просто недостижимо: шаг 1 срабатывает раньше шага 2. Инвариант класса удержан, несмотря на прямую запись в его словарь.

Отсюда правило, которое теперь не надо запоминать — оно выводится: дескриптор данных имеет приоритет над инстансом, потому что он про контроль; дескриптор не-данных уступает инстансу, потому что он про поведение по умолчанию.

Что в Python на самом деле является дескриптором

Почти всё, что выглядит как отдельная возможность языка:

import functools

class Q:
    __slots__ = ("s",)
    def m(self): pass
    @property
    def p(self): return 1
    @classmethod
    def cm(cls): pass
    @staticmethod
    def sm(): pass

for n in ("m", "p", "cm", "sm", "s"):
    o = Q.__dict__[n]
    t = type(o)
    kind = ("данных" if hasattr(t, "__set__") or hasattr(t, "__delete__")
            else "не-данных" if hasattr(t, "__get__") else "не дескриптор")
    print(f"{n:4} {t.__name__:18} {kind}")
# → m    function           не-данных
# → p    property           данных
# → cm   classmethod        не-данных
# → sm   staticmethod       не-данных
# → s    member_descriptor  данных

Строка про cached_property — лучшая иллюстрация всей механики. Он сделан дескриптором не-данных намеренно: посчитав значение один раз, он записывает его в obj.__dict__ — и со второго обращения срабатывает шаг 2, а сам дескриптор больше никогда не вызывается.

import functools

class D:
    def __init__(self): self.calls = 0
    @functools.cached_property
    def value(self):
        self.calls += 1
        return "посчитано"

d = D()
print(d.__dict__)                    # → {'calls': 0}    значения ещё нет
print(d.value, d.calls)              # → посчитано 1
print(d.__dict__)                    # → {'calls': 1, 'value': 'посчитано'}
print(d.value, d.calls)              # → посчитано 1     функция не звалась

Кеширование здесь не отдельный механизм, а прямое следствие приоритетов: не-данных уступает инстансу, значит достаточно один раз записать в инстанс — и дескриптор самоустранится. Замер: чтение property — 0.041 с на миллион, прогретого cached_property — 0.029 с, то есть обычное чтение атрибута.

А заодно отсюда видно ограничение: cached_property не работает с __slots__ — писать некуда, словаря инстанса нет.

Сравнение с C++ и C#

В C++ обращение к полю — смещение, вычисленное компилятором; перехватить его нельзя, можно только заранее написать геттер и вызывать его явно. В C# есть свойства с синтаксисом get/set, но это синтаксис компилятора: каждое свойство описывается по месту и не является объектом.

Разница принципиальная: дескриптор — это объект. Значит его можно создать один раз и переиспользовать в десяти классах, параметризовать при создании, положить в список, сгенерировать в цикле. Валидатор поля, ленивое поле, поле с логированием доступа, поле из базы — всё это в Python пишется один раз как класс и дальше используется как x = PositiveInt().

Именно на этом стоят ORM (поле модели Django — дескриптор), pydantic, dataclasses с валидацией и половина конфигурационных библиотек. Не «магия фреймворка», а один протокол из трёх методов.

Сначала x есть только на классе и не является дескриптором — срабатывает шаг 3, видим 1. Присваивание a.x = 2 кладёт значение в данные инстанса, и теперь шаг 2 срабатывает раньше шага 3: инстанс видит 2, класс по-прежнему 1. del a.x убирает запись инстанса, шаг 2 снова не находит ничего, шаг 3 возвращает классовое значение. Ничего не «перезаписывалось» — просто менялось, какой шаг успевает первым.

property — не синтаксис и не магия. Это обычный объект с __get__, __set__ и __delete__, то есть дескриптор данных, лежащий на классе. Значит срабатывает шаг 1 и до словаря инстанса дело не доходит вовсе. Значение 99 лежит в b.__dict__ и недостижимо.

Отсюда же выводится то, что обычно запоминают отдельно: присваивание в property без сеттера падает не потому, что «property только для чтения», а потому, что __set__ у него определён всегда и просто выбрасывает AttributeError.

__slots__ делает две вещи. Убирает у инстанса __dict__ — то есть отключает шаг 2 полностью. И создаёт на классе по одному дескриптору данных на каждое объявленное имя, каждый из которых читает и пишет по фиксированному смещению в объекте.

Дальше всё следует. c.x работает, потому что шаг 1 находит дескриптор слота. c.y = 1 падает, потому что дескриптора y на классе нет, а положить значение больше некуда — шага 2 не существует. И становится понятно, почему __slots__ экономит память: исчезает целый словарь на объект.

Первое обращение к d.foo проходит все три шага впустую и попадает на четвёртый. После d.foo = 1 значение оказывается в данных инстанса, и шаг 2 отвечает раньше — __getattr__ уже не вызывается никогда. Это единственная причина разного вывода: не «перехватчик отключился», а поиск стал успешным раньше.

Здесь же лежит различие, которое путают чаще всего. __getattribute__ — это вся процедура целиком, он вызывается на каждое обращение. __getattr__ — только запасной выход на шаге 4. Переопределять первый опасно ровно потому, что внутри него любое обращение к атрибуту вызовет его же.