类型对象¶

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

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

除了以下快速参考外，示例部分还提供了 PyTypeObject 的含义和用法的快速了解。

快速参考¶

“tp 插槽”¶

PyTypeObject 插槽 [1]	类型	特殊方法/属性	信息 [2]
PyTypeObject 插槽 [1]	类型	特殊方法/属性	O	T	D	I
<R> `tp_name`	const char *	__name__	X	X
`tp_basicsize`	`Py_ssize_t`		X	X		X
`tp_itemsize`	`Py_ssize_t`			X		X
`tp_dealloc`	`析构函数`		X	X		X
`tp_vectorcall_offset`	`Py_ssize_t`			X		X
(`tp_getattr`)	`getattrfunc`	__getattribute__， __getattr__				G
(`tp_setattr`)	`setattrfunc`	__setattr__， __delattr__				G
`tp_as_async`	`PyAsyncMethods` *	子插槽				%
`tp_repr`	`reprfunc`	__repr__	X	X		X
`tp_as_number`	`PyNumberMethods` *	子插槽				%
`tp_as_sequence`	`PySequenceMethods` *	子插槽				%
`tp_as_mapping`	`PyMappingMethods` *	子插槽				%
`tp_hash`	`hashfunc`	__hash__	X			G
`tp_call`	`ternaryfunc`	__call__		X		X
`tp_str`	`reprfunc`	__str__	X			X
`tp_getattro`	`getattrofunc`	__getattribute__， __getattr__	X	X		G
`tp_setattro`	`setattrofunc`	__setattr__， __delattr__	X	X		G
`tp_as_buffer`	`PyBufferProcs` *					%
`tp_flags`	unsigned long		X	X		?
`tp_doc`	const char *	__doc__	X	X
`tp_traverse`	`traverseproc`			X		G
`tp_clear`	`inquiry`			X		G
`tp_richcompare`	`richcmpfunc`	__lt__， __le__， __eq__， __ne__， __gt__， __ge__	X			G
(`tp_weaklistoffset`)	`Py_ssize_t`			X		?
`tp_iter`	`getiterfunc`	__iter__				X
`tp_iternext`	`iternextfunc`	__next__				X
`tp_methods`	`PyMethodDef` []		X	X
`tp_members`	`PyMemberDef` []			X
`tp_getset`	`PyGetSetDef` []		X	X
`tp_base`	`PyTypeObject` *	__base__			X
`tp_dict`	`PyObject` *	__dict__			?
`tp_descr_get`	`descrgetfunc`	__get__				X
`tp_descr_set`	`descrsetfunc`	__set__， __delete__				X
(`tp_dictoffset`)	`Py_ssize_t`			X		?
`tp_init`	`initproc`	__init__	X	X		X
`tp_alloc`	`allocfunc`		X		?	?
`tp_new`	`newfunc`	__new__	X	X	?	?
`tp_free`	`freefunc`		X	X	?	?
`tp_is_gc`	`inquiry`			X		X
<`tp_bases`>	`PyObject` *	__bases__			~
<`tp_mro`>	`PyObject` *	__mro__			~
[`tp_cache`]	`PyObject` *
[`tp_subclasses`]	void *	__subclasses__
[`tp_weaklist`]	`PyObject` *
(`tp_del`)	`析构函数`
[`tp_version_tag`]	unsigned int
`tp_finalize`	`析构函数`	__del__				X
`tp_vectorcall`	`vectorcallfunc`
[`tp_watched`]	unsigned char

子插槽¶

插槽	类型	特殊方法
`am_await`	`unaryfunc`	__await__
`am_aiter`	`unaryfunc`	__aiter__
`am_anext`	`unaryfunc`	__anext__
`am_send`	`sendfunc`

`nb_add`	`binaryfunc`	__add__ __radd__
`nb_inplace_add`	`binaryfunc`	__iadd__
`nb_subtract`	`binaryfunc`	__sub__ __rsub__
`nb_inplace_subtract`	`binaryfunc`	__isub__
`nb_multiply`	`binaryfunc`	__mul__ __rmul__
`nb_inplace_multiply`	`binaryfunc`	__imul__
`nb_remainder`	`binaryfunc`	__mod__ __rmod__
`nb_inplace_remainder`	`binaryfunc`	__imod__
`nb_divmod`	`binaryfunc`	__divmod__ __rdivmod__
`nb_power`	`ternaryfunc`	__pow__ __rpow__
`nb_inplace_power`	`ternaryfunc`	__ipow__
`nb_negative`	`unaryfunc`	__neg__
`nb_positive`	`unaryfunc`	__pos__
`nb_absolute`	`unaryfunc`	__abs__
`nb_bool`	`inquiry`	__bool__
`nb_invert`	`unaryfunc`	__invert__
`nb_lshift`	`binaryfunc`	__lshift__ __rlshift__
`nb_inplace_lshift`	`binaryfunc`	__ilshift__
`nb_rshift`	`binaryfunc`	__rshift__ __rrshift__
`nb_inplace_rshift`	`binaryfunc`	__irshift__
`nb_and`	`binaryfunc`	__and__ __rand__
`nb_inplace_and`	`binaryfunc`	__iand__
`nb_xor`	`binaryfunc`	__xor__ __rxor__
`nb_inplace_xor`	`binaryfunc`	__ixor__
`nb_or`	`binaryfunc`	__or__ __ror__
`nb_inplace_or`	`binaryfunc`	__ior__
`nb_int`	`unaryfunc`	__int__
`nb_reserved`	void *
`nb_float`	`unaryfunc`	__float__
`nb_floor_divide`	`binaryfunc`	__floordiv__
`nb_inplace_floor_divide`	`binaryfunc`	__ifloordiv__
`nb_true_divide`	`binaryfunc`	__truediv__
`nb_inplace_true_divide`	`binaryfunc`	__itruediv__
`nb_index`	`unaryfunc`	__index__
`nb_matrix_multiply`	`binaryfunc`	__matmul__ __rmatmul__
`nb_inplace_matrix_multiply`	`binaryfunc`	__imatmul__

`mp_length`	`lenfunc`	__len__
`mp_subscript`	`binaryfunc`	__getitem__
`mp_ass_subscript`	`objobjargproc`	__setitem__， __delitem__

`sq_length`	`lenfunc`	__len__
`sq_concat`	`binaryfunc`	__add__
`sq_repeat`	`ssizeargfunc`	__mul__
`sq_item`	`ssizeargfunc`	__getitem__
`sq_ass_item`	`ssizeobjargproc`	__setitem__ __delitem__
`sq_contains`	`objobjproc`	__contains__
`sq_inplace_concat`	`binaryfunc`	__iadd__
`sq_inplace_repeat`	`ssizeargfunc`	__imul__

`bf_getbuffer`	`getbufferproc()`
`bf_releasebuffer`	`releasebufferproc()`

插槽 typedef¶

typedef	参数类型	返回类型
`allocfunc`	`PyTypeObject` * `Py_ssize_t`	`PyObject` *
`析构函数`	`PyObject` *	void
`freefunc`	void *	void
`traverseproc`	`PyObject` * `visitproc` void *	int
`newfunc`	`PyObject` * `PyObject` * `PyObject` *	`PyObject` *
`initproc`	`PyObject` * `PyObject` * `PyObject` *	int
`reprfunc`	`PyObject` *	`PyObject` *
`getattrfunc`	`PyObject` * const char *	`PyObject` *
`setattrfunc`	`PyObject` * const char * `PyObject` *	int
`getattrofunc`	`PyObject` * `PyObject` *	`PyObject` *
`setattrofunc`	`PyObject` * `PyObject` * `PyObject` *	int
`descrgetfunc`	`PyObject` * `PyObject` * `PyObject` *	`PyObject` *
`descrsetfunc`	`PyObject` * `PyObject` * `PyObject` *	int
`hashfunc`	`PyObject` *	Py_hash_t
`richcmpfunc`	`PyObject` * `PyObject` * int	`PyObject` *
`getiterfunc`	`PyObject` *	`PyObject` *
`iternextfunc`	`PyObject` *	`PyObject` *
`lenfunc`	`PyObject` *	`Py_ssize_t`
`getbufferproc`	`PyObject` * `Py_buffer` * int	int
`releasebufferproc`	`PyObject` * `Py_buffer` *	void
`inquiry`	`PyObject` *	int
`unaryfunc`	`PyObject` *	`PyObject` *
`binaryfunc`	`PyObject` * `PyObject` *	`PyObject` *
`ternaryfunc`	`PyObject` * `PyObject` * `PyObject` *	`PyObject` *
`ssizeargfunc`	`PyObject` * `Py_ssize_t`	`PyObject` *
`ssizeobjargproc`	`PyObject` * `Py_ssize_t` `PyObject` *	int
`objobjproc`	`PyObject` * `PyObject` *	int
`objobjargproc`	`PyObject` * `PyObject` * `PyObject` *	int

有关更多详细信息，请参见下面的插槽类型 typedef。

PyTypeObject 定义¶

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;
    Py_ssize_t tp_vectorcall_offset;
    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 */

    /* Assigned meaning in release 2.0 */
    /* call function for all accessible objects */
    traverseproc tp_traverse;

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

    /* Assigned meaning in release 2.1 */
    /* 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;
    // Strong reference on a heap type, borrowed reference on a static type
    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;
    vectorcallfunc tp_vectorcall;

    /* bitset of which type-watchers care about this type */
    unsigned char tp_watched;
} PyTypeObject;

PyObject 插槽¶

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

Py_ssize_t PyObject.ob_refcnt¶

属于稳定 ABI 的一部分。

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

继承

此字段不会被子类型继承。

PyTypeObject *PyObject.ob_type¶

属于稳定 ABI 的一部分。

这是类型的类型，换句话说，是它的元类型。它由 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() 如果此字段非零，则不会更改此字段。

继承

此字段被子类型继承。

PyVarObject 槽¶

Py_ssize_t PyVarObject.ob_size¶

属于稳定 ABI 的一部分。

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

继承

此字段不会被子类型继承。

PyTypeObject 槽¶

每个槽都有一个描述继承的部分。如果 PyType_Ready() 可以在字段设置为 NULL 时设置一个值，则还会有一个“默认”部分。（请注意，在 PyBaseObject_Type 和 PyType_Type 上设置的许多字段实际上充当默认值。）

const char *PyTypeObject.tp_name¶

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

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

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

如果不存在点，则整个 tp_name 字段可以作为 __name__ 属性访问，并且 __module__ 属性是未定义的（除非如上所述在字典中显式设置）。这意味着您的类型将无法 pickle。此外，它不会列在用 pydoc 创建的模块文档中。

此字段不能为 NULL。它是 PyTypeObject() 中唯一必需的字段（可能除了 tp_itemsize 之外）。

继承

此字段不会被子类型继承。

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_basicsize 的值来处理。示例：假设一个类型实现了一个 double 数组。tp_itemsize 是 sizeof(double)。程序员有责任确保 tp_basicsize 是 sizeof(double) 的倍数（假设这是 double 的对齐要求）。

对于任何具有可变长度实例的类型，此字段不能为 NULL。

继承

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

destructor PyTypeObject.tp_dealloc¶

指向实例析构函数的指针。除非类型保证其实例永远不会被释放（如单例 None 和 Ellipsis 的情况），否则必须定义此函数。函数签名是

void tp_dealloc(PyObject *self);

当新的引用计数为零时，析构函数由 Py_DECREF() 和 Py_XDECREF() 宏调用。此时，实例仍然存在，但没有对它的引用。析构函数应释放实例拥有的所有引用，释放实例拥有的所有内存缓冲区（使用与用于分配缓冲区的分配函数相对应的释放函数），并调用类型的 tp_free 函数。如果类型不可子类型化（没有设置 Py_TPFLAGS_BASETYPE 标志位），则可以直接调用对象释放器，而不是通过 tp_free。对象释放器应该是用于分配实例的释放器；如果实例是使用 PyObject_New 或 PyObject_NewVar 分配的，则通常为 PyObject_Del()；如果实例是使用 PyObject_GC_New 或 PyObject_GC_NewVar 分配的，则为 PyObject_GC_Del()。

如果该类型支持垃圾回收（已设置 Py_TPFLAGS_HAVE_GC 标志位），则析构函数应在清除任何成员字段之前调用 PyObject_GC_UnTrack()。

static void foo_dealloc(foo_object *self) {
    PyObject_GC_UnTrack(self);
    Py_CLEAR(self->ref);
    Py_TYPE(self)->tp_free((PyObject *)self);
}

最后，如果该类型是堆分配的 (Py_TPFLAGS_HEAPTYPE)，则释放器应在调用类型释放器之后（通过 Py_DECREF()）释放对其类型对象拥有的引用。为了避免悬空指针，推荐的实现方法是

static void foo_dealloc(foo_object *self) {
    PyTypeObject *tp = Py_TYPE(self);
    // free references and buffers here
    tp->tp_free(self);
    Py_DECREF(tp);
}

警告

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

继承

此字段被子类型继承。

Py_ssize_t PyTypeObject.tp_vectorcall_offset¶

一个可选的偏移量，指向实现使用 vectorcall 协议调用对象的每个实例的函数，这是更简单的 tp_call 的更高效替代方案。

只有当设置了 Py_TPFLAGS_HAVE_VECTORCALL 标志时，才使用此字段。如果设置了该标志，则该值必须是一个正整数，其中包含实例中 vectorcallfunc 指针的偏移量。

vectorcallfunc 指针可以为 NULL，在这种情况下，实例的行为就好像没有设置 Py_TPFLAGS_HAVE_VECTORCALL 一样：调用实例将回退到 tp_call。

任何设置 Py_TPFLAGS_HAVE_VECTORCALL 的类还必须设置 tp_call，并确保其行为与 vectorcallfunc 函数一致。这可以通过将 tp_call 设置为 PyVectorcall_Call() 来完成。

在 3.8 版本中更改: 在 3.8 版本之前，此槽名为 tp_print。在 Python 2.x 中，它用于打印到文件。在 Python 3.0 到 3.7 中，它未使用。

在 3.12 版本中更改: 在 3.12 版本之前，不建议可变堆类型实现 vectorcall 协议。当用户在 Python 代码中设置 __call__ 时，只会更新 tp_call，这可能会导致它与 vectorcall 函数不一致。自 3.12 版本以来，设置 __call__ 将通过清除 Py_TPFLAGS_HAVE_VECTORCALL 标志来禁用 vectorcall 优化。

继承

此字段始终被继承。但是，Py_TPFLAGS_HAVE_VECTORCALL 标志并不总是被继承。如果未设置该标志，则子类将不会使用 vectorcall，除非显式调用 PyVectorcall_Call()。

getattrfunc PyTypeObject.tp_getattr¶

一个可选的指向获取属性字符串函数的指针。

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

继承

组： tp_getattr, tp_getattro

此字段与 tp_getattro 一起由子类型继承：当子类型的 tp_getattr 和 tp_getattro 都为 NULL 时，子类型会从其基类型继承 tp_getattr 和 tp_getattro。

setattrfunc PyTypeObject.tp_setattr¶

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

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

继承

组： tp_setattr, tp_setattro

此字段与 tp_setattro 一起由子类型继承：当子类型的 tp_setattr 和 tp_setattro 都为 NULL 时，子类型会从其基类型继承 tp_setattr 和 tp_setattro。

PyAsyncMethods *PyTypeObject.tp_as_async¶

指向一个附加结构的指针，该结构仅包含与在 C 级别实现可等待和异步迭代器协议的对象相关的字段。有关详细信息，请参阅异步对象结构。

3.5 版本新增: 以前称为 tp_compare 和 tp_reserved。

继承

tp_as_async 字段不被继承，但其中包含的字段会被单独继承。

reprfunc PyTypeObject.tp_repr¶

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

签名与 PyObject_Repr() 的相同

PyObject *tp_repr(PyObject *self);

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

继承

此字段被子类型继承。

默认

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

PyNumberMethods *PyTypeObject.tp_as_number¶

指向一个附加结构的指针，该结构仅包含与实现数字协议的对象相关的字段。这些字段在数字对象结构中进行了说明。

继承

tp_as_number 字段不被继承，但其中包含的字段会被单独继承。

PySequenceMethods *PyTypeObject.tp_as_sequence¶

指向一个附加结构的指针，该结构仅包含与实现序列协议的对象相关的字段。这些字段在序列对象结构中进行了说明。

继承

tp_as_sequence 字段不被继承，但其中包含的字段会被单独继承。

PyMappingMethods *PyTypeObject.tp_as_mapping¶

指向一个附加结构的指针，该结构仅包含与实现映射协议的对象相关的字段。这些字段在映射对象结构中进行了说明。

继承

tp_as_mapping 字段不被继承，但其中包含的字段会被单独继承。

hashfunc PyTypeObject.tp_hash¶

一个可选的函数指针，用于实现内置函数 hash()。

其签名与 PyObject_Hash() 相同。

Py_hash_t tp_hash(PyObject *);

值 -1 不应作为正常返回值返回；当计算哈希值时发生错误时，该函数应设置一个异常并返回 -1。

当此字段未设置（且 tp_richcompare 未设置）时，尝试获取对象的哈希值会引发 TypeError。这与将其设置为 PyObject_HashNotImplemented() 相同。

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

继承

组： tp_hash， tp_richcompare

此字段与 tp_richcompare 一起被子类型继承：当子类型的 tp_richcompare 和 tp_hash 都为 NULL 时，子类型将同时继承 tp_richcompare 和 tp_hash。

默认

PyBaseObject_Type 使用 PyObject_GenericHash()。

ternaryfunc PyTypeObject.tp_call¶

一个可选的函数指针，用于实现调用对象。如果对象不可调用，则应为 NULL。其签名与 PyObject_Call() 相同。

PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);

继承

此字段被子类型继承。

reprfunc PyTypeObject.tp_str¶

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

其签名与 PyObject_Str() 相同。

PyObject *tp_str(PyObject *self);

该函数必须返回字符串或 Unicode 对象。它应该是对象的“友好”字符串表示形式，因为这是 print() 函数等将使用的表示形式。

继承

此字段被子类型继承。

默认

当此字段未设置时，将调用 PyObject_Repr() 返回字符串表示形式。

getattrofunc PyTypeObject.tp_getattro¶

一个可选的获取属性函数指针。

其签名与 PyObject_GetAttr() 相同。

PyObject *tp_getattro(PyObject *self, PyObject *attr);

通常将其设置为 PyObject_GenericGetAttr() 很方便，它实现了查找对象属性的正常方法。

继承

组： tp_getattr, tp_getattro

此字段与 tp_getattr 一起被子类型继承：当子类型的 tp_getattr 和 tp_getattro 都为 NULL 时，子类型将从其基类型同时继承 tp_getattr 和 tp_getattro。

默认

PyBaseObject_Type 使用 PyObject_GenericGetAttr()。

setattrofunc PyTypeObject.tp_setattro¶

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

其签名与 PyObject_SetAttr() 相同。

int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);

此外，必须支持将value 设置为 NULL 来删除属性。通常，将其设置为 PyObject_GenericSetAttr() 很方便，它实现了设置对象属性的正常方法。

继承

组： tp_setattr, tp_setattro

此字段与 tp_setattr 一起被子类型继承：当子类型的 tp_setattr 和 tp_setattro 都为 NULL 时，子类型将从其基类型同时继承 tp_setattr 和 tp_setattro。

默认

PyBaseObject_Type 使用 PyObject_GenericSetAttr()。

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值。 .. XXX 大多数标志位真的是单独继承的吗？

默认

PyBaseObject_Type使用Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE。

位掩码

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

Py_TPFLAGS_HEAPTYPE¶

当类型对象本身在堆上分配时，例如，使用PyType_FromSpec()动态创建的类型时，会设置此位。在这种情况下，其实例的ob_type字段被视为对该类型的引用，并且在创建新实例时，该类型对象被 INCREF，并在实例被销毁时被 DECREF（这不适用于子类型的实例；只有实例的 ob_type 引用的类型才会 INCREF 或 DECREF）。堆类型也应该支持垃圾回收，因为它们可以与自己的模块对象形成引用循环。

继承

???

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_HAVE_GC，tp_traverse，tp_clear

Py_TPFLAGS_HAVE_GC标志位与tp_traverse和tp_clear字段一起继承，即，如果子类型中的Py_TPFLAGS_HAVE_GC标志位被清除，并且子类型中的tp_traverse和tp_clear字段存在并且具有NULL值。

Py_TPFLAGS_DEFAULT¶

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

继承

???

Py_TPFLAGS_METHOD_DESCRIPTOR¶

此位表示对象的行为类似于未绑定的方法。

如果为type(meth)设置了此标志，则

meth.__get__(obj, cls)(*args, **kwds) (其中 obj 不是 None) 必须等效于 meth(obj, *args, **kwds)。
meth.__get__(None, cls)(*args, **kwds) 必须等价于 meth(*args, **kwds)。

此标志为典型的如 obj.meth() 的方法调用启用优化：它避免为 obj.meth 创建临时的“绑定方法”对象。

3.8 版本新增。

继承

此标志永远不会被未设置 Py_TPFLAGS_IMMUTABLETYPE 标志的类型继承。对于扩展类型，当继承 tp_descr_get 时，它会被继承。

Py_TPFLAGS_MANAGED_DICT¶

此位表示该类的实例具有 ~object.__dict__ 属性，并且字典的空间由虚拟机管理。

如果设置了此标志，则还应设置 Py_TPFLAGS_HAVE_GC。

类型遍历函数必须调用 PyObject_VisitManagedDict()，并且其清除函数必须调用 PyObject_ClearManagedDict()。

3.12 版本新增。

继承

除非在超类中设置了 tp_dictoffset 字段，否则此标志会被继承。

Py_TPFLAGS_MANAGED_WEAKREF¶

此位表示该类的实例应该是可弱引用的。

3.12 版本新增。

继承

除非在超类中设置了 tp_weaklistoffset 字段，否则此标志会被继承。

Py_TPFLAGS_ITEMS_AT_END¶

仅可用于可变大小的类型，即具有非零 tp_itemsize 的类型。

表示此类型的实例的可变大小部分位于实例内存区域的末尾，偏移量为 Py_TYPE(obj)->tp_basicsize（在每个子类中可能不同）。

设置此标志时，请确保所有超类都使用此内存布局，或者都不是可变大小的。Python 不会对此进行检查。

3.12 版本新增。

继承

此标志会被继承。

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 版本新增。

3.8 版本起已弃用: 此标志不再必要，因为解释器假定类型结构中始终存在 tp_finalize 插槽。

Py_TPFLAGS_HAVE_VECTORCALL¶

当类实现 vectorcall 协议时，将设置此位。有关详细信息，请参见 tp_vectorcall_offset。

继承

如果也继承了 tp_call，则会继承此位。

3.9 版本新增。

在 3.12 版本中变更: 当重新分配类的 __call__() 方法时，现在会从类中删除此标志。

现在，可变类可以继承此标志。

Py_TPFLAGS_IMMUTABLETYPE¶

对于不可变的类型对象，会设置此位：不能设置或删除类型属性。

PyType_Ready() 会自动将此标志应用于静态类型。

继承

此标志不会被继承。

3.10 版本新增。

Py_TPFLAGS_DISALLOW_INSTANTIATION¶

禁止创建该类型的实例：将 tp_new 设置为 NULL，并且不在类型字典中创建 __new__ 键。

该标志必须在创建类型之前设置，而不是之后。例如，它必须在对该类型调用 PyType_Ready() 之前设置。

如果 tp_base 为 NULL 或 &PyBaseObject_Type 并且 tp_new 为 NULL，则会在静态类型上自动设置该标志。

继承

此标志不会被继承。但是，除非子类提供非 NULL 的 tp_new（这只能通过 C API 实现），否则子类将不可实例化。

注意

要禁止直接实例化类，但允许实例化其子类（例如，对于抽象基类），请不要使用此标志。而是使 tp_new 仅对子类成功。

3.10 版本新增。

Py_TPFLAGS_MAPPING¶

此位表示该类的实例在用作 match 块的主题时，可以匹配映射模式。当注册或子类化 collections.abc.Mapping 时，会自动设置它，当注册 collections.abc.Sequence 时，会取消设置它。

注意

Py_TPFLAGS_MAPPING 和 Py_TPFLAGS_SEQUENCE 是互斥的；同时启用这两个标志是错误的。

继承

此标志会被尚未设置 Py_TPFLAGS_SEQUENCE 的类型继承。

另请参阅

PEP 634 – 结构化模式匹配：规范

3.10 版本新增。

Py_TPFLAGS_SEQUENCE¶

此位表示当该类的实例用作 match 代码块的主题时，可以匹配序列模式。当注册或子类化 collections.abc.Sequence 时会自动设置此位，而当注册 collections.abc.Mapping 时会取消设置此位。

注意

Py_TPFLAGS_MAPPING 和 Py_TPFLAGS_SEQUENCE 是互斥的；同时启用这两个标志是错误的。

继承

此标志会被尚未设置 Py_TPFLAGS_MAPPING 的类型继承。

另请参阅

PEP 634 – 结构化模式匹配：规范

3.10 版本新增。

Py_TPFLAGS_VALID_VERSION_TAG¶: 内部使用。请勿设置或取消设置此标志。要指示类已更改，请调用 PyType_Modified()

警告

此标志存在于头文件中，但未使用。它将在 CPython 的未来版本中删除。

const char *PyTypeObject.tp_doc¶

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

继承

此字段不会被子类型继承。

traverseproc PyTypeObject.tp_traverse¶

一个可选的指向垃圾收集器的遍历函数的指针。仅当设置了 Py_TPFLAGS_HAVE_GC 标志位时才使用。其签名为

int tp_traverse(PyObject *self, visitproc visit, void *arg);

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

tp_traverse 指针被垃圾收集器用来检测引用循环。tp_traverse 函数的典型实现只是在其拥有的实例成员中，对每个属于 Python 对象的成员调用 Py_VISIT()。例如，以下是来自 _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_TPFLAGS_HEAPTYPE）必须使用

Py_VISIT(Py_TYPE(self));

这仅在 Python 3.9 中需要。为了支持 Python 3.8 及更早的版本，此行必须是条件性的

#if PY_VERSION_HEX >= 0x03090000
    Py_VISIT(Py_TYPE(self));
#endif

如果在 tp_flags 字段中设置了 Py_TPFLAGS_MANAGED_DICT 位，则 traverse 函数必须像这样调用 PyObject_VisitManagedDict()

PyObject_VisitManagedDict((PyObject*)self, visit, arg);

警告

在实现 tp_traverse 时，只需要访问实例拥有（通过对它们具有强引用）的成员。例如，如果一个对象通过 tp_weaklist 插槽支持弱引用，则支持链表的指针（tp_weaklist 指向的指针）必须不被访问，因为该实例不直接拥有对其自身的弱引用（弱引用列表是为了支持弱引用机制，但实例对其中的元素没有强引用，因为即使实例仍然存在，也允许删除它们）。

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

堆分配类型的实例保持对其类型的引用。因此，它们的遍历函数必须访问 Py_TYPE(self)，或者通过调用另一个堆分配类型（例如堆分配的超类）的 tp_traverse 来委派此责任。如果它们不这样做，则类型对象可能无法被垃圾回收。

在 3.9 版本中更改：堆分配类型应在 tp_traverse 中访问 Py_TYPE(self)。在早期版本的 Python 中，由于错误 40217，这样做可能会导致子类崩溃。

继承

组：Py_TPFLAGS_HAVE_GC，tp_traverse，tp_clear

此字段与 tp_clear 和 Py_TPFLAGS_HAVE_GC 标志位一起被子类型继承：如果子类型中所有位都为零，则标志位、tp_traverse 和 tp_clear 都从基类型继承。

inquiry PyTypeObject.tp_clear¶

一个可选的指向垃圾收集器的清除函数的指针。仅当设置了 Py_TPFLAGS_HAVE_GC 标志位时才使用。其签名为

int tp_clear(PyObject *);

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 之后，才能释放（通过 Py_DECREF()）对包含对象的引用。这是因为释放引用可能会导致包含的对象变成垃圾，从而触发一系列回收活动，其中可能包括调用任意 Python 代码（由于与包含对象关联的终结器或弱引用回调）。如果此类代码有可能再次引用 self，那么重要的是，此时指向包含对象的指针为 NULL，以便 self 知道不能再使用包含的对象。Py_CLEAR() 宏以安全的顺序执行操作。

如果在 tp_flags 字段中设置了 Py_TPFLAGS_MANAGED_DICT 位，则遍历函数必须像这样调用 PyObject_ClearManagedDict()

PyObject_ClearManagedDict((PyObject*)self);

请注意，tp_clear 并非总是在实例被释放之前调用。例如，当引用计数足以确定不再使用对象时，不会涉及循环垃圾收集器，而是直接调用 tp_dealloc。

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

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

继承

组：Py_TPFLAGS_HAVE_GC，tp_traverse，tp_clear

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

richcmpfunc PyTypeObject.tp_richcompare¶

指向富比较函数的可选指针，其签名如下

PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);

保证第一个参数是由 PyTypeObject 定义的类型的实例。

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

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

常量	比较
Py_LT¶	`<`
Py_LE¶	`<=`
Py_EQ¶	`==`
Py_NE¶	`!=`
Py_GT¶	`>`
Py_GE¶	`>=`

定义以下宏来简化富比较函数的编写

Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, op)¶

根据比较的结果，从函数返回 Py_True 或 Py_False。VAL_A 和 VAL_B 必须可以通过 C 比较运算符进行排序（例如，它们可以是 C 整数或浮点数）。第三个参数指定请求的操作，与 PyObject_RichCompare() 相同。

返回的值是一个新的强引用。

如果发生错误，则设置异常并从函数返回 NULL。

在 3.7 版本中添加。

继承

组： tp_hash， tp_richcompare

此字段与 tp_hash 一起由子类型继承：当子类型的 tp_richcompare 和 tp_hash 都为 NULL 时，子类型将继承 tp_richcompare 和 tp_hash。

默认

PyBaseObject_Type 提供了一个 tp_richcompare 实现，可以被继承。但是，如果只定义了 tp_hash，则即使继承的函数也不会被使用，并且该类型的实例将无法参与任何比较。

Py_ssize_t PyTypeObject.tp_weaklistoffset¶

虽然仍然支持此字段，但如果可能，应使用 Py_TPFLAGS_MANAGED_WEAKREF。

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

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

同时设置 Py_TPFLAGS_MANAGED_WEAKREF 位和 tp_weaklistoffset 是错误的。

继承

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

默认

如果在 tp_flags 字段中设置了 Py_TPFLAGS_MANAGED_WEAKREF 位，则 tp_weaklistoffset 将被设置为负值，以指示使用此字段是不安全的。

getiterfunc PyTypeObject.tp_iter¶

一个可选的函数指针，该函数返回对象的迭代器。它的存在通常表示此类型的实例是可迭代的（尽管序列可能在没有此函数的情况下也是可迭代的）。

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

PyObject *tp_iter(PyObject *self);

继承

此字段被子类型继承。

iternextfunc PyTypeObject.tp_iternext¶

一个可选的函数指针，该函数返回迭代器中的下一个项目。签名是

PyObject *tp_iternext(PyObject *self);

当迭代器耗尽时，它必须返回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结构数组，声明此类型实例的计算属性。

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

继承

此字段不会被子类型继承（计算属性是通过不同的机制继承的）。

PyTypeObject *PyTypeObject.tp_base¶

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

注意

槽初始化受全局变量初始化规则的约束。C99 要求初始化程序为“地址常量”。函数指示符（如PyType_GenericNew()）隐式转换为指针，是有效的 C99 地址常量。

但是，应用于非静态变量（如PyBaseObject_Type）的一元“&”运算符不一定产生地址常量。编译器可能支持此操作（gcc 支持），而 MSVC 不支持。在这方面，两个编译器都严格符合标准。

因此，应在扩展模块的 init 函数中设置tp_base。

继承

此字段不会被子类型继承（显然）。

默认

此字段的默认值为&PyBaseObject_Type（Python 程序员将其称为类型object）。

PyObject *PyTypeObject.tp_dict¶

类型的字典由PyType_Ready()存储在此处。

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

某些类型可能不会将它们的字典存储在此槽中。使用PyType_GetDict()检索任意类型的字典。

3.12 版本中的更改: 内部细节：对于静态内置类型，这始终为NULL。相反，此类类型的字典存储在PyInterpreterState上。使用PyType_GetDict()获取任意类型的字典。

继承

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

默认

如果此字段为NULL，则PyType_Ready()将为其分配一个新字典。

警告

使用PyDict_SetItem()或以其他方式通过字典 C-API 修改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¶

虽然仍然支持此字段，但如果可能，应使用 Py_TPFLAGS_MANAGED_DICT。

如果此类型的实例具有包含实例变量的字典，则此字段为非零值，并包含该类型实例中实例变量字典的偏移量；此偏移量由 PyObject_GenericGetAttr() 使用。

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

该值指定字典相对于实例结构起始位置的偏移量。

tp_dictoffset 应被视为只写。要获取指向字典的指针，请调用 PyObject_GenericGetDict()。调用 PyObject_GenericGetDict() 可能需要为字典分配内存，因此在访问对象上的属性时，调用 PyObject_GetAttr() 可能更有效率。

同时设置 Py_TPFLAGS_MANAGED_WEAKREF 位和 tp_dictoffset 是错误的。

继承

此字段由子类型继承。子类型不应覆盖此偏移量；如果 C 代码尝试在前一个偏移量处访问字典，这样做可能不安全。为了正确支持继承，请使用 Py_TPFLAGS_MANAGED_DICT。

默认

此槽没有默认值。对于静态类型，如果该字段为 NULL，则不会为实例创建 __dict__。

如果 Py_TPFLAGS_MANAGED_DICT 位在 tp_flags 字段中设置，则 tp_dictoffset 将设置为 -1，以指示使用此字段是不安全的。

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。

成功时返回 0，错误时返回 -1 并设置异常。

继承

此字段被子类型继承。

默认

对于静态类型，此字段没有默认值。

allocfunc PyTypeObject.tp_alloc¶

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

函数签名是

PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);

继承

此字段由静态子类型继承，但不由动态子类型（由 class 语句创建的子类型）继承。

默认

对于动态子类型，此字段始终设置为 PyType_GenericAlloc()，以强制执行标准堆分配策略。

对于静态子类型，PyBaseObject_Type 使用 PyType_GenericAlloc()。这是所有静态定义类型的推荐值。

newfunc PyTypeObject.tp_new¶

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

函数签名是

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

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

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

设置 Py_TPFLAGS_DISALLOW_INSTANTIATION 标志以禁止在 Python 中创建该类型的实例。

继承

此字段由子类型继承，但静态类型的 tp_base 为 NULL 或 &PyBaseObject_Type 的情况除外，它们不继承此字段。

默认

对于静态类型，此字段没有默认值。这意味着如果该槽定义为 NULL，则不能调用该类型来创建新实例；大概有其他方式可以创建实例，例如工厂函数。

freefunc PyTypeObject.tp_free¶

指向实例释放函数的可选指针。其签名为

void tp_free(void *self);

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

继承

此字段由静态子类型继承，但不由动态子类型（由 class 语句创建的子类型）继承

默认

在动态子类型中，此字段设置为一个合适的释放器，以便与 PyType_GenericAlloc() 以及 Py_TPFLAGS_HAVE_GC 标志位的取值相匹配。

对于静态子类型，PyBaseObject_Type 使用 PyObject_Del()。

inquiry PyTypeObject.tp_is_gc¶

一个可选的函数指针，由垃圾回收器调用。

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

int tp_is_gc(PyObject *self);

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

继承

此字段被子类型继承。

默认

此槽没有默认值。如果此字段为 NULL，则使用 Py_TPFLAGS_HAVE_GC 作为功能等效项。

PyObject *PyTypeObject.tp_bases¶

基类型的元组。

此字段应设置为 NULL 并视为只读。当类型 初始化 时，Python 将填充它。

对于动态创建的类，可以使用 Py_tp_bases 槽 来代替 PyType_FromSpecWithBases() 的 bases 参数。首选参数形式。

警告

多重继承对于静态定义的类型效果不佳。如果将 tp_bases 设置为元组，Python 不会引发错误，但是某些槽将仅从第一个基类继承。

继承

此字段不被继承。

PyObject *PyTypeObject.tp_mro¶

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

此字段应设置为 NULL 并视为只读。当类型 初始化 时，Python 将填充它。

继承

此字段不被继承；它由 PyType_Ready() 重新计算。

PyObject *PyTypeObject.tp_cache¶

未使用。仅供内部使用。

继承

此字段不被继承。

void *PyTypeObject.tp_subclasses¶

子类的集合。仅供内部使用。可能是一个无效的指针。

要获取子类的列表，请调用 Python 方法 __subclasses__()。

在 3.12 版本中变更：对于某些类型，此字段不保存有效的 PyObject*。该类型已更改为 void* 以指示这一点。

继承

此字段不被继承。

PyObject *PyTypeObject.tp_weaklist¶

弱引用列表头，用于对此类型对象的弱引用。不被继承。仅供内部使用。

在 3.12 版本中变更：内部细节：对于静态内置类型，即使添加了弱引用，这也始终为 NULL。相反，每个弱引用都存储在 PyInterpreterState 上。使用公共 C-API 或内部 _PyObject_GET_WEAKREFS_LISTPTR() 宏以避免区分。

继承

此字段不被继承。

destructor PyTypeObject.tp_del¶: 此字段已弃用。请改用 tp_finalize。

unsigned int PyTypeObject.tp_version_tag¶

用于索引到方法缓存中。仅供内部使用。

继承

此字段不被继承。

destructor PyTypeObject.tp_finalize¶

一个指向实例终结函数的可选指针。其签名是

void tp_finalize(PyObject *self);

如果设置了 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);
}

继承

此字段被子类型继承。

3.4 版本新增。

在 3.8 版本中变更：在 3.8 版本之前，必须设置 Py_TPFLAGS_HAVE_FINALIZE 标志位才能使用此字段。现在不再需要这样做。

另请参阅

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

vectorcallfunc PyTypeObject.tp_vectorcall¶

用于此类型对象调用的向量调用函数。换句话说，它用于为 type.__call__ 实现向量调用。如果 tp_vectorcall 为 NULL，则使用 __new__() 和 __init__() 的默认调用实现。

继承

此字段永远不会被继承。

3.9 版本中新增：（该字段自 3.8 版本起存在，但仅自 3.9 版本起使用）

unsigned char PyTypeObject.tp_watched¶: 内部的。请勿使用。

3.12 版本新增。

静态类型¶

传统上，C 代码中定义的类型是静态的，也就是说，一个静态的 PyTypeObject 结构体直接在代码中定义，并使用 PyType_Ready() 进行初始化。

这导致类型相对于 Python 中定义的类型受到限制

静态类型仅限于一个基类，即它们不能使用多重继承。
静态类型对象（但不一定是它们的实例）是不可变的。无法从 Python 添加或修改类型对象的属性。
静态类型对象在子解释器之间共享，因此它们不应包含任何特定于子解释器的状态。

此外，由于 PyTypeObject 仅作为不透明结构体是有限 API 的一部分，因此任何使用静态类型的扩展模块都必须针对特定的 Python 小版本进行编译。

堆类型¶

除了静态类型之外，另一种选择是堆分配类型，或简称为堆类型，它与 Python 的 class 语句创建的类非常相似。堆类型设置了 Py_TPFLAGS_HEAPTYPE 标志。

这是通过填充 PyType_Spec 结构体并调用 PyType_FromSpec()， PyType_FromSpecWithBases()， PyType_FromModuleAndSpec()，或 PyType_FromMetaclass() 来完成的。

数值对象结构体¶

type PyNumberMethods¶

此结构体保存对象用于实现数字协议的函数的指针。每个函数都由数字协议部分中记录的类似名称的函数使用。

以下是结构体定义

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 中重命名。

binaryfunc PyNumberMethods.nb_add¶

binaryfunc PyNumberMethods.nb_subtract¶

binaryfunc PyNumberMethods.nb_multiply¶

binaryfunc PyNumberMethods.nb_remainder¶

binaryfunc PyNumberMethods.nb_divmod¶

ternaryfunc PyNumberMethods.nb_power¶

unaryfunc PyNumberMethods.nb_negative¶

unaryfunc PyNumberMethods.nb_positive¶

unaryfunc PyNumberMethods.nb_absolute¶

inquiry PyNumberMethods.nb_bool¶

unaryfunc PyNumberMethods.nb_invert¶

binaryfunc PyNumberMethods.nb_lshift¶

binaryfunc PyNumberMethods.nb_rshift¶

binaryfunc PyNumberMethods.nb_and¶

binaryfunc PyNumberMethods.nb_xor¶

binaryfunc PyNumberMethods.nb_or¶

unaryfunc PyNumberMethods.nb_int¶

void *PyNumberMethods.nb_reserved¶

unaryfunc PyNumberMethods.nb_float¶

binaryfunc PyNumberMethods.nb_inplace_add¶

binaryfunc PyNumberMethods.nb_inplace_subtract¶

binaryfunc PyNumberMethods.nb_inplace_multiply¶

binaryfunc PyNumberMethods.nb_inplace_remainder¶

ternaryfunc PyNumberMethods.nb_inplace_power¶

binaryfunc PyNumberMethods.nb_inplace_lshift¶

binaryfunc PyNumberMethods.nb_inplace_rshift¶

binaryfunc PyNumberMethods.nb_inplace_and¶

binaryfunc PyNumberMethods.nb_inplace_xor¶

binaryfunc PyNumberMethods.nb_inplace_or¶

binaryfunc PyNumberMethods.nb_floor_divide¶

binaryfunc PyNumberMethods.nb_true_divide¶

binaryfunc PyNumberMethods.nb_inplace_floor_divide¶

binaryfunc PyNumberMethods.nb_inplace_true_divide¶

unaryfunc PyNumberMethods.nb_index¶

binaryfunc PyNumberMethods.nb_matrix_multiply¶

binaryfunc PyNumberMethods.nb_inplace_matrix_multiply¶

映射对象结构¶

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()，PySequence_SetSlice() 和 PySequence_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() 使用，并且具有相同的签名。它也被 PyObject_GetItem() 使用，在尝试通过 mp_subscript 插槽进行下标操作之后。必须填写此插槽才能使 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) 点之外，此函数的实现必须执行以下步骤

检查是否可以满足请求。如果不能，则引发 BufferError，将 view->obj 设置为 NULL 并返回 -1。
填写请求的字段。
递增内部计数器，用于记录导出的数量。
将 view->obj 设置为 exporter 并递增 view->obj。
返回 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。否则，此函数的标准实现将执行这些可选步骤

递减导出次数的内部计数器。
如果计数器为 0，则释放与 view 关联的所有内存。

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

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

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

异步对象结构¶

在 3.5 版本中添加。

type PyAsyncMethods¶

此结构保存实现可等待对象和异步迭代器对象所需的函数的指针。

以下是结构体定义

typedef struct {
    unaryfunc am_await;
    unaryfunc am_aiter;
    unaryfunc am_anext;
    sendfunc am_send;
} PyAsyncMethods;

unaryfunc PyAsyncMethods.am_await¶

此函数的签名是

PyObject *am_await(PyObject *self);

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

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

unaryfunc PyAsyncMethods.am_aiter¶

此函数的签名是

PyObject *am_aiter(PyObject *self);

必须返回一个异步迭代器对象。有关详细信息，请参阅 __anext__()。

如果对象未实现异步迭代协议，则此槽可以设置为 NULL。

unaryfunc PyAsyncMethods.am_anext¶

此函数的签名是

PyObject *am_anext(PyObject *self);

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

sendfunc PyAsyncMethods.am_send¶

此函数的签名是

PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);

有关详细信息，请参阅 PyIter_Send()。此槽可以设置为 NULL。

3.10 版本新增。

槽类型 typedef¶

typedef PyObject *(*allocfunc)(PyTypeObject *cls, Py_ssize_t nitems)¶

属于稳定 ABI 的一部分。

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

此函数不应执行任何其他实例初始化，甚至不应分配额外的内存；这应由 tp_new 完成。

typedef void (*destructor)(PyObject*)¶: 属于稳定 ABI 的一部分。

typedef void (*freefunc)(void*)¶: 请参阅 tp_free。

typedef PyObject *(*newfunc)(PyObject*, PyObject*, PyObject*)¶: 属于稳定 ABI 的一部分。
请参阅 tp_new。

typedef int (*initproc)(PyObject*, PyObject*, PyObject*)¶: 属于稳定 ABI 的一部分。
请参阅tp_init。

typedef PyObject *(*reprfunc)(PyObject*)¶: 属于稳定 ABI 的一部分。
请参阅tp_repr。

typedef PyObject *(*getattrfunc)(PyObject *self, char *attr)¶: 属于稳定 ABI 的一部分。
返回对象的指定属性的值。

typedef int (*setattrfunc)(PyObject *self, char *attr, PyObject *value)¶: 属于稳定 ABI 的一部分。
设置对象的指定属性的值。如果 value 参数设置为 NULL，则删除该属性。

typedef PyObject *(*getattrofunc)(PyObject *self, PyObject *attr)¶

属于稳定 ABI 的一部分。

返回对象的指定属性的值。

请参阅tp_getattro。

typedef int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value)¶

属于稳定 ABI 的一部分。

设置对象的指定属性的值。如果 value 参数设置为 NULL，则删除该属性。

请参阅tp_setattro。

typedef PyObject *(*descrgetfunc)(PyObject*, PyObject*, PyObject*)¶: 属于稳定 ABI 的一部分。
请参阅tp_descr_get。

typedef int (*descrsetfunc)(PyObject*, PyObject*, PyObject*)¶: 属于稳定 ABI 的一部分。
请参阅tp_descr_set。

typedef Py_hash_t (*hashfunc)(PyObject*)¶: 属于稳定 ABI 的一部分。
请参阅tp_hash。

typedef PyObject *(*richcmpfunc)(PyObject*, PyObject*, int)¶: 属于稳定 ABI 的一部分。
请参阅tp_richcompare。

typedef PyObject *(*getiterfunc)(PyObject*)¶: 属于稳定 ABI 的一部分。
请参阅tp_iter。

typedef PyObject *(*iternextfunc)(PyObject*)¶: 属于稳定 ABI 的一部分。
请参阅tp_iternext。

typedef Py_ssize_t (*lenfunc)(PyObject*)¶: 属于稳定 ABI 的一部分。

typedef int (*getbufferproc)(PyObject*, Py_buffer*, int)¶: 自 3.12 版本起，属于稳定 ABI 的一部分。

typedef void (*releasebufferproc)(PyObject*, Py_buffer*)¶: 自 3.12 版本起，属于稳定 ABI 的一部分。

typedef PyObject *(*unaryfunc)(PyObject*)¶: 属于稳定 ABI 的一部分。

typedef PyObject *(*binaryfunc)(PyObject*, PyObject*)¶: 属于稳定 ABI 的一部分。

typedef PySendResult (*sendfunc)(PyObject*, PyObject*, PyObject**)¶: 请参考 am_send。

typedef PyObject *(*ternaryfunc)(PyObject*, PyObject*, PyObject*)¶: 属于稳定 ABI 的一部分。

typedef PyObject *(*ssizeargfunc)(PyObject*, Py_ssize_t)¶: 属于稳定 ABI 的一部分。

typedef int (*ssizeobjargproc)(PyObject*, Py_ssize_t, PyObject*)¶: 属于稳定 ABI 的一部分。

typedef int (*objobjproc)(PyObject*, PyObject*)¶: 属于稳定 ABI 的一部分。

typedef int (*objobjargproc)(PyObject*, PyObject*, PyObject*)¶: 属于稳定 ABI 的一部分。

示例¶

以下是一些 Python 类型定义的基本示例。它们包括您可能遇到的常见用法。有些演示了棘手的边缘情况。有关更多示例、实用信息和教程，请参阅定义扩展类型：教程和定义扩展类型：各种主题。

一个基本的静态类型

typedef struct {
    PyObject_HEAD
    const char *data;
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject),
    .tp_doc = PyDoc_STR("My objects"),
    .tp_new = myobj_new,
    .tp_dealloc = (destructor)myobj_dealloc,
    .tp_repr = (reprfunc)myobj_repr,
};

您还可能会发现较旧的代码（尤其是在 CPython 代码库中）使用了更详细的初始化程序

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    "mymod.MyObject",               /* tp_name */
    sizeof(MyObject),               /* tp_basicsize */
    0,                              /* tp_itemsize */
    (destructor)myobj_dealloc,      /* tp_dealloc */
    0,                              /* tp_vectorcall_offset */
    0,                              /* tp_getattr */
    0,                              /* tp_setattr */
    0,                              /* tp_as_async */
    (reprfunc)myobj_repr,           /* tp_repr */
    0,                              /* tp_as_number */
    0,                              /* tp_as_sequence */
    0,                              /* tp_as_mapping */
    0,                              /* tp_hash */
    0,                              /* tp_call */
    0,                              /* tp_str */
    0,                              /* tp_getattro */
    0,                              /* tp_setattro */
    0,                              /* tp_as_buffer */
    0,                              /* tp_flags */
    PyDoc_STR("My objects"),        /* tp_doc */
    0,                              /* tp_traverse */
    0,                              /* tp_clear */
    0,                              /* tp_richcompare */
    0,                              /* tp_weaklistoffset */
    0,                              /* tp_iter */
    0,                              /* tp_iternext */
    0,                              /* tp_methods */
    0,                              /* tp_members */
    0,                              /* tp_getset */
    0,                              /* tp_base */
    0,                              /* tp_dict */
    0,                              /* tp_descr_get */
    0,                              /* tp_descr_set */
    0,                              /* tp_dictoffset */
    0,                              /* tp_init */
    0,                              /* tp_alloc */
    myobj_new,                      /* tp_new */
};

一个支持弱引用、实例字典和哈希的类型

typedef struct {
    PyObject_HEAD
    const char *data;
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject),
    .tp_doc = PyDoc_STR("My objects"),
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE |
         Py_TPFLAGS_HAVE_GC | Py_TPFLAGS_MANAGED_DICT |
         Py_TPFLAGS_MANAGED_WEAKREF,
    .tp_new = myobj_new,
    .tp_traverse = (traverseproc)myobj_traverse,
    .tp_clear = (inquiry)myobj_clear,
    .tp_alloc = PyType_GenericNew,
    .tp_dealloc = (destructor)myobj_dealloc,
    .tp_repr = (reprfunc)myobj_repr,
    .tp_hash = (hashfunc)myobj_hash,
    .tp_richcompare = PyBaseObject_Type.tp_richcompare,
};

一个不能被子类化并且不能被调用来创建实例（例如，使用单独的工厂函数）的 str 子类，使用 Py_TPFLAGS_DISALLOW_INSTANTIATION 标志

typedef struct {
    PyUnicodeObject raw;
    char *extra;
} MyStr;

static PyTypeObject MyStr_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyStr",
    .tp_basicsize = sizeof(MyStr),
    .tp_base = NULL,  // set to &PyUnicode_Type in module init
    .tp_doc = PyDoc_STR("my custom str"),
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_DISALLOW_INSTANTIATION,
    .tp_repr = (reprfunc)myobj_repr,
};

最简单的具有固定长度实例的静态类型

typedef struct {
    PyObject_HEAD
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
};

最简单的具有可变长度实例的静态类型

typedef struct {
    PyObject_VAR_HEAD
    const char *data[1];
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject) - sizeof(char *),
    .tp_itemsize = sizeof(char *),
};

类型对象¶

快速参考¶

“tp 插槽”¶

子插槽¶

插槽 typedef¶

PyTypeObject 定义¶

PyObject 插槽¶

PyVarObject 槽¶

PyTypeObject 槽¶

静态类型¶

堆类型¶

数值对象结构体¶

映射对象结构¶

序列对象结构¶

缓冲区对象结构¶

异步对象结构¶

槽类型 typedef¶

示例¶

目录

上一主题

下一主题

本页