Python官方文档：Descriptor 指南，pythondescriptor,未经许可，禁止转载！英文

本文由 编橙之家 - icejoywoo 翻译，Namco 校稿。未经许可，禁止转载！
英文出处：Raymond Hettinger。欢迎加入翻译组。

摘要

定义Descriptor并概述其协议，以及展示如何调用Descriptor。深入学习自定义Descriptor和几个内置的Python Descriptor，包括函数、property、静态方法和类方法。通过纯Python代码等价实现和应用示例来揭示其运行原理。

学习Descriptor不仅可以获得更多的工具集，而且可以更好地体会Python的运行原理及其优雅的设计。

定义和介绍

一般来说，Descriptor是伴随有“绑定行为”的对象属性，其属性访问可以根据Descriptor协议通过方法来控制。方法有__get__()、__set__()和__delete__()。如果在对象中定义了其中任意方法，那么这个对象就称为Descriptor。

对象中属性访问的默认行为就是在对象的字典中get、set或delete相应的属性。例如，a.x的查找顺序是从 a.__dict__[‘x’] 到 type(a).__dict__[‘x’]，然后继续在type(a)除元类（metaclass）外的基类中查找。如果要查找的值是定义了任意Descriptor方法的对象，那么Python会调用Descriptor方法来覆盖默认行为。查找的优先级顺序取决于定义了哪些Descriptor方法。

Descriptor是一个强大而通用的协议，是property、方法、静态方法、类方法和super()背后的机制。在Python的内部使用Descriptor来实现了2.2版本中引入的新风格类。Descriptor抽象了底层的c代码，为Python日常编码提供了一个灵活的新工具集。

Descriptor协议

Python

descr.__get__(self, obj, type=None) --> value

descr.__set__(self, obj, value) --> None

descr.__delete__(self, obj) --> None

这就是协议的全部。对象只要定义其中任意方法就是Descriptor，就可以覆盖属性查找的默认行为。

同时定义了__get__()和__set__()的对象就叫作Data Descriptor。而只定义了__get__()的Descriptor就被叫做Non-data Descriptor（这种方式就是类方法的典型用法，当然也可能有其他用法）。

Data Descriptor和Non-data Descriptor的不同体现在关于实例字典条目的覆盖和计算顺序上。如果实例字典中包含了与Data Descriptor同名的属性，那么Data Descriptor优先。如果实例字典中包含了与Non-data Descriptor同名的属性，实例字典优先。

（译注：实例字典是指类实例中__dict__。关于优先级的代码示例参考：https://gist.github.com/icejoywoo/0f19fa8575ac664140fc）

同时定义__get__()和__set__()方法，并且__set__()在调用时抛出AttributeError异常，就可以创建一个只读的Data Descriptor。只需要定义一个抛出异常的__set__()方法就足以让该对象成为Data Descriptor。

调用Descriptor

Descriptor可以直接通过方法名来进行调用。例如，d.__get__(obj)。

另外，更常用的方式是通过属性访问来自动地调用Descriptor。例如，obj.d在obj的对象字典中查找d。如果d定义了__get__()方法，那么根据下面列出的优先级规则，就会优先调用d.__get__(obj)。

调用的细节取决于obj是对象还是类。

对于对象来说，其机制是object.__getattribute__()将b.x转换为type(b).__dict__[‘x’].__get__(b, type(b))。其实现的优先级链是：Data Descriptor优先级高于实例变量（instance variables），实例变量优先级高于Non-data Descriptor，而 __getattr__() 的优先级是最低的。完整的c代码实现在Objects/object.c的PyObject_GenericGetAttr()函数中。

对于类来说，其机制是type.__getattribute__()将B.x转换为B.__dict__[‘x’].__get__(None, B)。纯Python的代码实现如下：

Python

def __getattribute__(self, key):
    "Emulate type_getattro() in Objects/typeobject.c"
    "模拟Objects/typeobject.c中的type_getattro()"
    v = object.__getattribute__(self, key)
    if hasattr(v, '__get__'):
       return v.__get__(None, self)
    return v

需要记住的重要几点：

• Descriptor是通过__getattribute__()方法来调用的
• 覆写__getattribute__()可以阻止Descriptor的自动调用
• object.__getattribute__()和type.__getattribute__()调用__get__()的方式不同
• Data Descriptor总是覆盖实例字典
• Non-data Descriptor可能会被实例字典覆盖

super()返回的对象也有一个用于调用Descriptor的定制__getattribute__()方法。super(B, obj).m()会搜查obj.__class__.__mro__中的基类A，返回A.__dict__[‘m’].__get__(obj, B)。如果不是Descriptor，m返回也是一样的。如果m不在实例字典中，就还原为通过object.__getattribute__()来搜索。

实现细节在Object/typeobject.c的super_getattro()函数中。Guido的入门教程有纯Python的等价实现。

上面描述了在object、type和super()中隐藏在__getattribute__()方法内部的Descriptor机制。这种机制是可继承的。如果一个类派生自某个对象，或者这个类的元类实现了相似的机制，这个类就可以继承该机制。同样地，类可以通过覆写__getattribute__()来屏蔽Descriptor。

Descriptor示例

下面的代码创建了一个Data Descriptor的类，会在get或set时打印一条信息。覆写__getattribute__()也可以为每个属性加上打印信息。然而，在监控几个选定的属性时Descriptor是很用的：

Python

class RevealAccess(object):
    """A data descriptor that sets and returns values
       normally and prints a message logging their access.
       Data Descriptor在赋值和取值时打印一条记录访问的信息。
    """

    def __init__(self, initval=None, name='var'):
        self.val = initval
        self.name = name

    def __get__(self, obj, objtype):
        print('Retrieving', self.name)
        return self.val

    def __set__(self, obj, val):
        print('Updating', self.name)
        self.val = val

>>> class MyClass(object):
    x = RevealAccess(10, 'var "x"')
    y = 5

>>> m = MyClass()
>>> m.x
Retrieving var "x"
10
>>> m.x = 20
Updating var "x"
>>> m.x
Retrieving var "x"
20
>>> m.y
5

Descriptor协议简单并且提供了令人兴奋的可能性。这几种使用场景是非常普遍的，所以都打包成了单独的函数调用。Property，绑定和未绑定的方法，静态方法和类方法都是基于Descriptor协议的。

属性

调用property()是一种简洁的创建Data Descriptor的方式，会在访问属性时触发函数调用。函数签名如下：

Python

property(fget=None, fset=None, fdel=None, doc=None) -> property attribute

文档展示了托管属性x的典型用法：

Python

class C(object):
    def getx(self): return self.__x
    def setx(self, value): self.__x = value
    def delx(self): del self.__x
    x = property(getx, setx, delx, "I'm the 'x' property.")

来看下property()是如何使用Descriptor协议来实现的，下面是纯Python的等价实现：

Python

class Property(object):
    "Emulate PyProperty_Type() in Objects/descrobject.c"

    def __init__(self, fget=None, fset=None, fdel=None, doc=None):
        self.fget = fget
        self.fset = fset
        self.fdel = fdel
        if doc is None and fget is not None:
            doc = fget.__doc__
        self.__doc__ = doc

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        if self.fget is None:
            raise AttributeError("unreadable attribute")
        return self.fget(obj)

    def __set__(self, obj, value):
        if self.fset is None:
            raise AttributeError("can't set attribute")
        self.fset(obj, value)

    def __delete__(self, obj):
        if self.fdel is None:
            raise AttributeError("can't delete attribute")
        self.fdel(obj)

    def getter(self, fget):
        return type(self)(fget, self.fset, self.fdel, self.__doc__)

    def setter(self, fset):
        return type(self)(self.fget, fset, self.fdel, self.__doc__)

    def deleter(self, fdel):
        return type(self)(self.fget, self.fset, fdel, self.__doc__)

每当用户接口授权属性访问并且后续变化需要方法的接入，property()内置函数都是有用的。

例如，电子表格类可以授权通过Cell(‘b10’).value访问单元格的值。对程序的后续变化需要单元格在每次访问时重新计算；然而，程序员不希望影响现有直接访问属性的客户端代码。解决方案就是用Property Data Descriptor来封装对值属性的访问：

Python

class Cell(object):
    . . .
    def getvalue(self, obj):
        "Recalculate cell before returning value"
        self.recalc()
        return obj._value
    value = property(getvalue)

函数和方法

Python的面向对象特性是建立在以函数为基础的环境之上的。使用Non-data Descriptor，函数和方法可以无缝地融合起来。

Class字典将方法存储为函数。在Class的定义中，方法和函数同样都用def和lambda来定义。方法与函数唯一的不同是其第一个参数预留给对象实例（object instance）的。按照Python的惯例，这个实例引用被称为self，在其他语言中可能是this或其他名字。

为了支持方法调用，函数有__get__()方法，可以在属性访问时绑定方法。这意味着所有的函数都是Non-data Descriptor，根据调用方是对象或类来返回绑定或非绑定方法。纯Python实现如下：

Python

class Function(object):
    . . .
    def __get__(self, obj, objtype=None):
        "Simulate func_descr_get() in Objects/funcobject.c"
        return types.MethodType(self, obj, objtype)

在解释器中展示函数Descriptor实际是如何工作的：

Python

>>> class D(object):
     def f(self, x):
          return x

>>> d = D()
>>> D.__dict__['f'] # Stored internally as a function
<function f at 0x00C45070>
>>> D.f             # Get from a class becomes an unbound method
<unbound method D.f>
>>> d.f             # Get from an instance becomes a bound method
<bound method D.f of <__main__.D object at 0x00B18C90>>

上面的输出信息表示绑定和非绑定方法是两种不同的类型。尽管我们可以用上述方式实现，但是在Objects/classobject.c 中的 PyMethod_Type 其实是用一个对象实现的，只是这个对象存在两种不同的表现形式，而表现形式则取决于 im_self 的值是否为空（在 C 语言中表示 None 的关键字为 NULL）。

同样地，方法对象调用的效果依赖于im_self字段。如果赋值（意味着绑定），原函数（保存在im_func字段中）在调用时会设置第一个参数为实例。如果非绑定，所有的参数保持不变传入原函数中。instancemethod_call()的C实现因为包含一些类型检查而变得稍稍复杂了一点。

静态方法和类方法

Non-data descriptor为函数绑定到方法的常用模式中提供了一个简单的变化机制。

总的来说，函数有__get__()方法，因此在当作属性访问时会转换为方法。Non-data Descriptor将obj.f(*args)变成f(obj, *args)，将klass.f(*args)变成f(*args)。

下表总结了绑定和它的两个最有用的变种：

Transformation	Called from an Object	Called from a Class
function	f(obj, *args)	f(*args)
staticmethod	f(*args)	f(*args)
classmethod	f(type(obj), *args)	f(klass, *args)

静态方法返回没有任何变化的原函数。调用c.f或C.f相当于直接查找object.__getattribute__(c, “f”)或object.__getattribute__(C, “f”)。因此，函数通过对象或类来调用是等价的。

静态方法是没有引用self变量的方法。

例如，统计学的package可以包含存放实验数据的容器类。这个类提供了标准的方法，计算平均值、均值、中值和其他依赖数据的描述性统计。然而，可能有只是概念相关但不依赖数据的函数。例如，erf(x)是在统计工作中方便的转换程序，但是不直接依赖特定的数据集。可以通过对象或类来调用：s.erf(1.5) –> .9332或Sample.erf(1.5) –> .9332。

因为静态方法返回没有变化的原函数，所以示例调用就没有特别之处：

Python

>>> class E(object):
     def f(x):
          print(x)
     f = staticmethod(f)

>>> print(E.f(3))
3
>>> print(E().f(3))
3

使用Non-data Descriptor协议，staticmethod()的纯Python版本如下：

Python

class StaticMethod(object):
 "Emulate PyStaticMethod_Type() in Objects/funcobject.c"

 def __init__(self, f):
      self.f = f

 def __get__(self, obj, objtype=None):
      return self.f

不同于静态方法，类方法在调用函数之前在参数列表的前面加了类引用。无论其调用者是对象还是类结果是一致的：

Python

>>> class E(object):
     def f(klass, x):
          return klass.__name__, x
     f = classmethod(f)

>>> print(E.f(3))
('E', 3)
>>> print(E().f(3))
('E', 3)

当函数仅需要类引用并且不关心任何内部数据时，类方法是非常有用的。类方法的一个用途就是代替类构造函数来创建对象。在Python 2.3中，类方法dict.fromkeys()通过键值列表来创建新字典。等价的纯Python实现如下：

Python

class Dict(object):
    . . .
    def fromkeys(klass, iterable, value=None):
        "Emulate dict_fromkeys() in Objects/dictobject.c"
        d = klass()
        for key in iterable:
            d[key] = value
        return d
    fromkeys = classmethod(fromkeys)

现在，独立键名的新字典会像下面这样来构建：

Python

>>> Dict.fromkeys('abracadabra')
{'a': None, 'r': None, 'b': None, 'c': None, 'd': None}

使用Non-data Descriptor协议，classmethod()的纯Python版本如下：

Python

class ClassMethod(object):
     "Emulate PyClassMethod_Type() in Objects/funcobject.c"

     def __init__(self, f):
          self.f = f

     def __get__(self, obj, klass=None):
          if klass is None:
               klass = type(obj)
          def newfunc(*args):
               return self.f(klass, *args)
          return newfunc