Если обратиться к документации, то дескриптор — механизм, который позволяет объектам настраивать поиск, хранение и удаление атрибутов.

Дескрипторы используются в классах, выступая в роли атрибутов класса(не экземпляра).

Думаю, мало кто, хотя бы раз, сам писал дескрипторы в коммерческой разработке, но я уверен, что большинство программистов используют механизмы, которые являются дескрипторами, или используют их "под капотом":

• classmethod, staticmethod

• property

• __slots__

• В конечном итоге, любое обращение к атрибуту класса, связано с дескрипторами.

Некоторые из них, мы реализуем с вами немного позднее.

Протокол дескрипторов состоит из:

• __get__ - Поиск атрибута

• __set__ - Хранение атрибута

• __delete__ - Удаление атрибута

Начнём с поиска атрибута - __get__ .

class StaticValueDescriptor:
    def __init__(self, value: Any) -> None:
        self._value = value
        
    def __get__(self, instance, owner=None) -> Any:
        return self._value

  
class Object:
    attr_1 = StaticValueDescriptor(100)

    
instance_object = Object()
instance_object.attr_1  # -> 100

Несмотря на то, что в attr_1 мы присвоили экземпляр StaticValueDescriptor, в ответе мы видим 100, но почему?

Дело в том, что при поиске атрибута класса(getattribute), python использует примерно такой механизм(подчеркнул одинаковые куски алгоритма):

• attr_1 есть в __dict__ класса?

  • Да. Есть ли у него __get__ и (__set__ или __delete__)(data descriptor)?

    • Да. Для получения результата используется дескриптор.

    • Нет. attr_1 есть в __dict__ экземпляра?

      • Да. Вернуть результат из __dict__ экземпляра.

      • Нет. attr_1 есть в __dict__ класса?

        • Да. Есть ли у него __get__ (non-data descriptor)?

          • Да. Для получения результата используется дескриптор.

          • Нет. Вернуть результат из __dict__ класса.

        • Нет. Вызов у класса getattr , который по умолчанию возбудит исключение AttributeError.

  • Нет. attr_1 есть в __dict__ экземпляра?

    • Да. Вернуть результат из __dict__ экземпляра.

    • Нет. attr_1 есть в __dict__ класса?

      • Да. Есть ли у него __get__ (non-data descriptor)?

        • Да. Для получения результата используется дескриптор.

        • Нет. Вернуть результат из __dict__ класса.

      • Нет. Вызов у класса getattr , который по умолчанию возбудит исключение AttributeError.

Согласен, некоторым, такое представление алгоритма покажется сложным. Я упрощу его и покажу лишь приоритеты получения атрибута при поиске:

1. Data descriptor - дескриптор, у которого есть __get__ и (__set__ или __delete__)

2. Instance.__dict__

3. Следующие два варианта имеют одинаковый приоритет.
   

   1. Non-data descriptor - дескриптор, у которого есть только __get__

   2. Class.__dict__

Мы ещё вернёмся к примерам, которые продемонстрируют работу приоритетов на деле, а пока давайте вернёмся к протоколу дескрипторов.

Ещё не дойдя до __set__ или __delete__ у вас, может возникнуть вопрос - "а как связать конкретный дескриптор с конкретным атрибутом? Я не хочу использовать только хардкодные статические объекты". И правда, предыдущий пример со StaticValueDescriptor имеет достаточно узкую применимость.

Решением с ходу является расширение __init__. И давайте сразу реализуем __set__:

class DataDescriptor:
    def __init__(self, attr_name: str) -> None:
        self._attr_name = attr_name
    
    def __get__(self, instance, owner=None) -> Any:
        return instance.__dict__[self._attr_name]

    def __set__(self, instance, value: Any) -> None:
        instance.__dict__[self._attr_name] = value

        
class Object:
  attr_1 = DataDescriptor("attr_1")

  
instance_object = Object()
instance_object.attr_1 = 100
instance_object.attr_1  # -> 100

В целом мы решили проблему, и смогли связать имя атрибута в рамках класса, где используется дескриптор, но можно сделать ещё лучше, используя __set_name__:

class DataDescriptor:
    def __set_name__(self, owner, attr_name: str) -> None:
        self._attr_name = attr_name

    def __get__(self, instance, owner=None) -> Any:
        return instance.__dict__[self._attr_name]

    def __set__(self, instance, value: Any) -> None:
        instance.__dict__[self._attr_name] = value

        
class Object:
    attr_1 = DataDescriptor()

    
instance_object = Object()
instance_object.attr_1 = 100
instance_object.attr_1  # -> 100

Используя метод __set_name__ нам не нужно пробрасывать название переменной снаружи. Хотя уверен, найдутся те, кому нужно это:

class DataDescriptor:
    def __init__(self, attr_name: str) -> None:
        self._attr_name = attr_name
    
    def __get__(self, instance, owner=None) -> Any:
        return instance.__dict__[self._attr_name]

    def __set__(self, instance, value: Any) -> None:
        instance.__dict__[self._attr_name] = value

        
class Object:
    attr_1 = DataDescriptor("attr_999")  # Не надо так ?

    def __init__(self):
        self.attr_1 = 123

        
instance_object = Object()
instance_object.attr_999  # -> 123

Ну и напоследок у нас остаётся __delete__ :

class DataDescriptor:
    def __set_name__(self, owner, attr_name: str) -> None:
        self._attr_name = attr_name
    
    def __get__(self, instance, owner=None) -> Any:
        return instance.__dict__[self._attr_name]

    def __set__(self, instance, value: Any) -> None:
        instance.__dict__[self._attr_name] = value
    
    def __delete__(self, instance) -> None:
        del instance.__dict__[self._attr_name]

        
class Object:
    attr_1 = DataDescriptor()

    
instance_object = Object()
instance_object.attr_1 = 100
instance_object.attr_1  # -> 100
del instance_object.attr_1
instance_object.attr_1  # -> KeyError: 'attr_1'

Ничего не смущает? А что это за KeyError при получении атрибута класса? Непорядок!

Дело в том, что при вызове __get__ , наша попытка достать результат из instance.__dict__ терпит неудачу, так как такого ключа в словаре нет.

Получается, нам нужно обработать исключение KeyError в __get__ , __set__ , __delete__ и следовать алгоритму, описанному выше. Кажется, не очень удобным делать это руками, неправда ли? Выход есть!

Первый шаг - использовать встроенные механизмы(getattr, setattr, delattr), которые дадут нам корректное поведение:

class DataDescriptor:
    def __set_name__(self, owner, attr_name: str) -> None:
        self._attr_name = attr_name
    
    def __get__(self, instance, owner=None) -> Any:
        return getattr(instance, self._attr_name)

    def __set__(self, instance, value: Any) -> None:
        setattr(instance, self._attr_name, value)
    
    def __delete__(self, instance) -> None:
        delattr(instance, self._attr_name)

        
class Object:
    attr_1 = DataDescriptor()

    
instance_object = Object()
instance_object.attr_1 = 100
instance_object.attr_1  # -> 100
del instance_object.attr_1
instance_object.attr_1  # -> RecursionError: maximum recursion depth
                        # exceeded while calling a Python object

Кажется, у нас проблемы? При попытке доступа к attr_1 происходит следующее:

• Мы всё по тому же алгоритму выбираем источником данных дескриптор и попадаем в __get__ .

• Внутри мы используем getattr(instance, self._attr_name, value)

• Который, в свою очередь пытается получить из экземпляра класса атрибут attr_1(по сути, то же самое, что мы пытались сделать изначально)

• И мы снова попадаем в дескриптор и так по кругу.

И на эту проблему есть решение!

Второй шаг - добавить защищённый(protected) вариант имени атрибута:

class DataDescriptor:
    def __set_name__(self, owner, attr_name: str) -> None:
        self._protected_attr_name = f"{attr_name}"
    
    def __get__(self, instance, owner=None) -> Any:
        return getattr(instance, self._protected_attr_name)

    def __set__(self, instance, value: Any) -> None:
        setattr(instance, self._protected_attr_name, value)
    
    def __delete__(self, instance) -> None:
        delattr(instance, self._protected_attr_name)


class Object:
    attr_1 = DataDescriptor()

    
instance_object = Object()
instance_object.attr_1 = 100
instance_object.attr_1  # -> 100
del instance_object.attr_1
instance_object.attr_1  # -> AttributeError: 'Object' object has no attribute
                        # '_attr_1'. Did you mean: 'attr_1'?

Теперь мы добились корректной ошибки!

Возможно, некоторые из вас зададутся вопросом - "Куда делась проблема с рекурсией? Кажется, что в коде нет существенных изменений."

Давайте разберём, что изменилось при обращении к attr_1:

• Мы всё по тому же алгоритму выбираем источником данных дескриптор и попадаем в __get__ .

• Внутри мы используем getattr(instance, self._attr_name, value)

• Который пытается получить из экземпляра класса не attr_1, а _attr_1. _attr_1 не является дескриптором и поэтому не повлечёт за собой повторный вызов __get__ и зацикливание, приводящее к ошибке(RecursionError)

Таким образом, в экземпляре класса будет установлен атрибут _attr_1 , который не является дескриптором:

instance_object = Object()
instance_object.__dict__  # -> {}
instance_object.attr_1 = 100
instance_object.__dict__  # -> {"_attr_1": 100}

И напоследок, давайте разберём разницу между data и non-data дескрипторами. Она заключается в приоритетах поиска атрибута.

Data descriptor имеет __get__ и (__set__ или __delete__):

class StaticValueDescriptor:
    def __init__(self, value: Any) -> None:
        self._value = value
    
    def __set_name__(self, owner, attr_name: str) -> None:
        self._private_attr_name = f"_{attr_name}"

    def __get__(self, instance, owner=None) -> None:
        return self._value

    def __set__(self, instance, value: Any) -> None:
        setattr(instance, self._private_attr_name, value)

        
class Object:
    attr_1 = StaticValueDescriptor(100)
    
    def __init__(self):
        self.attr_1 = 200

        
object_ = Object()
object_.attr_1  # -> 100 - data descriptor имеет приоритет
                # над __dict__ экземпляра класса

Стоит нам закомментировать/удалить метод __set__, и мы получим non-data descriptor, у которого меньший приоритет, чем у __dict__ класса.

class StaticValueDescriptor:
    ...
    
    # def __set__(self, instance, value: Any) -> None:
    #    setattr(instance, self._private_attr_name, value)

    
class Object:
    attr_1 = StaticValueDescriptor(100)
    
    def __init__(self):
        self.attr_1 = 200

        
object_ = Object()
object_.attr_1  # -> 200

После того, как мы получили описание работы дескрипторов, предлагаю вернуться к началу статьи и обсудить механизмы, которые так или иначе связаны с дескрипторами. Я покажу одну из возможных реализаций этих механизмов на python.

staticmethod - Это non-data descriptor с одной задачей - просто вернуть тот же метод, что и был получен. Таким образом, мы избавляемся от self.

class StaticMethod:
    def __init__(self, method: Callable) -> None:
        self._method = method
    
    def __get__(self, instance, owner=None) -> Any:
        return self._method

      
class Object:
    @StaticMethod
    def attr_1():
        return 100

      
object_ = Object()
object_.attr_1()  # -> 100

classmethod - Не что иное, как non-data descriptor, который создаёт обёртку над изначальным методом, и вместо экземпляра класса(self), передаёт первым аргументом класс(cls).

class ClassMethod:
    def __init__(self, method: Callable) -> None:
        self._method = method
    
    def __get__(self, instance, owner=None) -> Any:
        @wraps(self._method)
        def wrapper(*args, **kwargs):
            return self._method(owner, *args, **kwargs)
        return wrapper

      
class Object:
    @ClassMethod
    def attr_1(cls):
        return cls

      
object_ = Object()
object_.attr_1()  # -> <class 'main.Object'>

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

class Property:
    def __init__(
        self,
        fget: Callable | None = None,
        fset: Callable | None = None,
        fdel: Callable | None = None,
    ) -> None:
        self._fget = fget
        self._fset = fset
        self._fdel = fdel
    
    def getattr(self, fget: Callable) -> Property:
        return type(self)(fget, self._fset, self._fdel)
    
    def setattr(self, fset: Callable) -> Property:
        return type(self)(self._fget, fset, self._fdel)
    
    def deleter(self, fdel: Callable) -> Property:
        return type(self)(self._fget, self._fset, fdel)
    
    def __get__(self, instance, owner=None) -> Any:
        return self._fget(instance)
    
    def __set__(self, instance, value) -> None:
        self._fset(instance, value)
    
    def __delete__(self, instance) -> None:
        self._fdel(instance)

        
class Object:
    def __init__(self, value: Any) -> None:
        self._attr_1 = value
        
    @Property
    def attr_1(self):
        return self._attr_1

    @attr_1.setattr
    def attr_1(self, value: Any) -> None:
        self._attr_1 = value
        
    @attr_1.deleter
    def attr_1(self) -> None:
        self._attr_1 = None

        
object_ = Object(100)
object_.attr_1  # -> 100
object_.attr_1 = 200
object_.attr_1  # -> 200
del object_.attr_1
object_.attr_1  # -> None

И в завершение без возможной реализации, хочется показать, что __slots__ тоже относится к дескрипторам:

class Object:
    __slots__ = ("attr_1", "attr_2")

    
type(Object.attr_1)  # -> <class 'member_descriptor'>
type(Object.attr_2)  # -> <class 'member_descriptor'>

Спасибо всем, кто справился и дочитал статью до конца! Это была вводная статья о дескрипторах. Возможно, в будущем я напишу вторую часть, и покажу какие ещё вещи можно реализовывать с помощью этого протокола.