成为Python砖家(5): 描述器descriptor的简单理解

第一次解释 discriptor 描述符

任何定义了 __get__()， __set__()或 __delete__()方法的对象。当一个类的某个属性是discriptor时，它的特殊绑定行为就会在属性查找时被触发。通常情况下， 使用 a.b来获取、设置或删除一个属性时，会在 a 类的字典中查找名称为 b 的对象。 但如果 b 是一个 descriptor，则会调用对应的descriptor方法。 理解描述器的概念是更深层次理解 Python 的关键， 因为这是许多重要特性的基础， 包括函数、方法、特征函数（properties）、类方法、静态方法以及对超类的引用等。

上面这段是官方文档的中文翻译版本中文字，来自 file:///Users/zz/Documents/python-3.12.5-docs-html/glossary.html#term-descriptor 。 实话说还是很不清晰的。

第二次解释 discriptor 描述符

在 Python 中， 描述符（descriptor）是一种具有特殊方法的对象，用于管理其他对象的属性访问。描述符协议包括三个核心方法：
● __get__()方法
● __set__()方法
● __delete__()方法

第三次解释 discriptor 描述符

在 Python 中，当定义了一个类，这个类含有 __get__(), __set__(), __delete__()三个方法中的任意一个或多个时，这个类的实例，称为 descriptor。
descriptor 可以具体分成两类：
● 非数据描述符（non-data descriptor）：前面提到的三个魔术方法中，仅定义了 __get()__方法，没定义 __set()__和 __delete__()，此时的类对象称为 non-data descriptor
● 数据描述符（data descriptor): 在实现了 __set__()或 __delete__()时（即：只实现了它们两个中的一个，或都实现了），此时的类对象称为 data descriptor
而提到的 __get()__, __set()__和 __delete__()则统称为 descriptor method

通过使用 descriptor 来理解 descriptor: __get()__方法

前一节提到 get(), 很容易误导新人，认为函数参数是空的。完整的函数说明是：
object.get(self, instance, owner=None)

object.__get__(self, instance, owner=None)

(file:///Users/zz/Documents/pydoc-zh-cn/python-3.12.5-docs-html/reference/datamodel.html#object.__get__)
文档里的解释：

调用此方法以获取所有者类的属性（类属性访问）或该类的实例的属性（实例属性访问）。 可选的 owner 参数是所有者类而 instance 是被用来访问属性的实例，如果通过 owner 来访问属性则返回 None。

使用最小复现代码来表述：

class B:
    def __get__(self, instance, owner):
        print(f'instance: {instance}, owner: {owner}')
        if instance:
            return f'Accessed through instance: {instance}'
        elif owner:
            return f'Accessed through owner: {owner}'


class A:
    b = B()


# 通过类访问属性，调用了 __get__()
print(A.b)

# 通过实例访问属性，调用了 __get__()
a = A()
print(a.b)

运行输出如下：

instance: None, owner: <class '__main__.A'>
Accessed through owner: <class '__main__.A'>
instance: <__main__.A object at 0x100f8c910>, owner: <class '__main__.A'>
Accessed through instance: <__main__.A object at 0x100f8c910>

解释：
类A的成员b是 descriptor, 访问 A.b或 a.b时是访问了方法 __get__()。
● A.b:会传入owner，也就是 A.b相当于调用 B.__get__(self, None, actual_owner);
● a.b相当于调用 B.__get__(self, actual_instance, actual_owner)
也就是说：
● descriptor 方法__get__()需要返回一个字符串，至于返回什么样子的字符串，用户可以根据函数参数做判断和给出不同结果，参数有 instance和 owner两个
● instance和 owner是自动传入的，owner总是有值， instance则可能为 None （通过类访问属性）或非 None（通过实例访问属性）

通过使用 descriptor 来理解 descriptor: __set()__和 __set_name()__方法

下面给出使用 __set__()的例子：在 __set__()内做定制化的检查，比如只允给 descriptor 赋值为 int 类型。

class IntAttr:
    def __get__(self, instance, owner):
        return instance.__dict__.get(self.name, 330)

    def __set__(self, instance, value):
        if isinstance(value, int):
            instance.__dict__[self.name] = value
        else:
            raise TypeError(f"Only support int type, got {type(value)}")

    def __set_name__(self, owner, name):
        self.name = name

class ZhejiangRen:
    id_num = IntAttr()

p = ZhejiangRen()
print(p.id_num) # 330

p.id_num = 339
print(p.id_num) # 339

try:
    p.id_num = "Zhejiang"
except TypeError as e:
    print(e) # Only support int type, got <class 'str'>

其中 __set_name__(self, owner, name) 方法是描述符协议的一部分，它在 Python 3.6 及更高版本中被引入，用于让描述符在被绑定到某个类的属性时能够获得该属性的名称。这个方法的主要作用是在描述符第一次被附加到类的属性时调用，为描述符提供了一种知道自己被安装在哪个属性上的机制。

总结

远远谈不上熟悉 descriptor, 仅仅是按照官方文档，把不明白的地方，尝试写了代码，来增加了对于 descriptor 的理解。descriptor首先应当是类的属性，而不能是实例的属性：

class A:
    b = B() # b 是 descriptor

class C:
    def __init__(self):
        d = D() # d 不是 descriptor

descriptor 的类（上述代码中B），应当定义了 __set__()， __get__()或 __delete__()中的任意一个。还可以定义 __set_name__()（since python 3.6)。这几个函数统称为descriptor method, 它们有具体的参数，是：
● __get__(self, instance, owner)
● __set__(self, instance, value)
● __set_name__(self, owner, name)
● __delete__(self, instance)
当读取了 descriptor 是调用 __get__()， 当写入 descriptor 是调用 __set__() 删除则是调用 __delete__(). 其实颇有一种 C++ 中 RAII 的感觉，是在原本的操作（读取、赋值、删除）外面包装了一层定制化的东西。这样说来，和decorator也有点像。但是decorator是针对函数的，而descriptor是针对类属性的。