类型对象¶

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

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

除了以下快速参考之外，“示例”部分还提供了一些关于 PyTypeObject 的含义和用法的概览。

快速参考¶

“tp slots”¶

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	参数类型	返回类型
`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

有关更多详细信息，请参阅下面的插槽类型类型定义。

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 字段。如果 ob_type 不为零，则 PyType_Ready() 不会更改此字段。

继承

此字段由子类型继承。

PyObject *PyObject._ob_next¶

PyObject *PyObject._ob_prev¶

这些字段仅在定义了宏 Py_TRACE_REFS 时才会出现（请参阅 configure --with-trace-refs option）。

PyObject_HEAD_INIT 宏负责将它们初始化为 NULL。对于静态分配的对象，这些字段始终保持 NULL。对于动态分配的对象，这两个字段用于将对象链接到堆上*所有*活动对象的双向链表中。

这可以用于各种调试目的；目前唯一的用途是 sys.getobjects() 函数，以及在设置了环境变量 PYTHONDUMPREFS 的情况下打印运行结束时仍然存在的对象。

继承

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

PyVarObject 插槽¶

Py_ssize_t PyVarObject.ob_size¶

稳定 ABI 的一部分。

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

继承

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

PyTypeObject 插槽¶

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

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__ 属性未定义（除非在字典中显式设置，如上所述）。这意味着您的类型将无法被 pickle。此外，它也不会列在使用 pydoc 创建的模块文档中。

此字段不能为空。它是 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 的对齐要求）。

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

继承

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

析构函数 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);
}

继承

此字段由子类型继承。

Py_ssize_t PyTypeObject.tp_vectorcall_offset¶

一个可选的偏移量，指向一个实例函数，该函数使用向量调用协议实现对对象的调用，这是比简单的 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 版之前，不建议可变堆类型实现向量调用协议。当用户在 Python 代码中设置 __call__ 时，只会更新 tp_call，这可能会使其与向量调用函数不一致。从 3.12 开始，设置 __call__ 将通过清除 Py_TPFLAGS_HAVE_VECTORCALL 标志来禁用向量调用优化。

继承

此字段始终会被继承。但是，Py_TPFLAGS_HAVE_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() 时，将返回一个具有相同值的 object。如果不可行，则应返回以 '<' 开头并以 '>' 结尾的字符串，从中可以推断出对象的类型和值。

继承

此字段由子类型继承。

默认

如果未设置此字段，则返回 <%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。

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¶

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

签名与 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'ed)，而在销毁实例时，类型对象的引用计数会减少 (DECREF'ed)（这不适用于子类型的实例；只有实例的 ob_type 引用的类型才会增加或减少引用计数）。堆类型还应支持垃圾回收，因为它们可以与其自己的模块对象形成循环引用。

继承

???

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¶

此位指示类的实例具有 __dict__ 属性，并且字典的空间由 VM 管理。

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

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¶

当类实现向量调用协议时，将设置此位。有关详细信息，请参阅 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() 函数会将其包含在内。

警告

实现 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 中，由于 bug 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_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，而没有定义 tp_richcompare，则即使是继承的函数也不会被使用，并且该类型的实例将无法参与任何比较。

Py_ssize_t PyTypeObject.tp_weaklistoffset¶

虽然此字段仍然受支持，但应尽可能使用 Py_TPFLAGS_MANAGED_WEAKREF 来代替。

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

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

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

继承

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

默认

如果在 tp_dict 字段中设置了 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 不支持。这两种编译器在这种特定行为中都严格符合标准。

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

继承

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

默认

此字段默认为 &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() 将为其分配一个新字典。

警告

在 tp_dict 上使用 PyDict_SetItem() 或使用字典 C-API 对其进行修改是不安全的。

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__。

如果在 tp_dict 字段中设置了 Py_TPFLAGS_MANAGED_DICT 位，则 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);

继承

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

默认

对于动态子类型，此字段始终设置为 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()。

继承

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

默认

在动态子类型中，此字段设置为适合匹配 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 slot 来代替 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);
}

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

继承

此字段由子类型继承。

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 的一部分。
返回对象名为 attribute 的属性的值。

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

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

稳定 ABI 的一部分。

返回对象名为 attribute 的属性的值。

参见 tp_getattro。

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

稳定 ABI 的一部分。

设置对象名为 attribute 的属性的值。 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 slots”¶

子槽¶

插槽类型定义¶

PyTypeObject 定义¶

PyObject 插槽¶

PyVarObject 插槽¶

PyTypeObject 插槽¶

静态类型¶

堆类型¶

数字对象结构¶

映射对象结构¶

序列对象结构¶

缓冲区对象结构¶

异步对象结构¶

槽类型 typedef¶

示例¶

目录

上一主题

下一主题

本页