类型对象结构¶

也许 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()`	__buffer__
`bf_releasebuffer`	`releasebufferproc()`	__release_buffer__

槽位 typedef¶

typedef	参数类型	返回类型
`allocfunc`	`PyTypeObject` * `Py_ssize_t`	`PyObject` *
`析构函数`	`PyObject` *	void
`freefunc`	void *	void
`traverseproc`	`PyObject` * `visitproc` void *	int
`newfunc`	`PyTypeObject` * `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/cpython/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 */
    PyMethodDef *tp_methods;
    PyMemberDef *tp_members;
    PyGetSetDef *tp_getset;
    // Strong reference on a heap type, borrowed reference on a static type
    PyTypeObject *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; /* no longer used */
    void *tp_subclasses;  /* for static builtin types this is an index */
    PyObject *tp_weaklist; /* not used for static builtin types */
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6.
     * If zero, the cache is invalid and must be initialized.
     */
    unsigned int tp_version_tag;

    destructor tp_finalize;
    vectorcallfunc tp_vectorcall;

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

    /* Number of tp_version_tag values used.
     * Set to _Py_ATTR_CACHE_UNUSED if the attribute cache is
     * disabled for this type (e.g. due to custom MRO entries).
     * Otherwise, limited to MAX_VERSIONS_PER_CLASS (defined elsewhere).
     */
    uint16_t tp_versions_used;
} PyTypeObject;

PyObject 槽位¶

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

PyObject.ob_refcnt

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

继承

此字段不被子类型继承。

PyObject.ob_type

这是类型的类型，换句话说就是它的元类型。它由 PyObject_HEAD_INIT 宏的参数初始化，其值通常应为 &PyType_Type。但是，对于必须在 Windows 上（至少）可用的动态可加载扩展模块，编译器会抱怨这不是一个有效的初始化器。因此，约定是将 NULL 传递给 PyObject_HEAD_INIT 宏，并在模块初始化函数的开头，在做任何其他事情之前，显式初始化此字段。这通常是这样做的
Foo_Type.ob_type = &PyType_Type;
这应该在创建类型的任何实例之前完成。PyType_Ready() 检查 ob_type 是否为 NULL，如果是，则将其初始化为基类的 ob_type 字段。PyType_Ready() 如果此字段非零，则不会更改此字段。

继承

此字段被子类型继承。

PyVarObject 槽位¶

PyVarObject.ob_size

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

此字段应使用 Py_SIZE() 宏访问。

继承

此字段不被子类型继承。

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 创建的模块文档中列出。

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

继承

此字段不被子类型继承。

Py_ssize_t PyTypeObject.tp_basicsize¶

Py_ssize_t PyTypeObject.tp_itemsize¶

这些字段允许计算类型实例的字节大小。

有两种类型的类型：固定长度实例的类型具有零 tp_itemsize 字段，可变长度实例的类型具有非零 tp_itemsize 字段。对于固定长度实例的类型，所有实例都具有相同的大小，在 tp_basicsize 中给出。（可以使用 PyUnstable_Object_GC_NewWithExtraData() 对此规则进行例外处理。）

对于可变长度实例的类型，实例必须具有 ob_size 字段，并且实例大小为 tp_basicsize 加上 N 乘以 tp_itemsize，其中 N 是对象的“长度”。

像 PyObject_NewVar() 这样的函数将以 N 的值作为参数，并将其存储在实例的 ob_size 字段中。请注意，ob_size 字段以后可能用于其他目的。例如，int 实例以实现定义的方式使用 ob_size 的位；应使用 PyLong_Export() 访问底层存储及其大小。

备注

ob_size 字段应使用 Py_SIZE() 和 Py_SET_SIZE() 宏访问。

此外，实例布局中存在 ob_size 字段并不意味着实例结构是可变长度的。例如，list 类型具有固定长度的实例，但这些实例具有 ob_size 字段。（与 int 一样，避免直接读取列表的 ob_size。而是调用 PyList_Size()。）

tp_basicsize 包括类型 tp_base 的数据所需的大小，以及每个实例所需的任何额外数据。

设置 tp_basicsize 的正确方法是对用于声明实例布局的结构使用 sizeof 运算符。此结构必须包含用于声明基类型的结构。换句话说，tp_basicsize 必须大于或等于基类的 tp_basicsize。

由于每个类型都是 object 的子类型，因此此结构必须包含 PyObject 或 PyVarObject（取决于是否应包含 ob_size）。这些通常分别由宏 PyObject_HEAD 或 PyObject_VAR_HEAD 定义。

基本大小不包括 GC 头大小，因为该头不是 PyObject_HEAD 的一部分。

对于用于声明基类型的结构未知的情况，请参阅 PyType_Spec.basicsize 和 PyType_FromMetaclass()。

关于对齐的注意事项

tp_basicsize 必须是 _Alignof(PyObject) 的倍数。当对包含 PyObject_HEAD 的 struct 使用 sizeof 时（如推荐的那样），编译器会确保这一点。不使用 C struct 时，或使用像 __attribute__((packed)) 这样的编译器扩展时，由您负责。
如果可变项需要特定的对齐方式，则 tp_basicsize 和 tp_itemsize 都必须是该对齐方式的倍数。例如，如果类型的可变部分存储 double，则您有责任确保这两个字段都是 _Alignof(double) 的倍数。

继承

这些字段由子类型单独继承。（也就是说，如果字段设置为零，PyType_Ready() 将从基类型复制该值，表示实例不需要额外的存储。）

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

destructor PyTypeObject.tp_dealloc¶

指向实例析构函数的指针。函数签名是

void tp_dealloc(PyObject *self);

析构函数应移除实例拥有的所有引用（例如，调用 Py_CLEAR()），释放实例拥有的所有内存缓冲区，并调用类型的 tp_free 函数以释放对象本身。

如果您可能调用可能设置错误指示器的函数，则必须使用 PyErr_GetRaisedException() 和 PyErr_SetRaisedException() 以确保您不会覆盖预先存在的错误指示器（在处理不同的错误时可能发生了解除分配）

static void
foo_dealloc(foo_object *self)
{
    PyObject *et, *ev, *etb;
    PyObject *exc = PyErr_GetRaisedException();
    ...
    PyErr_SetRaisedException(exc);
}

dealloc 处理程序本身不得引发异常；如果遇到错误情况，它应该调用 PyErr_FormatUnraisable() 来记录（并清除）一个不可引发的异常。

不保证何时销毁对象，除了

Python 将在删除对象的最终引用后立即或一段时间后销毁对象，除非其终结器（tp_finalize）随后复活了对象。
对象在自动终结（tp_finalize）或自动清除（tp_clear）时不会被销毁。

CPython 目前在 Py_DECREF() 中，当新的引用计数为零时立即销毁对象，但这可能会在将来的版本中改变。

建议在 tp_dealloc 的开头调用 PyObject_CallFinalizerFromDealloc()，以保证对象在销毁前始终被终结。

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

允许从 tp_dealloc 调用 tp_clear 以减少代码重复并保证对象在销毁前始终被清除。请注意，tp_clear 可能已经被调用。

如果类型是堆分配的（Py_TPFLAGS_HEAPTYPE），析构函数应在调用类型析构函数后释放其对类型对象拥有的引用（通过 Py_DECREF()）。请参阅下面的示例代码。

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

tp_dealloc 必须保持异常状态不变。如果它需要调用可能引发异常的东西，则必须首先备份异常状态，然后在以后恢复（在用 PyErr_WriteUnraisable() 记录任何异常之后）。

示例

static void
foo_dealloc(PyObject *self)
{
    PyObject *exc = PyErr_GetRaisedException();

    if (PyObject_CallFinalizerFromDealloc(self) < 0) {
        // self was resurrected.
        goto done;
    }

    PyTypeObject *tp = Py_TYPE(self);

    if (tp->tp_flags & Py_TPFLAGS_HAVE_GC) {
        PyObject_GC_UnTrack(self);
    }

    // Optional, but convenient to avoid code duplication.
    if (tp->tp_clear && tp->tp_clear(self) < 0) {
        PyErr_WriteUnraisable(self);
    }

    // Any additional destruction goes here.

    tp->tp_free(self);
    self = NULL;  // In case PyErr_WriteUnraisable() is called below.

    if (tp->tp_flags & Py_TPFLAGS_HEAPTYPE) {
        Py_CLEAR(tp);
    }

done:
    // Optional, if something was called that might have raised an
    // exception.
    if (PyErr_Occurred()) {
        PyErr_WriteUnraisable(self);
    }
    PyErr_SetRaisedException(exc);
}

tp_dealloc 可以在任何 Python 线程中调用，而不仅仅是创建对象的线程（如果对象成为引用计数循环的一部分，该循环可能会被任何线程上的垃圾回收收集）。这对于 Python API 调用来说不是问题，因为调用 tp_dealloc 的线程具有附加的线程状态。但是，如果被销毁的对象反过来销毁来自其他 C 库的对象，则应注意确保在调用 tp_dealloc 的线程上销毁这些对象不会违反库的任何假设。

继承

此字段被子类型继承。

参见

有关此槽位与其他槽位如何关联的详细信息，请参阅对象生命周期。

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¶

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

此字段已弃用。当它被定义时，它应该指向一个与 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 设置为 PyObject_HashNotImplemented() 将导致 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¶

指向 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。

默认

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¶

当对象支持垃圾回收时，此位被设置。如果此位被设置，则新实例的内存（参见 tp_alloc）必须使用 PyObject_GC_New 或 PyType_GenericAlloc() 分配，并使用 PyObject_GC_Del() 释放（参见 tp_free）。更多信息请参见支持循环垃圾回收一节。

继承

组：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。

类型遍历函数必须调用 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¶

当类实现矢量调用协议时，此位被设置。详见 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(PyObject *op, visitproc visit, void *arg)
{
    localobject *self = (localobject *) op;
    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 位，则遍历函数必须像这样调用 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 来委托此责任。如果它们不这样做，则类型对象可能不会被垃圾回收。

备注

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¶

指向清除函数的可选指针。其签名为

int tp_clear(PyObject *);

此函数的目的是打破导致循环隔离的引用循环，以便安全地销毁对象。清除的对象是部分销毁的对象；对象没有义务满足正常使用期间所保持的设计不变量。

tp_clear 不需要删除对不能参与引用循环的对象的引用，例如 Python 字符串或 Python 整数。但是，清除所有引用可能很方便，并且编写类型的 tp_dealloc 函数以调用 tp_clear 以避免代码重复。（请注意，tp_clear 可能已经调用过。优先调用幂等函数，如 Py_CLEAR()。）

任何非平凡的清理都应在 tp_finalize 中执行，而不是在 tp_clear 中执行。

备注

如果 tp_clear 未能打破引用循环，则循环隔离中的对象可能无限期地无法回收（“泄漏”）。参见 gc.garbage。

备注

被引用者（直接和间接）可能已经被清除；它们不保证处于一致状态。

备注

tp_clear 函数可以在任何线程中调用。

备注

不能保证对象在其析构函数（tp_dealloc）被调用之前自动清除。

此函数与析构函数（tp_dealloc）在以下方面有所不同

清除对象的目的是移除对可能参与引用循环的其他对象的引用。另一方面，析构函数的目的是一个超集：它必须释放其拥有的所有资源，包括对不能参与引用循环的对象的引用（例如，整数）以及对象自身的内存（通过调用 tp_free）。
当调用 tp_clear 时，其他对象可能仍然持有对正在清除的对象的引用。因此，tp_clear 不得释放对象自身的内存（tp_free）。另一方面，析构函数仅在没有（强）引用存在时才调用，因此必须通过释放对象来安全地销毁对象本身。
tp_clear 可能永远不会被自动调用。另一方面，对象的析构函数将在对象变为不可达后（即，不存在对该对象的引用，或者该对象是循环隔离的成员）的某个时间点自动调用。

Python 不保证何时、是否或多久自动清除一个对象，但以下情况除外：

如果一个对象是可达的，即存在对它的引用且它不是循环隔离的成员，Python 将不会自动清除它。
如果一个对象尚未被自动终结（参见 tp_finalize），Python 将不会自动清除它。（如果终结器使对象复活，则在清除之前，该对象可能会或可能不会再次自动终结。）
如果一个对象是循环隔离的成员，如果循环隔离的任何成员尚未被自动终结（tp_finalize），Python 将不会自动清除它。
Python 不会在其 tp_clear 函数的任何自动调用返回之前销毁对象。这确保了在 tp_clear 仍在执行时，打破引用循环的行为不会使 self 指针无效。
Python 不会自动并发调用 tp_clear 多次。

CPython 目前只根据需要自动清除对象，以打破循环隔离中的引用循环，但未来的版本可能会在对象销毁之前定期清除对象。

总而言之，系统中所有 tp_clear 函数必须结合起来打破所有引用循环。这很微妙，如有任何疑问，请提供一个 tp_clear 函数。例如，元组类型没有实现 tp_clear 函数，因为可以证明没有引用循环完全由元组组成。因此，其他类型的 tp_clear 函数负责打破任何包含元组的循环。这并不立即显而易见，并且很少有充分的理由避免实现 tp_clear。

tp_clear 的实现应放弃实例对其 Python 对象成员的引用，并将其指向这些成员的指针设置为 NULL，示例如下：

static int
local_clear(PyObject *op)
{
    localobject *self = (localobject *) op;
    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);

有关 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 不支持。这两种编译器在此特定行为上都严格符合标准。

因此，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_DICT 位和 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);

继承

静态子类型继承此槽，如果从 object 继承，它将是 PyType_GenericAlloc()。

堆子类型不继承此槽。

默认

对于堆子类型，此字段始终设置为 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);

此函数必须释放由 tp_alloc 分配的内存。

继承

静态子类型继承此槽，如果从 object 继承，它将是 PyObject_Free()。例外：如果类型支持垃圾回收（即，Py_TPFLAGS_HAVE_GC 标志在 tp_flags 中设置）并且它将继承 PyObject_Free()，则此槽不继承，而是默认为 PyObject_GC_Del()。

堆子类型不继承此槽。

默认

对于堆子类型，此槽默认为与 PyType_GenericAlloc() 和 Py_TPFLAGS_HAVE_GC 标志的值匹配的解除分配器。

对于静态子类型，此槽是继承的（见上文）。

inquiry PyTypeObject.tp_is_gc¶

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

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

int tp_is_gc(PyObject *self);

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

继承

此字段被子类型继承。

默认

此槽没有默认值。如果此字段为 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¶

指向实例终结函数的可选指针。这是 __del__() 特殊方法的 C 实现。其签名是

void tp_finalize(PyObject *self);

终结的主要目的是在对象被销毁之前，当对象及其直接或间接引用的任何其他对象仍处于一致状态时，执行任何必须执行的非平凡清理。终结器可以执行任意 Python 代码。

在 Python 自动终结对象之前，对象的某些直接或间接引用者可能已自行自动终结。但是，尚未自动清除任何引用者 (tp_clear)。

其他未终结的对象可能仍在使用已终结的对象，因此终结器必须使对象处于健全状态（例如，不变量仍然满足）。

备注

在 Python 自动终结对象之后，Python 可能会开始自动清除 (tp_clear) 对象及其引用者（直接和间接）。清除的对象不保证处于一致状态；已终结的对象必须能够容忍已清除的引用者。

备注

不保证对象在调用其析构函数 (tp_dealloc) 之前被自动终结。建议在 tp_dealloc 开始时调用 PyObject_CallFinalizerFromDealloc()，以保证对象在销毁之前始终被终结。

备注

tp_finalize 函数可以从任何线程调用，尽管 GIL 将被持有。

备注

tp_finalize 函数可以在关机期间调用，在某些全局变量被删除之后。有关详细信息，请参阅 __del__() 方法的文档。

当 Python 终结一个对象时，它会按以下算法执行

Python 可能会将对象标记为 finalized。目前，Python 总是标记其类型支持垃圾回收（即 Py_TPFLAGS_HAVE_GC 标志在 tp_flags 中设置）的对象，并且从不标记其他类型的对象；这可能会在未来版本中改变。
如果对象未标记为 finalized 且其 tp_finalize 终结器函数不为 NULL，则调用终结器函数。
如果终结器函数被调用，并且终结器使对象可达（即，存在对对象的引用，并且它不是循环隔离的成员），则称终结器已 resurrected 对象。关于终结器是否还可以通过向对象添加一个新的不使其可达的引用来复活对象，即对象（仍然）是循环隔离的成员，这是未指明的。
如果终结器复活了对象，则对象的待定销毁被取消，并且如果存在，对象的 finalized 标记可能会被删除。目前，Python 从不删除 finalized 标记；这可能会在未来版本中改变。

自动终结 是指 Python 执行的任何终结，但通过调用 PyObject_CallFinalizer() 或 PyObject_CallFinalizerFromDealloc() 除外。关于对象何时、是否或多久自动终结，不作任何保证，除了

如果对象可达（即，存在对它的引用，并且它不是循环隔离的成员），Python 将不会自动终结该对象。
如果终结对象不会将对象标记为 finalized，Python 将不会自动终结该对象。目前，这适用于其类型不支持垃圾回收的对象，即 Py_TPFLAGS_HAVE_GC 标志未设置的对象。此类对象仍然可以通过调用 PyObject_CallFinalizer() 或 PyObject_CallFinalizerFromDealloc() 来手动终结。
Python 不会同时自动终结循环隔离的任何两个成员。
Python 在自动清除 (tp_clear) 对象后，将不会自动终结该对象。
如果对象是循环隔离的成员，Python 在自动清除（参见 tp_clear）任何其他成员后，将不会自动终结它。
Python 将自动终结循环隔离的每个成员，然后才自动清除（参见 tp_clear）其中任何一个。
如果 Python 要自动清除一个对象 (tp_clear)，它将首先自动终结该对象。

Python 目前仅自动终结循环隔离的成员对象，但未来版本可能会在销毁前定期终结对象。

要手动终结对象，不要直接调用此函数；请改用 PyObject_CallFinalizer() 或 PyObject_CallFinalizerFromDealloc()。

tp_finalize 应该保持当前异常状态不变。编写非平凡终结器的推荐方法是在开始时通过调用 PyErr_GetRaisedException() 备份异常，并在结束时通过调用 PyErr_SetRaisedException() 恢复异常。如果在终结器中间遇到异常，请使用 PyErr_WriteUnraisable() 或 PyErr_FormatUnraisable() 记录并清除它。例如

static void
foo_finalize(PyObject *self)
{
    // Save the current exception, if any.
    PyObject *exc = PyErr_GetRaisedException();

    // ...

    if (do_something_that_might_raise() != success_indicator) {
        PyErr_WriteUnraisable(self);
        goto done;
    }

done:
    // Restore the saved exception.  This silently discards any exception
    // raised above, so be sure to call PyErr_WriteUnraisable first if
    // necessary.
    PyErr_SetRaisedException(exc);
}

继承

此字段被子类型继承。

在 3.4 版本加入。

3.8 版更改: 在 3.8 版之前，必须设置 Py_TPFLAGS_HAVE_FINALIZE 标志位才能使用此字段。现在不再需要。

参见

PEP 442：“安全对象终结”
有关此槽位与其他槽位如何关联的详细信息，请参阅对象生命周期。
PyObject_CallFinalizer()
PyObject_CallFinalizerFromDealloc()

vectorcallfunc PyTypeObject.tp_vectorcall¶

用于调用此类型对象（而不是实例）的矢量调用函数。换句话说，tp_vectorcall 可用于优化 type.__call__，它通常返回 type 的新实例。

与任何矢量调用函数一样，如果 tp_vectorcall 为 NULL，则使用 tp_call 协议（Py_TYPE(type)->tp_call）代替。

备注

矢量调用协议要求矢量调用函数具有与相应 tp_call 相同的行为。这意味着 type->tp_vectorcall 必须与 Py_TYPE(type)->tp_call 的行为匹配。

具体来说，如果 type 使用默认元类，则 type->tp_vectorcall 必须与 PyType_Type->tp_call 的行为相同，它

调用 type->tp_new，
如果结果是 type 的子类，则在 tp_new 的结果上调用 type->tp_init，并且
返回 tp_new 的结果。

通常，会覆盖 tp_vectorcall 以优化特定 tp_new 和 tp_init 的此过程。在为用户可子类化的类型执行此操作时，请注意两者都可以被覆盖（分别使用 __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 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)(PyTypeObject*, 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 Py_ssize_t (*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 槽位¶

静态类型¶

堆类型¶

数字对象结构¶

映射对象结构¶

序列对象结构¶

缓冲区对象结构¶

异步对象结构¶

槽类型定义¶

示例¶

目录

上一主题

下一主题

本页