类型对象 — Python 文档

来自菜鸟教程
Python/docs/3.6/c-api/typeobj
跳转至：导航、​搜索

类型对象

也许 Python 对象系统最重要的结构之一是定义新类型的结构：PyTypeObject 结构。 可以使用 PyObject_*() 或 PyType_*() 函数中的任何一个来处理类型对象，但不会提供大多数 Python 应用程序感兴趣的东西。 这些对象是对象行为的基础，因此它们对解释器本身和任何实现新类型的扩展模块都非常重要。

与大多数标准类型相比，类型对象相当大。 大小的原因是每个类型对象都存储了大量的值，主要是 C 函数指针，每个指针都实现了该类型功能的一小部分。 本节将详细检查类型对象的字段。 这些字段将按照它们在结构中出现的顺序进行描述。

类型定义：一元函数、二进制函数、三元函数、查询、intargfunc、intintargfunc、intobjargproc、intintobjargproc、objobjargproc、析构函数、freefunc、printfunc、getattrfunc、getattrofunc、setattrfunc、setattrofunc、reprfunc、hashfunc

PyTypeObject 的结构定义可以在 Include/object.h 中找到。 为了方便参考，这里重复了在那里找到的定义： 

typedef struct _typeobject {
    PyObject_VAR_HEAD
    const char *tp_name; /* For printing, in format "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    printfunc tp_print;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                    or tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    unsigned long tp_flags;

    const char *tp_doc; /* Documentation string */

    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    Py_ssize_t tp_weaklistoffset;

    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6 */
    unsigned int tp_version_tag;

    destructor tp_finalize;

} PyTypeObject;

类型对象结构扩展了 PyVarObject 结构。 ob_size 字段用于动态类型（由 type_new() 创建，通常从类语句调用）。 注意 PyType_Type（元类型）初始化 tp_itemsize，这意味着它的实例（即 类型对象）必须有ob_size字段。

PyObject *PyObject._ob_next

PyObject *PyObject._ob_prev

这些字段仅在定义宏 Py_TRACE_REFS 时出现。 它们对 NULL 的初始化由 PyObject_HEAD_INIT 宏处理。 对于静态分配的对象，这些字段始终保持 NULL。 对于动态分配的对象，这两个字段用于将对象链接到堆上的 all 活动对象的双向链表中。 这可用于各种调试目的； 当前唯一的用途是在设置环境变量 PYTHONDUMPREFS 时打印在运行结束时仍处于活动状态的对象。

这些字段不会被子类型继承。

Py_ssize_t PyObject.ob_refcnt

这是类型对象的引用计数，由 PyObject_HEAD_INIT 宏初始化为 1。 请注意，对于静态分配的类型对象，该类型的实例（其 ob_type 指向该类型的对象）不会 不 算作引用。 但是对于动态分配的类型对象，实例 do 算作引用。

该字段不被子类型继承。

PyTypeObject *PyObject.ob_type

这是类型的类型，换句话说就是它的元类型。 它由 PyObject_HEAD_INIT 宏的参数初始化，其值通常应为 &PyType_Type。 但是，对于必须在 Windows 上（至少）可用的可动态加载的扩展模块，编译器会抱怨这不是有效的初始化程序。 因此，约定是将 NULL 传递给 PyObject_HEAD_INIT 宏，并在模块的初始化函数开始时显式初始化此字段，然后再执行任何其他操作。 这通常是这样完成的：

Foo_Type.ob_type = &PyType_Type;

这应该在创建该类型的任何实例之前完成。 PyType_Ready() 检查 ob_type 是否为 NULL，如果是，则将其初始化为基类的 ob_type 字段。 PyType_Ready() 如果该字段不为零，则不会更改该字段。

该字段由子类型继承。

Py_ssize_t PyVarObject.ob_size

对于静态分配的类型对象，这应该初始化为零。 对于动态分配的类型对象，该字段具有特殊的内在含义。

该字段不被子类型继承。

const char *PyTypeObject.tp_name

指向包含类型名称的以 NUL 结尾的字符串的指针。 对于可作为模块全局变量访问的类型，字符串应该是完整的模块名称，后跟一个点，后跟类型名称； 对于内置类型，它应该只是类型名称。 如果模块是包的子模块，则完整的包名称是完整模块名称的一部分。 例如，在包 P 中的子包 Q 中的模块 M 中定义的名为 T 的类型应该具有 tp_name 初始化程序 "P.Q.M.T"。

对于动态分配的类型对象，这应该只是类型名称，并且模块名称显式存储在类型字典中作为键 '__module__' 的值。

对于静态分配的类型对象，tp_name 字段应包含一个点。 最后一个点之前的所有内容都可以作为 __module__ 属性访问，最后一个点之后的所有内容都可以作为 __name__ 属性访问。

如果不存在点，则整个 tp_name 字段可作为 __name__ 属性访问，并且 __module__ 属性未定义（除非在字典中明确设置，如上面解释过）。 这意味着您的类型将无法腌制。 此外，它不会列在使用 pydoc 创建的模块文档中。

该字段不被子类型继承。

Py_ssize_t PyTypeObject.tp_basicsize

Py_ssize_t PyTypeObject.tp_itemsize

这些字段允许计算类型实例的大小（以字节为单位）。

有两种类型：具有固定长度实例的类型具有零 tp_itemsize 字段，具有可变长度实例的类型具有非零 tp_itemsize 字段。 对于具有固定长度实例的类型，所有实例都具有相同的大小，在 tp_basicsize 中给出。

对于变长实例类型，实例必须有ob_size字段，实例大小为tp_basicsize加N倍tp_itemsize，其中N为“物体的长度”。 N 的值通常存储在实例的 ob_size 字段中。 也有例外：例如，整数使用负数 ob_size 表示负数，而 N 则是 abs(ob_size)。 此外，实例布局中存在 ob_size 字段并不意味着实例结构是可变长度的（例如，列表类型的结构具有固定长度的实例，但这些实例具有有意义的 ob_size 字段）。

基本大小包括由宏 PyObject_HEAD 或 PyObject_VAR_HEAD（以用于声明实例结构体）声明的实例中的字段，而这又包括 _ob_prev和 _ob_next 字段（如果存在）。 这意味着获取 tp_basicsize 初始化程序的唯一正确方法是在用于声明实例布局的结构上使用 sizeof 运算符。 基本大小不包括 GC 头大小。

这些字段由子类型单独继承。 如果基类型具有非零 tp_itemsize，则将 tp_itemsize 设置为子类型中不同的非零值通常是不安全的（尽管这取决于基本类型）。

关于对齐的注意事项：如果变量项需要特定对齐，则应通过 tp_basicsize 的值来处理。 示例：假设一个类型实现了一个 double 数组。 tp_itemsize 是 sizeof(double)。 tp_basicsize 是 sizeof(double) 的倍数是程序员的责任（假设这是 double 的对齐要求）。

destructor PyTypeObject.tp_dealloc

指向实例析构函数的指针。 这个函数必须被定义，除非类型保证它的实例永远不会被释放（就像单例 None 和 Ellipsis 的情况）。

当新的引用计数为零时，析构函数由 Py_DECREF() 和 Py_XDECREF() 宏调用。 此时，实例仍然存在，但没有对它的引用。 析构函数应该释放实例拥有的所有引用，释放实例拥有的所有内存缓冲区（使用与用于分配缓冲区的分配函数对应的释放函数），最后（作为它的最后一个动作）调用类型的 [X270X ]tp_free 函数。 如果类型不是子类型化的（没有设置 Py_TPFLAGS_BASETYPE 标志位），则允许直接调用对象释放器而不是通过 tp_free。 对象释放器应该是用来分配实例的； 这通常是 PyObject_Del() 如果实例是使用 PyObject_New() 或 PyObject_VarNew() 分配的，或者 PyObject_GC_Del() 如果实例已分配使用 PyObject_GC_New() 或 PyObject_GC_NewVar()。

该字段由子类型继承。

printfunc PyTypeObject.tp_print
保留插槽，以前用于 Python 2.x 中的打印格式。
getattrfunc PyTypeObject.tp_getattr

指向 get-attribute-string 函数的可选指针。

此字段已弃用。 当它被定义时，它应该指向一个与tp_getattro函数作用相同的函数，但使用C字符串而不是Python字符串对象来给出属性名称。 签名是

PyObject * tp_getattr(PyObject *o, char *attr_name);

该字段与 tp_getattro 一起被子类型继承：当子类型的 tp_gettr] 和 tp_gettr tp_getattro 都是 NULL。

setattrfunc PyTypeObject.tp_setattr

指向用于设置和删除属性的函数的可选指针。

此字段已弃用。 定义时，它应该指向一个与 tp_setattro 函数作用相同的函数，但采用 C 字符串而不是 Python 字符串对象来给出属性名称。 签名是

PyObject * tp_setattr(PyObject *o, char *attr_name, PyObject *v);

v 参数设置为 NULL 以删除属性。 该字段由子类型与 tp_setattro 一起继承：当子类型的 tp193X] 和 tp_setattr tp_setattro 都是 NULL。

PyAsyncMethods *tp_as_async

指向附加结构的指针，该结构包含仅与在 C 级实现 awaitable 和 asynchronous iterator 协议的对象相关的字段。 有关详细信息，请参阅 异步对象结构 。

3.5 版新功能： 以前称为 tp_compare 和 tp_reserved。

reprfunc PyTypeObject.tp_repr

指向实现内置函数 repr() 的函数的可选指针。

签名与 PyObject_Repr() 相同； 它必须返回一个字符串或一个 Unicode 对象。 理想情况下，这个函数应该返回一个字符串，当传递给 eval() 时，给定合适的环境，返回一个具有相同值的对象。 如果这不可行，它应该返回一个以 '<' 开头并以 '>' 结尾的字符串，从中可以推导出对象的类型和值。

如果未设置此字段，则返回 <%s object at %p> 形式的字符串，其中 %s 替换为类型名称，%p 替换为对象的内存地址。

该字段由子类型继承。

PyNumberMethods *tp_as_number

指向包含仅与实现数字协议的对象相关的字段的附加结构的指针。 这些字段记录在 数字对象结构 中。

tp_as_number 字段不是继承的，但是包含的字段是单独继承的。

PySequenceMethods *tp_as_sequence

指向包含仅与实现序列协议的对象相关的字段的附加结构的指针。 这些字段记录在 序列对象结构 中。

tp_as_sequence 字段不是继承的，但是包含的字段是单独继承的。

PyMappingMethods *tp_as_mapping

指向包含仅与实现映射协议的对象相关的字段的附加结构的指针。 这些字段记录在 映射对象结构 中。

tp_as_mapping 字段不是继承的，但是包含的字段是单独继承的。

hashfunc PyTypeObject.tp_hash

指向实现内置函数 hash() 的函数的可选指针。

签名与 PyObject_Hash() 相同； 它必须返回 Py_hash_t 类型的值。 值 -1 不应作为正常返回值返回； 当哈希值计算过程中发生错误时，函数应设置异常并返回-1。

可以将此字段显式设置为 PyObject_HashNotImplemented() 以阻止从父类型继承哈希方法。 这被解释为 Python 级别的 __hash__ = None 等价物，导致 isinstance(o, collections.Hashable) 正确返回 False。 请注意，反过来也是如此 - 在 Python 级别的类上设置 __hash__ = None 将导致 tp_hash 插槽设置为 PyObject_HashNotImplemented()。

如果未设置此字段，则尝试获取对象的散列会引发 TypeError。

该字段与 tp_richcompare 一起被子类型继承：当子类型的 tp_richcompare 和 tp_hashtp_richcomparetp_richcompare ]tp_hash 都是 NULL。

ternaryfunc PyTypeObject.tp_call

指向实现调用对象的函数的可选指针。 如果对象不可调用，这应该是 NULL。 签名与 PyObject_Call() 相同。

该字段由子类型继承。

reprfunc PyTypeObject.tp_str

指向实现内置操作 str() 的函数的可选指针。 （注意 str 现在是一个类型，而 str() 调用该类型的构造函数。 此构造函数调用 PyObject_Str() 来完成实际工作，而 PyObject_Str() 将调用此处理程序。）

签名与 PyObject_Str() 相同； 它必须返回一个字符串或一个 Unicode 对象。 此函数应返回对象的“友好”字符串表示，因为这是 print() 函数将使用的表示。

如果未设置此字段，则调用 PyObject_Repr() 以返回字符串表示形式。

该字段由子类型继承。

getattrofunc PyTypeObject.tp_getattro

指向 get-attribute 函数的可选指针。

签名与 PyObject_GetAttr() 相同。 通常将此字段设置为 PyObject_GenericGetAttr() 很方便，它实现了查找对象属性的正常方式。

该字段由子类型与 tp_getattr 一起继承：当子类型的 tp_getattr] 和 tp_gettr tp_getattro 都是 NULL。

setattrofunc PyTypeObject.tp_setattro

指向用于设置和删除属性的函数的可选指针。

签名与 PyObject_SetAttr() 相同，但必须支持将 v 设置为 NULL 以删除属性。 通常将此字段设置为 PyObject_GenericSetAttr() 会很方便，它实现了设置对象属性的正常方式。

该字段与 tp_setattr 一起被子类型继承：当子类型的 tp192X] 和 tp_setattr 从其基本类型继承 tp_setattr tp_setattro 都是 NULL。

PyBufferProcs *PyTypeObject.tp_as_buffer

指向包含仅与实现缓冲区接口的对象相关的字段的附加结构的指针。 这些字段记录在 缓冲区对象结构 中。

tp_as_buffer 字段不是继承的，但是包含的字段是单独继承的。

unsigned long PyTypeObject.tp_flags

该字段是各种标志的位掩码。 某些标志表示某些情况下的变体语义； 其他用于指示类型对象中的某些字段（或通过 tp_as_number、tp_as_sequence、tp_as_mapping 和 tp_as_buffer 引用的扩展结构）历史上并不总是存在的都是有效的； 如果这样的标志位清除，则不得访问它所保护的类型字段，并且必须将其视为零或 NULL 值。

这个字段的继承很复杂。 大多数标志位是单独继承的，即 如果基类型设置了标志位，则子类型继承该标志位。 如果扩展结构是继承的，则与扩展结构有关的标志位是严格继承的，即 标志位的基类型值与指向扩展结构的指针一起复制到子类型中。 Py_TPFLAGS_HAVE_GC 标志位与 tp_traverse 和 tp_clear 字段一起继承，即 如果子类型中的 Py_TPFLAGS_HAVE_GC 标志位清除，并且子类型中的 tp_traverse 和 tp_clear 字段存在并且具有 NULL 值。

当前定义了以下位掩码； 这些可以使用 | 运算符进行或运算以形成 tp_flags 字段的值。 宏 PyType_HasFeature() 接受类型和标志值 tp 和 f，并检查 tp->tp_flags & f 是否非零。

Py_TPFLAGS_HEAPTYPE

当类型对象本身在堆上分配时，该位被设置。 在这种情况下，其实例的 ob_type 字段被认为是对该类型的引用，并且在创建新实例时对类型对象进行 INCREF 处理，在实例销毁时进行 DECREF 处理（这不会不适用于子类型的实例；只有实例的 ob_type 引用的类型被 INCREF'ed 或 DECREF'ed）。

Py_TPFLAGS_BASETYPE

当该类型可以用作另一种类型的基类型时，该位被设置。 如果此位清零，则该类型不能进行子类型化（类似于 Java 中的“final”类）。

Py_TPFLAGS_READY

当类型对象已被 PyType_Ready() 完全初始化时，该位被设置。

Py_TPFLAGS_READYING

该位在 PyType_Ready() 初始化类型对象的过程中设置。

Py_TPFLAGS_HAVE_GC

当对象支持垃圾收集时设置该位。 如果设置了该位，则必须使用 PyObject_GC_New() 创建实例并使用 PyObject_GC_Del() 销毁实例。 更多信息请参见 支持循环垃圾收集 部分。 该位还暗示与 GC 相关的字段 tp_traverse 和 tp_clear 存在于类型对象中。

Py_TPFLAGS_DEFAULT

这是与类型对象及其扩展结构中某些字段的存在有关的所有位的位掩码。 目前，它包括以下位：Py_TPFLAGS_HAVE_STACKLESS_EXTENSION、Py_TPFLAGS_HAVE_VERSION_TAG。

Py_TPFLAGS_LONG_SUBCLASS
Py_TPFLAGS_LIST_SUBCLASS
Py_TPFLAGS_TUPLE_SUBCLASS
Py_TPFLAGS_BYTES_SUBCLASS
Py_TPFLAGS_UNICODE_SUBCLASS
Py_TPFLAGS_DICT_SUBCLASS
Py_TPFLAGS_BASE_EXC_SUBCLASS
Py_TPFLAGS_TYPE_SUBCLASS

这些标志被 PyLong_Check() 等函数用来快速判断一个类型是否是内置类型的子类； 此类特定检查比一般检查更快，例如 PyObject_IsInstance()。 从内置函数继承的自定义类型应该适当地设置它们的 tp_flags，否则与这些类型交互的代码将根据使用的检查类型而不同。

Py_TPFLAGS_HAVE_FINALIZE

当类型结构中存在 tp_finalize 插槽时，会设置该位。

3.4 版中的新功能。

const char *PyTypeObject.tp_doc

一个指向以 NUL 结尾的 C 字符串的可选指针，给出此类型对象的文档字符串。 这作为类型和类型实例的 __doc__ 属性公开。

该字段是 不是由子类型继承的 。

traverseproc PyTypeObject.tp_traverse

指向垃圾收集器遍历函数的可选指针。 这仅在设置了 Py_TPFLAGS_HAVE_GC 标志位时使用。 有关 Python 垃圾收集方案的更多信息，请参见 支持循环垃圾收集 部分。

垃圾收集器使用 tp_traverse 指针来检测引用周期。 tp_traverse 函数的典型实现简单地调用 Py_VISIT() 对每个实例的成员是 Python 对象。 例如，这是来自 _thread 扩展模块的函数 local_traverse()：

static int
local_traverse(localobject *self, visitproc visit, void *arg)
{
    Py_VISIT(self->args);
    Py_VISIT(self->kw);
    Py_VISIT(self->dict);
    return 0;
}

请注意， Py_VISIT() 仅在那些可以参与引用循环的成员上调用。 虽然也有 self->key 成员，但它只能是 NULL 或 Python 字符串，因此不能成为引用循环的一部分。

另一方面，即使您知道成员永远不会成为循环的一部分，作为调试帮助，您可能仍然希望访问它，就像 gc 模块的 get_referents()函数将包括它。

请注意， Py_VISIT() 需要 visit 和 arg 参数到 local_traverse() 以具有这些特定名称； 不要随便命名它们。

该字段与tp_clear和Py_TPFLAGS_HAVE_GC标志位一起被子类型继承：标志位，tp_traverse和tp_clear]都是继承的如果它们在子类型中都为零，则从基类型开始。

inquiry PyTypeObject.tp_clear

指向垃圾收集器清除函数的可选指针。 这仅在设置了 Py_TPFLAGS_HAVE_GC 标志位时使用。

tp_clear成员函数用于在垃圾收集器检测到的循环垃圾中中断引用循环。 综上所述，系统中的所有 tp_clear 函数必须结合起来才能打破所有参考循环。 这是微妙的，如果有任何疑问，请提供 tp_clear 函数。 例如，元组类型没有实现 tp_clear 函数，因为可以证明没有引用循环可以完全由元组组成。 因此，其他类型的 tp_clear 函数必须足以中断任何包含元组的循环。 这不是很明显，而且很少有充分的理由避免实现 tp_clear。

tp_clear 的实现应该删除实例对其可能是 Python 对象的成员的引用，并将其指向这些成员的指针设置为 NULL，如下例所示：

static int
local_clear(localobject *self)
{
    Py_CLEAR(self->key);
    Py_CLEAR(self->args);
    Py_CLEAR(self->kw);
    Py_CLEAR(self->dict);
    return 0;
}

应该使用 Py_CLEAR() 宏，因为清除引用是微妙的：在指向所包含对象的指针设置为 NULL 之前，不得减少对所包含对象的引用。 这是因为减少引用计数可能会导致包含的对象变成垃圾，触发一系列回收活动，其中可能包括调用任意 Python 代码（由于与包含的对象关联的终结器或弱引用回调）。 如果这样的代码有可能再次引用 self，那么此时指向所包含对象的指针是 NULL 很重要，这样 self 就知道所包含的对象不能再使用对象。 Py_CLEAR() 宏以安全的顺序执行操作。

因为 tp_clear 函数的目标是打破引用循环，所以没有必要清除包含的对象，如 Python 字符串或 Python 整数，它们不能参与引用循环。 另一方面，清除所有包含的 Python 对象可能会很方便，并编写类型的 tp_dealloc 函数来调用 tp_clear。

有关 Python 垃圾收集方案的更多信息，请参见 支持循环垃圾收集 部分。

该字段与tp_traverse和Py_TPFLAGS_HAVE_GC标志位一起被子类型继承：标志位，tp_traverse和tp_clear][X16]都是继承的如果它们在子类型中都为零，则从基类型开始。

richcmpfunc PyTypeObject.tp_richcompare

指向富比较函数的可选指针，其签名为 PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)。 第一个参数保证是由 PyTypeObject 定义的类型的实例。

该函数应返回比较的结果（通常为 Py_True 或 Py_False）。 如果比较未定义，则必须返回 Py_NotImplemented，如果发生另一个错误，则必须返回 NULL 并设置异常条件。

笔记

如果你想实现一个只有有限的一组比较有意义的类型（例如 == 和 !=，但不是 < 和朋友），在丰富的比较函数中直接引发 TypeError。

该字段与tp_hash一起被子类型继承：当子类型的tp_richcompare[X1617X]和[X1617X]时，子类型继承tp_richcompare和tp_hash X190X] 都是 NULL。

以下常量被定义为用作 tp_richcompare 和 PyObject_RichCompare() 的第三个参数：

持续的

比较

Py_LT

<

Py_LE

<=

Py_EQ

==

Py_NE

!=

Py_GT

>

Py_GE

>=

Py_ssize_t PyTypeObject.tp_weaklistoffset

如果该类型的实例是弱引用的，则该字段大于零并包含弱引用列表头的实例结构中的偏移量（忽略 GC 头，如果存在）； 该偏移量由 PyObject_ClearWeakRefs() 和 PyWeakref_*() 函数使用。 实例结构需要包含一个类型为 PyObject* 的字段，该字段被初始化为 NULL。

不要将此字段与 tp_weaklist 混淆； 这是对类型对象本身的弱引用的列表头。

此字段由子类型继承，但请参阅下面列出的规则。 一个子类型可以覆盖这个偏移量； 这意味着子类型使用与基类型不同的弱引用列表头。 由于总是通过 tp_weaklistoffset 找到列表头，所以这应该不是问题。

当 class 语句定义的类型没有 __slots__ 声明，并且其基本类型都不是弱引用时，通过向实例布局添加弱引用列表头槽并设置 tp_weaklistoffset 该插槽的偏移量。

当类型的 __slots__ 声明包含名为 __weakref__ 的插槽时，该插槽成为该类型实例的弱引用列表头，并且该插槽的偏移量存储在该类型的 tp_weaklistoffset 中]。

当类型的 __slots__ 声明不包含名为 __weakref__ 的插槽时，该类型从其基类型继承其 tp_weaklistoffset。

getiterfunc PyTypeObject.tp_iter

指向返回对象迭代器的函数的可选指针。 它的存在通常表明这种类型的实例是可迭代的（尽管序列可能在没有这个函数的情况下是可迭代的）。

此函数与 PyObject_GetIter() 具有相同的签名。

该字段由子类型继承。

iternextfunc PyTypeObject.tp_iternext

指向返回迭代器中下一项的函数的可选指针。 当迭代器耗尽时，必须返回NULL； StopIteration 异常可能会也可能不会被设置。 当另一个错误发生时，它也必须返回 NULL。 它的存在表明这种类型的实例是迭代器。

迭代器类型还应该定义 tp_iter 函数，并且该函数应该返回迭代器实例本身（不是新的迭代器实例）。

此函数与 PyIter_Next() 具有相同的签名。

该字段由子类型继承。

struct PyMethodDef *PyTypeObject.tp_methods

一个指向静态 NULL 终止的 PyMethodDef 结构数组的可选指针，声明这种类型的常规方法。

对于数组中的每个条目，都会将一个条目添加到包含方法描述符的类型字典（参见下面的 tp_dict）。

该字段不由子类型继承（方法通过不同的机制继承）。

struct PyMemberDef *PyTypeObject.tp_members

指向静态 NULL 终止的 PyMemberDef 结构数组的可选指针，声明此类型实例的常规数据成员（字段或槽）。

对于数组中的每个条目，都会将一个条目添加到包含成员描述符的类型字典（参见下面的 tp_dict）。

该字段不被子类型继承（成员通过不同的机制继承）。

struct PyGetSetDef *PyTypeObject.tp_getset

一个指向静态 NULL 终止的 PyGetSetDef 结构数组的可选指针，声明此类型实例的计算属性。

对于数组中的每个条目，都会将一个条目添加到包含 getset 描述符的类型字典（参见下面的 tp_dict）。

该字段不由子类型继承（计算的属性通过不同的机制继承）。

PyTypeObject *PyTypeObject.tp_base

指向从其继承类型属性的基类型的可选指针。 在这个级别，只支持单继承； 多重继承需要通过调用元类型动态创建类型对象。

该字段不由子类型继承（显然），但它默认为 &PyBaseObject_Type（Python 程序员将其称为类型 object）。

PyObject *PyTypeObject.tp_dict

类型的字典由 PyType_Ready() 存储在这里。

在调用 PyType_Ready 之前，该字段通常应初始化为 NULL； 它也可以被初始化为一个包含该类型初始属性的字典。 一旦 PyType_Ready() 初始化了类型，只有当它们不对应于重载操作（如 __add__()）时，类型的额外属性才可以添加到此字典中。

这个字段不被子类型继承（尽管这里定义的属性是通过不同的机制继承的）。

警告

在字典 C-API 上使用 PyDict_SetItem() 或以其他方式修改 tp_dict 是不安全的。

descrgetfunc PyTypeObject.tp_descr_get

指向“描述符获取”函数的可选指针。

函数签名是

PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);

该字段由子类型继承。

descrsetfunc PyTypeObject.tp_descr_set

用于设置和删除描述符值的函数的可选指针。

函数签名是

int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);

value 参数设置为 NULL 以删除该值。 该字段由子类型继承。

Py_ssize_t PyTypeObject.tp_dictoffset

如果这个类型的实例有一个包含实例变量的字典，这个字段是非零的，并且包含实例变量字典类型的实例中的偏移量； 此偏移量由 PyObject_GenericGetAttr() 使用。

不要将此字段与 tp_dict 混淆； 那是类型对象本身的属性字典。

如果该字段的值大于零，则指定从实例结构开始的偏移量。 如果该值小于零，则指定与实例结构的 end 的偏移量。 使用负偏移量更昂贵，并且仅应在实例结构包含可变长度部分时使用。 例如，这用于将实例变量字典添加到 str 或 tuple 的子类型。 请注意，tp_basicsize 字段应考虑在这种情况下添加到末尾的字典，即使该字典未包含在基本对象布局中。 在指针大小为 4 字节的系统上，tp_dictoffset 应设置为 -4 以指示字典位于结构的最后。

实例中的实际字典偏移量可以从负 tp_dictoffset 计算如下：

dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
if dictoffset is not aligned on sizeof(void*):
    round up to sizeof(void*)

其中 tp_basicsize、tp_itemsize 和 tp_dictoffset 取自类型对象，ob_size 取自实例。 取绝对值是因为 ints 使用 ob_size 的符号来存储数字的符号。 （从来不需要你自己做这个计算；它是由 _PyObject_GetDictPtr() 为你完成的。）

此字段由子类型继承，但请参阅下面列出的规则。 一个子类型可以覆盖这个偏移量； 这意味着子类型实例将字典存储在与基类型不同的偏移量处。 由于字典总是通过 tp_dictoffset 找到，所以这应该不是问题。

当 class 语句定义的类型没有 __slots__ 声明，并且其基本类型都没有实例变量字典时，会在实例布局中添加一个字典槽，并且 tp_dictoffset 是设置为该插槽的偏移量。

当类语句定义的类型具有 __slots__ 声明时，该类型从其基类型继承其 tp_dictoffset。

（在 __slots__ 声明中添加一个名为 __dict__ 的插槽没有预期的效果，只会引起混乱。 也许这应该像 __weakref__ 一样作为功能添加。）

initproc PyTypeObject.tp_init

指向实例初始化函数的可选指针。

这个函数对应类的__init__()方法。 和 __init__() 一样，可以不调用 __init__() 来创建实例，并且可以通过再次调用其 __init__() 方法来重新初始化实例。

函数签名是

int tp_init(PyObject *self, PyObject *args, PyObject *kwds)

self 参数是要初始化的实例； args 和 kwds 参数表示调用 __init__() 的位置和关键字参数。

tp_init 函数，如果不是 NULL，则在通过调用其类型正常创建实例时，在类型的 tp_new 函数返回了类型。 如果 tp_new 函数返回某个其他类型的实例，该实例不是原始类型的子类型，则不会调用 tp_init 函数； 如果 tp_new 返回原始类型的子类型的实例，则调用子类型的 tp_init。

该字段由子类型继承。

allocfunc PyTypeObject.tp_alloc

指向实例分配函数的可选指针。

函数签名是

PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)

该函数的目的是将内存分配与内存初始化分开。 它应该返回一个指向实例足够长度的内存块的指针，适当对齐并初始化为零，但 ob_refcnt 设置为 1 和 ob_type 设置为类型参数。 如果类型的 tp_itemsize 非零，则对象的 ob_size 字段应初始化为 nitems，分配的内存块长度应为 tp_basicsize + nitems*tp_itemsize ]，向上取整为 sizeof(void*) 的倍数； 否则，不使用 nitems，块的长度应为 tp_basicsize。

不要使用这个函数来做任何其他的实例初始化，甚至不要分配额外的内存； 这应该由 tp_new 完成。

该字段由静态子类型继承，但不由动态子类型（由类语句创建的子类型）继承； 在后者中，此字段始终设置为 PyType_GenericAlloc()，以强制执行标准堆分配策略。 这也是静态定义类型的推荐值。

newfunc PyTypeObject.tp_new

指向实例创建函数的可选指针。

如果该函数为 NULL 特定类型，则不能调用该类型来创建新实例； 大概还有其他一些方法来创建实例，比如工厂函数。

函数签名是

PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)

subtype 参数是正在创建的对象的类型； args 和 kwds 参数表示对类型调用的位置和关键字参数。 请注意，子类型不必等于调用其 tp_new 函数的类型； 它可能是该类型的子类型（但不是不相关的类型）。

tp_new 函数应该调用 subtype->tp_alloc(subtype, nitems) 为对象分配空间，然后只做绝对必要的进一步初始化。 可以安全地忽略或重复的初始化应该放在 tp_init 处理程序中。 一个好的经验法则是，对于不可变类型，所有初始化都应该在 tp_new 中进行，而对于可变类型，大多数初始化应该推迟到 tp_init。

该字段由子类型继承，除非它不被 tp_base 为 NULL 或 &PyBaseObject_Type 的静态类型继承。

destructor PyTypeObject.tp_free

指向实例释放函数的可选指针。 它的签名是freefunc：

void tp_free(void *)

与此签名兼容的初始化程序是 PyObject_Free()。

该字段由静态子类型继承，但不由动态子类型（由类语句创建的子类型）继承； 在后者中，该字段设置为适合匹配 PyType_GenericAlloc() 和 Py_TPFLAGS_HAVE_GC 标志位的值的解除分配器。

inquiry PyTypeObject.tp_is_gc

指向垃圾收集器调用的函数的可选指针。

垃圾收集器需要知道特定对象是否可收集。 通常，查看对象类型的 tp_flags 字段，并检查 Py_TPFLAGS_HAVE_GC 标志位就足够了。 但是有些类型混合了静态和动态分配的实例，并且静态分配的实例是不可收集的。 这些类型应该定义这个函数； 它应该为可收集实例返回 1，对于不可收集实例返回 0。 签名是

int tp_is_gc(PyObject *self)

（唯一的例子是类型本身。 元类型 PyType_Type 定义了这个函数来区分静态和动态分配的类型。）

该字段由子类型继承。

PyObject *PyTypeObject.tp_bases

基本类型的元组。

这是为 class 语句创建的类型设置的。 对于静态定义的类型，它应该是 NULL。

该字段不是继承的。

PyObject *PyTypeObject.tp_mro

包含扩展的基类型集的元组，从类型本身开始，以 object 结束，按方法解析顺序。

该字段不是继承的； 它是由 PyType_Ready() 新鲜计算的。

destructor PyTypeObject.tp_finalize

指向实例终结函数的可选指针。 它的签名是destructor：

void tp_finalize(PyObject *)

如果设置了 tp_finalize，解释器在完成实例时调用它一次。 它从垃圾收集器（如果实例是隔离引用循环的一部分）或在对象被释放之前调用。 无论哪种方式，它都保证在尝试中断引用循环之前被调用，确保它找到处于正常状态的对象。

tp_finalize 不应改变当前异常状态； 因此，编写非平凡终结器的推荐方法是：

static void
local_finalize(PyObject *self)
{
    PyObject *error_type, *error_value, *error_traceback;

    /* Save the current exception, if any. */
    PyErr_Fetch(&error_type, &error_value, &error_traceback);

    /* ... */

    /* Restore the saved exception. */
    PyErr_Restore(error_type, error_value, error_traceback);
}

要考虑此字段（即使通过继承），您还必须设置 Py_TPFLAGS_HAVE_FINALIZE 标志位。

该字段由子类型继承。

3.4 版中的新功能。

也可以看看

“安全对象终结”（PEP 442）

PyObject *PyTypeObject.tp_cache
没用过。 不继承。 仅供内部使用。
PyObject *PyTypeObject.tp_subclasses
对子类的弱引用列表。 不继承。 仅供内部使用。
PyObject *PyTypeObject.tp_weaklist
弱引用列表头，用于对该类型对象的弱引用。 不继承。 仅供内部使用。

其余字段仅在定义了功能测试宏 COUNT_ALLOCS 时才定义，并且仅供内部使用。 为了完整起见，它们被记录在此处。 这些字段都不是由子类型继承的。

Py_ssize_t PyTypeObject.tp_allocs
分配数量。
Py_ssize_t PyTypeObject.tp_frees
免费次数。
Py_ssize_t PyTypeObject.tp_maxalloc
最大同时分配的对象。
PyTypeObject *PyTypeObject.tp_next
指向具有非零 tp_allocs 字段的下一个类型对象的指针。

另外，请注意，在垃圾回收的 Python 中，可以从任何 Python 线程调用 tp_dealloc，而不仅仅是创建对象的线程（如果对象成为 refcount 循环的一部分，则该循环可能会被任何线）。 这对于 Python API 调用来说不是问题，因为调用 tp_dealloc 的线程将拥有全局解释器锁 (GIL)。 但是，如果被销毁的对象又从其他 C 或 C++ 库中销毁对象，则应注意确保在调用 tp_dealloc 的线程上销毁这些对象不会违反库的任何假设。


数字对象结构

type PyNumberMethods

该结构包含指向对象用来实现数字协议的函数的指针。 每个函数都由 Number Protocol 部分中记录的类似名称的函数使用。

这是结构定义：

typedef struct {
     binaryfunc nb_add;
     binaryfunc nb_subtract;
     binaryfunc nb_multiply;
     binaryfunc nb_remainder;
     binaryfunc nb_divmod;
     ternaryfunc nb_power;
     unaryfunc nb_negative;
     unaryfunc nb_positive;
     unaryfunc nb_absolute;
     inquiry nb_bool;
     unaryfunc nb_invert;
     binaryfunc nb_lshift;
     binaryfunc nb_rshift;
     binaryfunc nb_and;
     binaryfunc nb_xor;
     binaryfunc nb_or;
     unaryfunc nb_int;
     void *nb_reserved;
     unaryfunc nb_float;

     binaryfunc nb_inplace_add;
     binaryfunc nb_inplace_subtract;
     binaryfunc nb_inplace_multiply;
     binaryfunc nb_inplace_remainder;
     ternaryfunc nb_inplace_power;
     binaryfunc nb_inplace_lshift;
     binaryfunc nb_inplace_rshift;
     binaryfunc nb_inplace_and;
     binaryfunc nb_inplace_xor;
     binaryfunc nb_inplace_or;

     binaryfunc nb_floor_divide;
     binaryfunc nb_true_divide;
     binaryfunc nb_inplace_floor_divide;
     binaryfunc nb_inplace_true_divide;

     unaryfunc nb_index;

     binaryfunc nb_matrix_multiply;
     binaryfunc nb_inplace_matrix_multiply;
} PyNumberMethods;

笔记

二元和三元函数必须检查其所有操作数的类型，并实现必要的转换（至少一个操作数是定义类型的实例）。 如果没有为给定的操作数定义操作，二元和三元函数必须返回 Py_NotImplemented，如果发生另一个错误，它们必须返回 NULL 并设置异常。

笔记

nb_reserved 字段应始终为 NULL。 它以前称为 nb_long，并在 Python 3.0.1 中重命名。


映射对象结构

type PyMappingMethods
该结构包含指向对象用来实现映射协议的函数的指针。 它有三个成员：
lenfunc PyMappingMethods.mp_length
该函数由 PyMapping_Size() 和 PyObject_Size() 使用，并且具有相同的签名。 如果对象没有定义的长度，这个槽可以设置为 NULL。
binaryfunc PyMappingMethods.mp_subscript
该函数由 PyObject_GetItem() 和 PySequence_GetSlice() 使用，与 PyObject_GetItem() 具有相同的签名。 PyMapping_Check()函数返回1时必须填入这个槽，否则可以是NULL。
objobjargproc PyMappingMethods.mp_ass_subscript
该函数由 PyObject_SetItem()、PyObject_DelItem()、PyObject_SetSlice() 和 PyObject_DelSlice() 使用。 它与 PyObject_SetItem() 具有相同的签名，但 v 也可以设置为 NULL 以删除项目。 如果此槽为NULL，则对象不支持项的赋值和删除。


序列对象结构

type PySequenceMethods
该结构包含指向对象用来实现序列协议的函数的指针。
lenfunc PySequenceMethods.sq_length
该函数由 PySequence_Size() 和 PyObject_Size() 使用，并且具有相同的签名。 它还用于通过 sq_item 和 sq_ass_item 槽处理负索引。
binaryfunc PySequenceMethods.sq_concat
该函数由 PySequence_Concat() 使用并且具有相同的签名。 在通过 nb_add 插槽尝试数字加法后，它也被 + 操作员使用。
ssizeargfunc PySequenceMethods.sq_repeat
该函数由 PySequence_Repeat() 使用并且具有相同的签名。 在通过 nb_multiply 插槽尝试数字乘法之后，它也被 * 运算符使用。
ssizeargfunc PySequenceMethods.sq_item

该函数由 PySequence_GetItem() 使用并且具有相同的签名。 在通过 mp_subscript 插槽尝试订阅后，它也被 PyObject_GetItem() 使用。 PySequence_Check()函数返回1时必须填入这个槽，否则可以是NULL。

负索引处理如下：如果 sq_length 槽被填满，则调用它并使用序列长度计算传递给 sq_item 的正索引。 如果 sq_length 是 NULL，则索引按原样传递给函数。

ssizeobjargproc PySequenceMethods.sq_ass_item
该函数由 PySequence_SetItem() 使用并且具有相同的签名。 PyObject_SetItem() 和 PyObject_DelItem() 在尝试通过 mp_ass_subscript 槽进行项目分配和删除后，也会使用它。 如果对象不支持项目分配和删除，则此插槽可能会保留为 NULL。
objobjproc PySequenceMethods.sq_contains
此函数可由 PySequence_Contains() 使用并具有相同的签名。 这个槽可以留给 NULL，在这种情况下 PySequence_Contains() 简单地遍历序列直到找到匹配。
binaryfunc PySequenceMethods.sq_inplace_concat
该函数由 PySequence_InPlaceConcat() 使用并且具有相同的签名。 它应该修改它的第一个操作数，并返回它。 这个槽可能留给 NULL，在这种情况下 PySequence_InPlaceConcat() 将回退到 PySequence_Concat()。 在通过 nb_inplace_add 插槽尝试数字就地加法后，它也被增强分配 += 使用。
ssizeargfunc PySequenceMethods.sq_inplace_repeat
该函数由 PySequence_InPlaceRepeat() 使用并且具有相同的签名。 它应该修改它的第一个操作数，并返回它。 这个槽可能留给 NULL，在这种情况下 PySequence_InPlaceRepeat() 将回退到 PySequence_Repeat()。 在通过 nb_inplace_multiply 槽尝试数字原地乘法之后，它也被增强赋值 *= 使用。


缓冲区对象结构

type PyBufferProcs
该结构包含指向 缓冲区协议 所需函数的指针。 该协议定义了导出器对象如何将其内部数据公开给消费者对象。
getbufferproc PyBufferProcs.bf_getbuffer

这个函数的签名是：

int (PyObject *exporter, Py_buffer *view, int flags);

处理对 exporter 的请求以填写 flags 指定的 view。 除了第 (3) 点，此函数的实现必须采取以下步骤：

  1. 检查是否可以满足请求。 如果不是，则提高 PyExc_BufferError，将 view->obj 设置为 NULL 并返回 -1。

  2. 填写要求的字段。

  3. 为导出数量增加一个内部计数器。

  4. 将 view->obj 设置为 exporter 并增加 view->obj。

  5. 返回 0。

如果 exporter 是缓冲区提供者链或树的一部分，则可以使用两种主要方案：

  • 重新导出：树的每个成员都充当导出对象，并将 view->obj 设置为对自身的新引用。

  • 重定向：缓冲区请求被重定向到树的根对象。 这里， view->obj 将是对根对象的新引用。

view 的各个字段在 缓冲区结构 节中描述，导出器必须如何对特定请求做出反应的规则在 缓冲区请求类型 节中。

Py_buffer 结构中指向的所有内存都属于导出器，并且必须保持有效直到没有消费者为止。 format、shape、strides、suboffsets 和 internal 对消费者来说是只读的。

PyBuffer_FillInfo() 提供了一种在正确处理所有请求类型的同时公开简单字节缓冲区的简单方法。

PyObject_GetBuffer() 是包装这个函数的消费者接口。

releasebufferproc PyBufferProcs.bf_releasebuffer

这个函数的签名是：

void (PyObject *exporter, Py_buffer *view);

处理释放缓冲区资源的请求。 如果不需要释放资源，PyBufferProcs.bf_releasebuffer可能是NULL。 否则，此函数的标准实现将采取以下可选步骤：

  1. 减少导出数量的内部计数器。

  2. 如果计数器为 0，则释放与 view 关联的所有内存。

导出器必须使用 internal 字段来跟踪特定于缓冲区的资源。 该字段保证保持不变，而消费者可以将原始缓冲区的副本作为 view 参数传递。

此函数不得减少 view->obj，因为这是在 PyBuffer_Release() 中自动完成的（此方案对于打破引用循环很有用）。

PyBuffer_Release() 是包装这个函数的消费者接口。


异步对象结构

3.5 版中的新功能。


type PyAsyncMethods

该结构包含指向实现 awaitable 和 asynchronous iterator 对象所需的函数的指针。

这是结构定义：

typedef struct {
    unaryfunc am_await;
    unaryfunc am_aiter;
    unaryfunc am_anext;
} PyAsyncMethods;
unaryfunc PyAsyncMethods.am_await

这个函数的签名是：

PyObject *am_await(PyObject *self)

返回的对象必须是迭代器，即 PyIter_Check() 必须为其返回 1。

如果对象不是 awaitable，则此插槽可以设置为 NULL。

unaryfunc PyAsyncMethods.am_aiter

这个函数的签名是：

PyObject *am_aiter(PyObject *self)

必须返回一个 awaitable 对象。 有关详细信息，请参阅 __anext__()。

如果一个对象没有实现异步迭代协议，这个槽可以设置为 NULL。

unaryfunc PyAsyncMethods.am_anext

这个函数的签名是：

PyObject *am_anext(PyObject *self)

必须返回一个 awaitable 对象。 有关详细信息，请参阅 __anext__()。 此插槽可以设置为 NULL。



取自“https://cainiaojiaocheng.com/index.php?title=Python/docs/3.6/c-api/typeobj&oldid=23490”
Powered by MediaWiki