3. 定义扩展类型：已分类主题

本章节目标是提供一个各种你可以实现的类型方法及其功能的简短介绍。

这是 C 类型 PyTypeObject 的定义，省略了只用于 调试构建 的字段：

  1. typedef struct _typeobject {
  2.     PyObject_VAR_HEAD
  3.     const char *tp_name; /* For printing, in format "<module>.<name>" */
  4.     Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */
  6.     /* Methods to implement standard operations */
  8.     destructor tp_dealloc;
  9.     Py_ssize_t tp_vectorcall_offset;
  10.     getattrfunc tp_getattr;
  11.     setattrfunc tp_setattr;
  12.     PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
  13.                                     or tp_reserved (Python 3) */
  14.     reprfunc tp_repr;
  16.     /* Method suites for standard classes */
  18.     PyNumberMethods *tp_as_number;
  19.     PySequenceMethods *tp_as_sequence;
  20.     PyMappingMethods *tp_as_mapping;
  22.     /* More standard operations (here for binary compatibility) */
  24.     hashfunc tp_hash;
  25.     ternaryfunc tp_call;
  26.     reprfunc tp_str;
  27.     getattrofunc tp_getattro;
  28.     setattrofunc tp_setattro;
  30.     /* Functions to access object as input/output buffer */
  31.     PyBufferProcs *tp_as_buffer;
  33.     /* Flags to define presence of optional/expanded features */
  34.     unsigned long tp_flags;
  36.     const char *tp_doc; /* Documentation string */
  38.     /* Assigned meaning in release 2.0 */
  39.     /* call function for all accessible objects */
  40.     traverseproc tp_traverse;
  42.     /* delete references to contained objects */
  43.     inquiry tp_clear;
  45.     /* Assigned meaning in release 2.1 */
  46.     /* rich comparisons */
  47.     richcmpfunc tp_richcompare;
  49.     /* weak reference enabler */
  50.     Py_ssize_t tp_weaklistoffset;
  52.     /* Iterators */
  53.     getiterfunc tp_iter;
  54.     iternextfunc tp_iternext;
  56.     /* Attribute descriptor and subclassing stuff */
  57.     struct PyMethodDef *tp_methods;
  58.     struct PyMemberDef *tp_members;
  59.     struct PyGetSetDef *tp_getset;
  60.     // Strong reference on a heap type, borrowed reference on a static type
  61.     struct _typeobject *tp_base;
  62.     PyObject *tp_dict;
  63.     descrgetfunc tp_descr_get;
  64.     descrsetfunc tp_descr_set;
  65.     Py_ssize_t tp_dictoffset;
  66.     initproc tp_init;
  67.     allocfunc tp_alloc;
  68.     newfunc tp_new;
  69.     freefunc tp_free; /* Low-level free-memory routine */
  70.     inquiry tp_is_gc; /* For PyObject_IS_GC */
  71.     PyObject *tp_bases;
  72.     PyObject *tp_mro; /* method resolution order */
  73.     PyObject *tp_cache;
  74.     PyObject *tp_subclasses;
  75.     PyObject *tp_weaklist;
  76.     destructor tp_del;
  78.     /* Type attribute cache version tag. Added in version 2.6 */
  79.     unsigned int tp_version_tag;
  81.     destructor tp_finalize;
  82.     vectorcallfunc tp_vectorcall;
  83. } PyTypeObject;

这里有 很多 方法。但是不要太担心，如果你要定义一个类型，通常只需要实现少量的方法。

正如你猜到的一样，我们正要一步一步详细介绍各种处理程序。因为有大量的历史包袱影响字段的排序，所以我们不会根据它们在结构体里定义的顺序讲解。通常非常容易找到一个包含你需要的字段的例子，然后改变值去适应你新的类型。

  1. const char *tp_name; /* For printing */

类型的名字 - 上一章提到过的，会出现在很多地方，几乎全部都是为了诊断目的。尝试选择一个好名字，对于诊断很有帮助。

  1. Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

这些字段告诉运行时在创造这个类型的新对象时需要分配多少内存。Python为了可变长度的结构（想下：字符串，元组）有些内置支持，这是 tp_itemsize 字段存在的原由。这部分稍后解释。

  1. const char *tp_doc;

这里你可以放置一段字符串（或者它的地址），当你想在Python脚本引用 obj.__doc__ 时返回这段文档字符串。

现在我们来看一下基本类型方法 - 大多数扩展类型将实现的方法。

3.1. 终结和内存释放

  1. destructor tp_dealloc;

当您的类型实例的引用计数减少为零并且Python解释器想要回收它时，将调用此函数。如果你的类型有内存可供释放或执行其他清理，你可以把它放在这里。 对象本身也需要在这里释放。 以下是此函数的示例：

  1. static void
  2. newdatatype_dealloc(newdatatypeobject *obj)
  3. {
  4.     free(obj->obj_UnderlyingDatatypePtr);
  5.     Py_TYPE(obj)->tp_free((PyObject *)obj);
  6. }

如果你的类型支持垃圾回收，则析构器应当在清理任何成员字段之前调用 PyObject_GC_UnTrack():

  1. static void
  2. newdatatype_dealloc(newdatatypeobject *obj)
  3. {
  4.     PyObject_GC_UnTrack(obj);
  5.     Py_CLEAR(obj->other_obj);
  6.     ...
  7.     Py_TYPE(obj)->tp_free((PyObject *)obj);
  8. }

一个重要的释放器函数实现要求是把所有未决异常放着不动。这很重要是因为释放器会被解释器频繁的调用，当栈异常退出时(而非正常返回)，不会有任何办法保护释放器看到一个异常尚未被设置。此事释放器的任何行为都会导致额外增加的Python代码来检查异常是否被设置。这可能导致解释器的误导性错误。正确的保护方法是，在任何不安全的操作前，保存未决异常，然后在其完成后恢复。者可以通过 PyErr_Fetch() 和 PyErr_Restore() 函数来实现:

  1. static void
  2. my_dealloc(PyObject *obj)
  3. {
  4.     MyObject *self = (MyObject *) obj;
  5.     PyObject *cbresult;
  7.     if (self->my_callback != NULL) {
  8.         PyObject *err_type, *err_value, *err_traceback;
  10.         /* This saves the current exception state */
  11.         PyErr_Fetch(&err_type, &err_value, &err_traceback);
  13.         cbresult = PyObject_CallNoArgs(self->my_callback);
  14.         if (cbresult == NULL)
  15.             PyErr_WriteUnraisable(self->my_callback);
  16.         else
  17.             Py_DECREF(cbresult);
  19.         /* This restores the saved exception state */
  20.         PyErr_Restore(err_type, err_value, err_traceback);
  22.         Py_DECREF(self->my_callback);
  23.     }
  24.     Py_TYPE(obj)->tp_free((PyObject*)self);
  25. }

备注

你能在释放器函数中安全执行的操作是有限的。 首先，如果你的类型支持垃圾回收 (使用 tp_traverse 和/或 tp_clear)，对象的部分成员可以在调用 tp_dealloc 时被清空或终结。 其次，在 tp_dealloc 中，你的对象将处于不稳定状态：它的引用计数等于零。 任何对非琐碎对象或 API 的调用 (如上面的示例所做的) 最终都可能会再次调用 tp_dealloc，导致双重释放并发生崩溃。

从 Python 3.4 开始，推荐不要在 tp_dealloc 放复杂的终结代码，而是使用新的 tp_finalize 类型方法。

参见

PEP 442 解释了新的终结方案。

3.2. 对象展示

在 Python 中，有两种方式可以生成对象的文本表示: repr() 函数和 str() 函数。 (print() 函数会直接调用 str()。) 这些处理程序都是可选的。

  1. reprfunc tp_repr;
  2. reprfunc tp_str;

tp_repr 处理程序应该返回一个字符串对象，其中包含调用它的实例的表示形式。 下面是一个简单的例子:

  1. static PyObject *
  2. newdatatype_repr(newdatatypeobject * obj)
  3. {
  4.     return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",
  5.                                 obj->obj_UnderlyingDatatypePtr->size);
  6. }

If no tp_repr handler is specified, the interpreter will supply a representation that uses the type’s tp_name and a uniquely identifying value for the object.

tp_str 处理句柄对于 str() 就如上述的 tp_repr 处理句柄对于 repr() 一样；也就是说，它会在当 Python 代码在你的对象的某个实例上调用 str() 时被调用。 它的实现与 tp_repr 函数非常相似，但其结果字符串是供人类查看的。 如果未指定 tp_str，则会使用 tp_repr 重句柄来代替。

下面是一个简单的例子:

  1. static PyObject *
  2. newdatatype_str(newdatatypeobject * obj)
  3. {
  4.     return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
  5.                                 obj->obj_UnderlyingDatatypePtr->size);
  6. }

3.3. 属性管理

对于每个可支持属性操作的对象，相应的类型必须提供用于控制属性获取方式的函数。 需要有一个能够检索属性的函数（如果定义了任何属性）还要有另一个函数负责设置属性（如果允许设置属性）。 移除属性是一种特殊情况，在此情况下要传给处理句柄的新值为 NULL。

Python supports two pairs of attribute handlers; a type that supports attributes only needs to implement the functions for one pair. The difference is that one pair takes the name of the attribute as a char*, while the other accepts a PyObject*. Each type can use whichever pair makes more sense for the implementation’s convenience.

  1. getattrfunc  tp_getattr;        /* char * version */
  2. setattrfunc  tp_setattr;
  3. /* ... */
  4. getattrofunc tp_getattro;       /* PyObject * version */
  5. setattrofunc tp_setattro;

If accessing attributes of an object is always a simple operation (this will be explained shortly), there are generic implementations which can be used to provide the PyObject* version of the attribute management functions. The actual need for type-specific attribute handlers almost completely disappeared starting with Python 2.2, though there are many examples which have not been updated to use some of the new generic mechanism that is available.

3.3.1. 泛型属性管理

大多数扩展类型只使用 简单 属性，那么，是什么让属性变得“简单”呢？只需要满足下面几个条件：

  1. 当调用 PyType_Ready() 时，必须知道属性的名称。

  2. 不需要特殊的处理来记录属性是否被查找或设置，也不需要根据值采取操作。

请注意，此列表不对属性的值、值的计算时间或相关数据的存储方式施加任何限制。

当 PyType_Ready() 被调用时，它会使用由类型对象所引用的三个表来创建要放置到类型对象的字典中的 descriptor。 每个描述器控制对实例对象的一个属性的访问。 每个表都是可选的；如果三个表全都为 NULL，则该类型的实例将只有从它们的基础类型继承来的属性，并且还应当让 tp_getattro 和 tp_setattro 字段保持为 NULL，以允许由基础类型处理这些属性。

表被声明为object::类型的三个字段:

  1. struct PyMethodDef *tp_methods;
  2. struct PyMemberDef *tp_members;
  3. struct PyGetSetDef *tp_getset;

如果 tp_methods 不为 NULL，则它必须指向一个由 PyMethodDef 结构体组成的数组。 表中的每个条目都是该结构体的一个实例:

  1. typedef struct PyMethodDef {
  2.     const char  *ml_name;       /* method name */
  3.     PyCFunction  ml_meth;       /* implementation function */
  4.     int          ml_flags;      /* flags */
  5.     const char  *ml_doc;        /* docstring */
  6. } PyMethodDef;

应当为该类型所提供的每个方法都定义一个条目；从基础类型继承来的方法不需要条目。 还需要在末尾加一个额外的条目；它是一个标记数组结束的哨兵条目。 该哨兵条目的 ml_name 字段必须为 NULL。

第二个表被用来定义要直接映射到实例中的数据的属性。 各种原始 C 类型均受到支持，并且访问方式可以为只读或读写。 表中的结构体被定义为:

  1. typedef struct PyMemberDef {
  2.     const char *name;
  3.     int         type;
  4.     int         offset;
  5.     int         flags;
  6.     const char *doc;
  7. } PyMemberDef;

对于表中的每个条目，将构建一个 descriptor 并添加到类型中使其能够从实例结构体中提取值。 type 字段应当包含在 structmember.h 头文件中定义的某个类型的代码；该值将被用来确定如何将 Python 值转换为 C 值或者反之。 flags 字段将被用来储存控制属性可以如何被访问的旗标。

以下标志常量定义在:file: ‘ structmember.h ‘;它们可以使用bitwise-OR组合。

常量

含意

READONLY

没有可写的

PYAUDITREAD

在读取之前发送一个 object.__getattr 审计事件。

在 3.10 版更改: RESTRICTED, READ_RESTRICTED 和 WRITE_RESTRICTED 已被弃用。 但是，READ_RESTRICTED 是 PY_AUDIT_READ 的一个别名，因此指定了 RESTRICTED 或 READ_RESTRICTED 的字段也会引发审计事件。

使用 tp_members 表来构建用于运行时的描述器还有一个有趣的优点是任何以这种方式定义的属性都可以简单地通过在表中提供文本来设置一个相关联的文档字符串。 一个应用程序可以使用自省 API 从类对象获取描述器，并使用其 __doc__ 属性来获取文档字符串。

与 tp_methods 表一样，需要有一个值为 NULL 的哨兵条目 name。

3.3.2. 类型专属的属性管理

For simplicity, only the char* version will be demonstrated here; the type of the name parameter is the only difference between the char* and PyObject* flavors of the interface. This example effectively does the same thing as the generic example above, but does not use the generic support added in Python 2.2. It explains how the handler functions are called, so that if you do need to extend their functionality, you’ll understand what needs to be done.

tp_getattr 处理句柄会在对象需要查找属性时被调用。 它被调用的情况与一个类的 __getattr__() 方法要被调用的情况相同。

例如：

  1. static PyObject *
  2. newdatatype_getattr(newdatatypeobject *obj, char *name)
  3. {
  4.     if (strcmp(name, "data") == 0)
  5.     {
  6.         return PyLong_FromLong(obj->data);
  7.     }
  9.     PyErr_Format(PyExc_AttributeError,
  10.                  "'%.50s' object has no attribute '%.400s'",
  11.                  tp->tp_name, name);
  12.     return NULL;
  13. }

tp_setattr 处理句柄会在要调用一个类实例的 __setattr__() 或 __delattr__() 方法时被调用。 当一个属性应当被删除时，第三个形参将为 NULL。 下面是一个简单地引发异常的例子；如果这确实是你想要的，则 tp_setattr 处理句柄应当被设为 NULL。

  1. static int
  2. newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
  3. {
  4.     PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);
  5.     return -1;
  6. }

3.4. 对象比较

  1. richcmpfunc tp_richcompare;

tp_richcompare 处理句柄会在需要进行比较时被调用。 它类似于 富比较方法，例如 __lt__()，并会被 PyObject_RichCompare() 和 PyObject_RichCompareBool() 所调用。

此函数被调用时将传入两个 Python 对象和运算符作为参数，其中运算符为 Py_EQ, Py_NE, Py_LE, Py_GE, Py_LT 或 Py_GT 之一。 它应当使用指定的运算符来比较两个对象并在比较操作成功时返回 Py_True 或 Py_False，如果比较操作未被实现并应尝试其他对象比较方法时则返回 Py_NotImplemented，或者如果设置了异常则返回 NULL。

下面是一个示例实现，该数据类型如果内部指针的大小相等就认为是相等的:

  1. static PyObject *
  2. newdatatype_richcmp(PyObject *obj1, PyObject *obj2, int op)
  3. {
  4.     PyObject *result;
  5.     int c, size1, size2;
  7.     /* code to make sure that both arguments are of type
  8.        newdatatype omitted */
  10.     size1 = obj1->obj_UnderlyingDatatypePtr->size;
  11.     size2 = obj2->obj_UnderlyingDatatypePtr->size;
  13.     switch (op) {
  14.     case Py_LT: c = size1 <  size2; break;
  15.     case Py_LE: c = size1 <= size2; break;
  16.     case Py_EQ: c = size1 == size2; break;
  17.     case Py_NE: c = size1 != size2; break;
  18.     case Py_GT: c = size1 >  size2; break;
  19.     case Py_GE: c = size1 >= size2; break;
  20.     }
  21.     result = c ? Py_True : Py_False;
  22.     Py_INCREF(result);
  23.     return result;
  24.  }

3.5. 抽象协议支持

Python 支持多种 抽象 ‘协议’；被提供来使用这些接口的专门接口说明请在 抽象对象层 中查看。

这些抽象接口很多都是在 Python 实现开发的早期被定义的。 特别地，数字、映射和序列协议从一开始就已经是 Python 的组成部分。 其他协议则是后来添加的。 对于依赖某些来自类型实现的处理句柄例程的协议来说，较旧的协议被定义为类型对象所引用的处理句柄的可选块。 对于较新的协议来说在主类型对象中还有额外的槽位，并带有一个预设旗标位来指明存在该槽位并应当由解释器来检查。 （此旗标位并不会指明槽位值非 NULL 的情况，可以设置该旗标来指明一个槽位的存在，但此本位仍可能保持未填充的状态。）

  1. PyNumberMethods   *tp_as_number;
  2. PySequenceMethods *tp_as_sequence;
  3. PyMappingMethods  *tp_as_mapping;

如果你希望你的对象的行为类似一个数字、序列或映射对象，那么你就要分别放置一个实现了 C 类型 PyNumberMethods, PySequenceMethods 或 PyMappingMethods, 的结构体的地址。 你要负责将适当的值填入这些结构体。 你可以在 Python 源代码发布版的 Objects 目录中找到这些对象各自的用法示例。

  1. hashfunc tp_hash;

如果你选择提供此函数，则它应当为你的数据类型的实例返回一个哈希数值。 下面是一个简单的示例:

  1. static Py_hash_t
  2. newdatatype_hash(newdatatypeobject *obj)
  3. {
  4.     Py_hash_t result;
  5.     result = obj->some_size + 32767 * obj->some_number;
  6.     if (result == -1)
  7.        result = -2;
  8.     return result;
  9. }

Py_hash_t 是一个在宽度取决于具体平台的有符号整数类型。 从 tp_hash 返回 -1 表示发生了错误，这就是为什么你应当注意避免在哈希运算成功时返回它，如上面所演示的。

  1. ternaryfunc tp_call;

此函数会在“调用”你的数据类型实例时被调用，举例来说，如果 obj1 是你的数据类型的实例而 Python 脚本包含了 obj1('hello')，则将发起调用 tp_call 处理句柄。

此函数接受三个参数:

  1. self 是作为调用目标的数据类型实例。 如果调用是 obj1('hello')，则 self 为 obj1。

  2. args 是包含调用参数的元组。 你可以使用 PyArg_ParseTuple() 来提取参数。

  3. kwds 是由传入的关键字参数组成的字典。 如果它不为 NULL 且你支持关键字参数，则可使用 PyArg_ParseTupleAndKeywords() 来提取参数。 如果你不想支持关键字参数而它为非 NULL 值，则会引发 TypeError 并附带一个提示不支持关键字参数的消息。

下面是一个演示性的 tp_call 实现:

  1. static PyObject *
  2. newdatatype_call(newdatatypeobject *self, PyObject *args, PyObject *kwds)
  3. {
  4.     PyObject *result;
  5.     const char *arg1;
  6.     const char *arg2;
  7.     const char *arg3;
  9.     if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
  10.         return NULL;
  11.     }
  12.     result = PyUnicode_FromFormat(
  13.         "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",
  14.         obj->obj_UnderlyingDatatypePtr->size,
  15.         arg1, arg2, arg3);
  16.     return result;
  17. }
  1. /* Iterators */
  2. getiterfunc tp_iter;
  3. iternextfunc tp_iternext;

这些函数提供了对迭代器协议的支持。 两个处理句柄都只接受一个形参，即它们被调用时所使用的实例，并返回一个新的引用。 当发生错误时，它们应当设置一个异常并返回 NULL。 tp_iter 对应于 Python __iter__() 方法，而 tp_iternext 对应于 Python __next__() 方法。

任何 iterable 对象都必须实现 tp_iter 处理句柄，该处理句柄必须返回一个 iterator 对象。 下面是与 Python 类所应用的同一个指导原则:

  • 对于可以支持多个独立迭代器的多项集（如列表和元组），则应当在每次调用 tp_iter 时创建并返回一个新的迭代器。

  • 只能被迭代一次的对象（通常是由于迭代操作的附带影响，例如文件对象）可以通过返回一个指向自身的新引用来实现 tp_iter — 并且为此还应当实现 tp_iternext 处理句柄。

任何 iterator 对象都应当同时实现 tp_iter 和 tp_iternext。 一个迭代器的 tp_iter 处理句柄应当返回一个指向该迭代器的新引用。 它的 tp_iternext 处理句柄应当返回一个指向迭代操作的下一个对象的新引用，如果还有下一个对象的话。 如果迭代已到达末尾，则 tp_iternext 可以返回 NULL 而不设置异常，或者也可以在返回 NULL 的基础上 额外 设置 StopIteration；避免异常可以产生更好的性能。 如果发生了实际的错误，则 tp_iternext 应当总是设置一个异常并返回 NULL。

3.6. 弱引用支持

One of the goals of Python 弱引用实现的目标之一是允许任意类型参与弱引用机制而不会在重视性能的对象（例如数字）上产生额外开销。

参见

weakref 模块的文档。

对于可弱引用的对象，扩展类型必须做两件事:

  1. Include a PyObject* field in the C object structure dedicated to the weak reference mechanism. The object’s constructor should leave it NULL (which is automatic when using the default tp_alloc).

  2. 将 tp_weaklistoffset 类型成员设置为 C 对象结构体中上述字段的偏移量，这样解释器就能知道如何访问和修改该字段。

具体来说，下面是一个微小的对象结构体如何被增强为具有所需的字段:

  1. typedef struct {
  2.     PyObject_HEAD
  3.     PyObject *weakreflist;  /* List of weak references */
  4. } TrivialObject;

And the corresponding member in the statically declared type object:

  1. static PyTypeObject TrivialType = {
  2.     PyVarObject_HEAD_INIT(NULL, 0)
  3.     /* ... other members omitted for brevity ... */
  4.     .tp_weaklistoffset = offsetof(TrivialObject, weakreflist),
  5. };

唯一的额外补充是如果字段不为 NULL 则 tp_dealloc 需要清除任何弱引用 (通过调用 PyObject_ClearWeakRefs())。:

  1. static void
  2. Trivial_dealloc(TrivialObject *self)
  3. {
  4.     /* Clear weakrefs first before calling any destructors */
  5.     if (self->weakreflist != NULL)
  6.         PyObject_ClearWeakRefs((PyObject *) self);
  7.     /* ... remainder of destruction code omitted for brevity ... */
  8.     Py_TYPE(self)->tp_free((PyObject *) self);
  9. }

3.7. 更多建议

为了学习如何为你的新数据类型实现任何特定方法，请获取 CPython 源代码。 进入 Objects 目录，然后在 C 源文件中搜索 tp_ 加上你想要的函数 (例如，tp_richcompare)。 你将找到你想要实现的函数的例子。

当你需要验证一个对象是否为你实现的类型的具体实例时，请使用 PyObject_TypeCheck() 函数。 它的一个用法示例如下:

  1. if (!PyObject_TypeCheck(some_object, &MyType)) {
  2.     PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
  3.     return NULL;
  4. }

参见

下载CPython源代码版本。

https://www.python.org/downloads/source/

GitHub上开发CPython源代码的CPython项目。

https://github.com/python/cpython