descriptor.md
1> **Источник:** https://python-all.ru/2.7/howto/descriptor.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [Руководство по дескрипторам](https://python-all.ru/2.7/howto/descriptor.html#id1)89**Автор**1011Рэймонд Хеттингер1213**Контакт**1415\<python at rcn dot com\>1617Содержание1819- [Руководство по дескрипторам](https://python-all.ru/2.7/howto/descriptor.html#descriptor-howto-guide)2021 - [Аннотация](https://python-all.ru/2.7/howto/descriptor.html#abstract)22 - [Определение и введение](https://python-all.ru/2.7/howto/descriptor.html#definition-and-introduction)23 - [Протокол дескрипторов](https://python-all.ru/2.7/howto/descriptor.html#descriptor-protocol)24 - [Вызов дескрипторов](https://python-all.ru/2.7/howto/descriptor.html#invoking-descriptors)25 - [Пример дескриптора](https://python-all.ru/2.7/howto/descriptor.html#descriptor-example)26 - [Свойства](https://python-all.ru/2.7/howto/descriptor.html#properties)27 - [Функции и методы](https://python-all.ru/2.7/howto/descriptor.html#functions-and-methods)28 - [Статические методы и методы класса](https://python-all.ru/2.7/howto/descriptor.html#static-methods-and-class-methods)2930## [Аннотация](https://python-all.ru/2.7/howto/descriptor.html#id2)3132Определяет дескрипторы, обобщает протокол и показывает, как вызываются дескрипторы. Рассматривает пользовательский дескриптор и несколько встроенных дескрипторов Python, включая функции, свойства, статические методы и методы класса. Показывает, как каждый из них работает, приводя эквивалент на чистом Python и пример приложения.3334Изучение дескрипторов не только даёт доступ к более широкому набору инструментов, но и позволяет глубже понять, как работает Python, и оценить элегантность его устройства.3536## [Определение и введение](https://python-all.ru/2.7/howto/descriptor.html#id3)3738В общем случае дескриптор – это атрибут объекта с «поведением связывания», доступ к которому переопределён методами протокола дескриптора. Такими методами являются [`__get__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__), [`__set__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__set__) и [`__delete__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__delete__). Если для объекта определён хотя бы один из этих методов, он считается дескриптором.3940Поведение по умолчанию при доступе к атрибуту заключается в получении, установке или удалении атрибута из словаря объекта. Например, `a.x` имеет цепочку поиска, начиная с `a.__dict__['x']`, затем `type(a).__dict__['x']` и далее по базовым классам `type(a)`, исключая метаклассы. Если найденное значение является объектом, определяющим один из методов дескриптора, то Python может переопределить поведение по умолчанию и вместо этого вызвать метод дескриптора. Где это происходит в цепочке приоритетов, зависит от того, какие методы дескриптора были определены. Обратите внимание, что дескрипторы вызываются только для объектов или классов нового стиля (класс является новым стилем, если он наследуется от [`object`](https://python-all.ru/2.7/library/functions.html#object) или [`type`](https://python-all.ru/2.7/library/functions.html#type)).4142Дескрипторы – это мощный универсальный протокол. Они лежат в основе свойств, методов, статических методов, методов класса и [`super()`](https://python-all.ru/2.7/library/functions.html#super). Они используются во всём Python для реализации классов нового стиля, появившихся в версии 2.2. Дескрипторы упрощают внутренний C-код и предоставляют гибкий набор новых инструментов для повседневных программ на Python.4344## [Протокол дескриптора](https://python-all.ru/2.7/howto/descriptor.html#id4)4546`descr.__get__(self, obj, type=None) --> value`4748`descr.__set__(self, obj, value) --> None`4950`descr.__delete__(self, obj) --> None`5152Вот и всё. Определите любой из этих методов – и объект считается дескриптором и может переопределять поведение по умолчанию при поиске в качестве атрибута.5354Если объект определяет и [`__get__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__), и [`__set__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__set__), он считается data-дескриптором. Дескрипторы, определяющие только [`__get__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__), называются non-data-дескрипторами (обычно они используются для методов, но возможны и другие применения).5556Дескрипторы данных и не-данных различаются тем, как вычисляются переопределения по отношению к записям в словаре экземпляра. Если в словаре экземпляра есть запись с тем же именем, что и у дескриптора данных, дескриптор данных имеет приоритет. Если в словаре экземпляра есть запись с тем же именем, что и у дескриптора не-данных, приоритет имеет запись словаря.5758Чтобы создать дескриптор данных только для чтения, определите и [`__get__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__), и [`__set__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__set__), причём [`__set__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__set__) должен возбуждать [`AttributeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.AttributeError) при вызове. Определения метода [`__set__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__set__) с заглушкой, возбуждающей исключение, достаточно, чтобы сделать его дескриптором данных.5960## [Вызов дескрипторов](https://python-all.ru/2.7/howto/descriptor.html#id5)6162Дескриптор можно вызвать напрямую по имени его метода. Например, `d.__get__(obj)`.6364Чаще, однако, дескриптор вызывается автоматически при доступе к атрибуту. Например, `obj.d` ищет `d` в словаре `obj`. Если `d` определяет метод [`__get__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__), то `d.__get__(obj)` вызывается в соответствии с правилами приоритета, приведёнными ниже.6566Детали вызова зависят от того, является ли `obj` объектом или классом. В любом случае дескрипторы работают только с объектами и классами нового стиля. Класс является новым стилем, если он является подклассом [`object`](https://python-all.ru/2.7/library/functions.html#object).6768Для объектов механизм находится в [`object.__getattribute__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattribute__), который преобразует `b.x` в `type(b).__dict__['x'].__get__(b, type(b))`. Реализация работает через цепочку приоритетов, где дескрипторы данных имеют приоритет над переменными экземпляра, переменные экземпляра – над дескрипторами без данных, а самый низкий приоритет присваивается [`__getattr__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattr__), если он предоставлен. Полную реализацию на C можно найти в [`PyObject_GenericGetAttr()`](https://python-all.ru/2.7/c-api/object.html#c.PyObject_GenericGetAttr) в [Objects/object.c](https://python-all.ru/src/2.7/Objects/object.c).6970Для классов механизм находится в `type.__getattribute__()`, который преобразует `B.x` в `B.__dict__['x'].__get__(None, B)`. На чистом Python это выглядит так:7172```python73def __getattribute__(self, key):74 "Emulate type_getattro() in Objects/typeobject.c"75 v = object.__getattribute__(self, key)76 if hasattr(v, '__get__'):77 return v.__get__(None, self)78 return v79```8081Важно запомнить следующее:8283- дескрипторы вызываются методом [`__getattribute__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattribute__)84- переопределение [`__getattribute__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattribute__) предотвращает автоматический вызов дескрипторов85- [`__getattribute__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattribute__) доступен только для классов и объектов нового стиля.86- [`object.__getattribute__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattribute__) и `type.__getattribute__()` выполняют разные вызовы [`__get__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__).87- дескрипторы данных всегда переопределяют словари экземпляров.88- дескрипторы без данных могут быть переопределены словарями экземпляров.8990Объект, возвращаемый `super()`, также имеет пользовательский [`__getattribute__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattribute__) метод для вызова дескрипторов. Вызов `super(B, obj).m()` ищет `obj.__class__.__mro__` базовый класс `A`, следующий сразу после `B` и затем возвращает `A.__dict__['m'].__get__(obj, B)`. Если это не дескриптор, `m` возвращается без изменений. Если его нет в словаре, `m` возвращается к поиску с помощью [`object.__getattribute__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattribute__).9192Обратите внимание: в Python 2.2 `super(B, obj).m()` вызывал [`__get__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__) только если `m` был дескриптором данных. В Python 2.3 дескрипторы не-данных также вызываются, если только не задействован класс старого стиля. Детали реализации находятся в `super_getattro()` в [Objects/typeobject.c](https://python-all.ru/src/2.7/Objects/typeobject.c).9394Приведённые выше детали показывают, что механизм дескрипторов встроен в методы [`__getattribute__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattribute__) для [`object`](https://python-all.ru/2.7/library/functions.html#object), [`type`](https://python-all.ru/2.7/library/functions.html#type) и [`super()`](https://python-all.ru/2.7/library/functions.html#super). Классы наследуют этот механизм, если они являются подклассами [`object`](https://python-all.ru/2.7/library/functions.html#object) или имеют метакласс, предоставляющий аналогичную функциональность. Классы также могут отключать вызов дескрипторов, переопределяя [`__getattribute__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattribute__).9596## [Пример дескриптора](https://python-all.ru/2.7/howto/descriptor.html#id6)9798Следующий код создаёт класс, объекты которого являются дескрипторами данных, выводящими сообщение при каждом получении или установке значения. Переопределение [`__getattribute__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getattribute__) – это альтернативный подход, который мог бы делать это для каждого атрибута. Однако этот дескриптор удобен для отслеживания лишь нескольких выбранных атрибутов:99100```python101class RevealAccess(object):102 """Дескриптор данных, который обычным образом устанавливает и возвращает значения, а также выводит сообщение, регистрируя их доступ.103 обычным образом и выводит сообщение, регистрируя их доступ.104 """105106 def __init__(self, initval=None, name='var'):107 self.val = initval108 self.name = name109110 def __get__(self, obj, objtype):111 print 'Retrieving', self.name112 return self.val113114 def __set__(self, obj, val):115 print 'Updating', self.name116 self.val = val117118>>> class MyClass(object):119... x = RevealAccess(10, 'var "x"')120... y = 5121...122>>> m = MyClass()123>>> m.x124Retrieving var "x"12510126>>> m.x = 20127Updating var "x"128>>> m.x129Retrieving var "x"13020131>>> m.y1325133```134135Протокол прост и открывает захватывающие возможности. Некоторые сценарии использования настолько распространены, что были упакованы в отдельные вызовы функций. Свойства (properties), связанные (bound) и несвязанные (unbound) методы, статические методы и методы класса – все основаны на протоколе дескрипторов.136137## [Свойства](https://python-all.ru/2.7/howto/descriptor.html#id7)138139Вызов [`property()`](https://python-all.ru/2.7/library/functions.html#property) – это краткий способ создания дескриптора данных, который вызывает функции при доступе к атрибуту. Его сигнатура:140141```python142property(fget=None, fset=None, fdel=None, doc=None) -> property attribute143```144145В документации показан типичный пример использования для определения управляемого атрибута `x`:146147```python148class C(object):149 def getx(self): return self.__x150 def setx(self, value): self.__x = value151 def delx(self): del self.__x152 x = property(getx, setx, delx, "I'm the 'x' property.")153```154155Чтобы увидеть, как [`property()`](https://python-all.ru/2.7/library/functions.html#property) реализуется через протокол дескрипторов, вот эквивалент на чистом Python:156157```python158class Property(object):159 "Emulate PyProperty_Type() in Objects/descrobject.c"160161 def __init__(self, fget=None, fset=None, fdel=None, doc=None):162 self.fget = fget163 self.fset = fset164 self.fdel = fdel165 if doc is None and fget is not None:166 doc = fget.__doc__167 self.__doc__ = doc168169 def __get__(self, obj, objtype=None):170 if obj is None:171 return self172 if self.fget is None:173 raise AttributeError("unreadable attribute")174 return self.fget(obj)175176 def __set__(self, obj, value):177 if self.fset is None:178 raise AttributeError("can't set attribute")179 self.fset(obj, value)180181 def __delete__(self, obj):182 if self.fdel is None:183 raise AttributeError("can't delete attribute")184 self.fdel(obj)185186 def getter(self, fget):187 return type(self)(fget, self.fset, self.fdel, self.__doc__)188189 def setter(self, fset):190 return type(self)(self.fget, fset, self.fdel, self.__doc__)191192 def deleter(self, fdel):193 return type(self)(self.fget, self.fset, fdel, self.__doc__)194```195196Встроенная функция [`property()`](https://python-all.ru/2.7/library/functions.html#property) помогает, когда пользовательский интерфейс предоставил доступ к атрибуту, а последующие изменения требуют вмешательства метода.197198Например, класс электронной таблицы может предоставлять доступ к значению ячейки через `Cell('b10').value`. Последующие улучшения программы требуют пересчёта ячейки при каждом доступе; однако программист не хочет влиять на существующий клиентский код, обращающийся к атрибуту напрямую. Решение – обернуть доступ к атрибуту значения в дескриптор данных свойства:199200```python201class Cell(object):202 . . .203 def getvalue(self):204 "Recalculate the cell before returning value"205 self.recalc()206 return self._value207 value = property(getvalue)208```209210## [Функции и методы](https://python-all.ru/2.7/howto/descriptor.html#id8)211212Объектно-ориентированные возможности Python построены на функциональной основе. С помощью дескрипторов, не являющихся дескрипторами данных, эти две парадигмы объединяются бесшовно.213214Словари классов хранят методы как функции. В определении класса методы записываются с помощью [`def`](https://python-all.ru/2.7/reference/compound_stmts.html#def) и [`lambda`](https://python-all.ru/2.7/reference/expressions.html#lambda) – обычных инструментов для создания функций. Единственное отличие от обычных функций в том, что первый аргумент зарезервирован для экземпляра объекта. По соглашению Python ссылка на экземпляр называется *self*, но может называться *this* или любым другим именем переменной.215216Для поддержки вызовов методов функции включают метод [`__get__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__) для связывания методов при доступе к атрибуту. Это означает, что все функции являются дескрипторами не данных (non-data descriptors), которые возвращают связанные или несвязанные методы в зависимости от того, вызываются ли они от объекта или от класса. На чистом Python это работает так:217218```python219class Function(object):220 . . .221 def __get__(self, obj, objtype=None):222 "Simulate func_descr_get() in Objects/funcobject.c"223 return types.MethodType(self, obj, objtype)224```225226Запуск интерпретатора показывает, как дескриптор функции работает на практике:227228```python229>>> class D(object):230... def f(self, x):231... return x232...233>>> d = D()234>>> D.__dict__['f'] # Внутренне хранится как функция235<function f at 0x00C45070>236>>> D.f # При получении из класса становится несвязанным методом237<unbound method D.f>238>>> d.f # При получении из экземпляра становится связанным методом239<bound method D.f of <__main__.D object at 0x00B18C90>>240```241242Вывод предполагает, что связанные и несвязанные методы – это два разных типа. Хотя их можно было реализовать таким образом, фактическая C-реализация [`PyMethod_Type`](https://python-all.ru/2.7/c-api/method.html#c.PyMethod_Type) в [Objects/classobject.c](https://python-all.ru/src/2.7/Objects/classobject.c) представляет собой единый объект с двумя разными представлениями в зависимости от того, установлено ли поле `im_self` или равно *NULL* (C-эквивалент `None`).243244Аналогично, эффект вызова объекта метода зависит от поля `im_self`. Если оно установлено (то есть метод связан), исходная функция (хранящаяся в поле `im_func`) вызывается как обычно, с первым аргументом, установленным на экземпляр. Если не связано, все аргументы передаются исходной функции без изменений. Фактическая C-реализация `instancemethod_call()` лишь немного сложнее тем, что включает некоторую проверку типов.245246## [Статические методы и методы класса](https://python-all.ru/2.7/howto/descriptor.html#id9)247248Дескрипторы, не являющиеся дескрипторами данных, предоставляют простой механизм для вариаций обычных шаблонов привязки функций к методам.249250Повторим: функции имеют метод [`__get__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__), чтобы их можно было преобразовать в метод при доступе как атрибуты. Дескриптор, не являющийся дескриптором данных, преобразует вызов `obj.f(*args)` в `f(obj, *args)`. Вызов `klass.f(*args)` становится `f(*args)`.251252Эта таблица обобщает привязку и два наиболее полезных её варианта:253254> | Преобразование | Вызов из объекта | Вызов из класса |255> | --- | --- | --- |256> | функция | f(obj, \*args) | f(\*args) |257> | staticmethod | f(\*args) | f(\*args) |258> | classmethod | f(type(obj), \*args) | f(klass, \*args) |259260Статические методы возвращают базовую функцию без изменений. Вызов `c.f` или `C.f` эквивалентен прямому поиску в `object.__getattribute__(c, "f")` или `object.__getattribute__(C, "f")`. В результате функция становится одинаково доступной как из объекта, так и из класса.261262Хорошими кандидатами для статических методов являются те, которые не ссылаются на переменную `self`.263264Например, в пакете статистики может быть класс-контейнер для экспериментальных данных. Класс предоставляет обычные методы для вычисления среднего, медианы и других описательных статистик, которые зависят от данных. Однако могут быть полезные функции, которые концептуально связаны, но не зависят от данных. Например, `erf(x)` – это удобная процедура преобразования, которая встречается в статистической работе, но не зависит напрямую от конкретного набора данных. Её можно вызвать как от объекта, так и от класса: `s.erf(1.5) --> .9332` или `Sample.erf(1.5) --> .9332`.265266Поскольку статические методы возвращают базовую функцию без изменений, примеры вызовов неинтересны:267268```python269>>> class E(object):270... def f(x):271... print x272... f = staticmethod(f)273...274>>> print E.f(3)2753276>>> print E().f(3)2773278```279280Используя протокол дескриптора без данных, чистая версия [`staticmethod()`](https://python-all.ru/2.7/library/functions.html#staticmethod) на Python выглядела бы так:281282```python283class StaticMethod(object):284 "Emulate PyStaticMethod_Type() in Objects/funcobject.c"285286 def __init__(self, f):287 self.f = f288289 def __get__(self, obj, objtype=None):290 return self.f291```292293В отличие от статических методов, методы класса перед вызовом функции добавляют ссылку на класс в начало списка аргументов. Этот формат одинаков как для вызова от объекта, так и от класса:294295```python296>>> class E(object):297... def f(klass, x):298... return klass.__name__, x299... f = classmethod(f)300...301>>> print E.f(3)302('E', 3)303>>> print E().f(3)304('E', 3)305```306307Такое поведение полезно, когда функции нужна только ссылка на класс и не важны данные экземпляра. Одно из применений classmethod – создание альтернативных конструкторов класса. В Python 2.3 classmethod [`dict.fromkeys()`](https://python-all.ru/2.7/library/stdtypes.html#dict.fromkeys) создаёт новый словарь из списка ключей. Чистый эквивалент на Python выглядит так:308309```python310class Dict(object):311 . . .312 def fromkeys(klass, iterable, value=None):313 "Emulate dict_fromkeys() in Objects/dictobject.c"314 d = klass()315 for key in iterable:316 d[key] = value317 return d318 fromkeys = classmethod(fromkeys)319```320321Теперь новый словарь уникальных ключей можно создать так:322323```python324>>> Dict.fromkeys('abracadabra')325{'a': None, 'r': None, 'b': None, 'c': None, 'd': None}326```327328Используя протокол дескриптора без данных, чистая версия [`classmethod()`](https://python-all.ru/2.7/library/functions.html#classmethod) на Python выглядела бы так:329330```python331class ClassMethod(object):332 "Emulate PyClassMethod_Type() in Objects/funcobject.c"333334 def __init__(self, f):335 self.f = f336337 def __get__(self, obj, klass=None):338 if klass is None:339 klass = type(obj)340 def newfunc(*args):341 return self.f(klass, *args)342 return newfunc343```344