类型对象

type PyTypeObject
作为不透明结构体,是 受限 API 的一部分。

用于描述内置类型的对象的 C 结构。

PyTypeObject PyType_Type
稳定 ABI 的一部分。

这是类型对象的类型对象;它与 Python 层中的 type 是同一个对象。

int PyType_Check(PyObject *o)

如果对象 o 是类型对象(包括从标准类型对象派生的类型的实例),则返回非零值。在所有其他情况下返回 0。此函数始终成功。

int PyType_CheckExact(PyObject *o)

如果对象 o 是类型对象,但不是标准类型对象的子类型,则返回非零值。在所有其他情况下返回 0。此函数始终成功。

unsigned int PyType_ClearCache()
稳定 ABI 的一部分。

清除内部查找缓存。返回当前版本标签。

unsigned long PyType_GetFlags(PyTypeObject *type)
稳定 ABI 的一部分。

返回 typetp_flags 成员。此函数主要用于 Py_LIMITED_API;各个标志位保证在 Python 版本之间保持稳定,但对 tp_flags 本身的访问不是 受限 API 的一部分。

在版本 3.2 中添加。

在版本 3.4 中更改: 返回类型现在是 unsigned long 而不是 long

PyObject *PyType_GetDict(PyTypeObject *type)

返回类型对象的内部命名空间,否则只能通过只读代理 (cls.__dict__) 访问。这是直接访问 tp_dict 的替代方法。返回的字典必须被视为只读。

此函数适用于特定的嵌入和语言绑定情况,在这些情况下需要直接访问字典,而间接访问(例如通过代理或 PyObject_GetAttr())不足。

扩展模块在设置自己的类型时,应继续直接或间接使用 tp_dict

在 3.12 版本中添加。

void PyType_Modified(PyTypeObject *type)
稳定 ABI 的一部分。

使类型及其所有子类型的内部查找缓存失效。在手动修改类型的属性或基类后,必须调用此函数。

int PyType_AddWatcher(PyType_WatchCallback callback)

注册 callback 作为类型观察者。返回一个非负整数 ID,该 ID 必须传递给将来对 PyType_Watch() 的调用。如果发生错误(例如没有更多观察者 ID 可用),则返回 -1 并设置异常。

在 3.12 版本中添加。

int PyType_ClearWatcher(int watcher_id)

清除由 watcher_id 标识的观察者(先前从 PyType_AddWatcher() 返回)。成功时返回 0,错误时返回 -1(例如,如果 watcher_id 从未注册)。

扩展程序永远不应该使用 PyType_ClearWatcher 调用一个 watcher_id,该 watcher_id 不是由先前对 PyType_AddWatcher() 的调用返回给它的。

在 3.12 版本中添加。

int PyType_Watch(int watcher_id, PyObject *type)

type标记为已观察。每当PyType_Modified()报告对type的更改时,由PyType_AddWatcher()授予的回调watcher_id将被调用。(如果在对type进行一系列连续修改之间没有在type上调用_PyType_Lookup(),则回调可能只对type的一系列连续修改调用一次;这是一个实现细节,可能会发生变化。)

扩展程序永远不应该使用PyType_AddWatcher()之前调用返回给它的watcher_id调用PyType_Watch

在 3.12 版本中添加。

typedef int (*PyType_WatchCallback)(PyObject *type)

类型观察器回调函数的类型。

回调不得修改type或导致PyType_Modified()type或其MRO中的任何类型上被调用;违反此规则会导致无限递归。

在 3.12 版本中添加。

int PyType_HasFeature(PyTypeObject *o, int feature)

如果类型对象o设置了特性feature,则返回非零值。类型特性由单个位标志表示。

int PyType_IS_GC(PyTypeObject *o)

如果类型对象包含对循环检测器的支持,则返回真;这测试类型标志Py_TPFLAGS_HAVE_GC

int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
稳定 ABI 的一部分。

如果ab的子类型,则返回真。

此函数只检查实际的子类型,这意味着不会在b上调用__subclasscheck__()。调用PyObject_IsSubclass()来执行与issubclass()相同的检查。

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
返回值:新引用。稳定 ABI 的一部分。

类型对象的 tp_alloc 槽的通用处理程序。使用 Python 的默认内存分配机制分配一个新实例,并将所有内容初始化为 NULL

PyObject *PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
返回值:新引用。稳定 ABI 的一部分。

类型对象的 tp_new 槽的通用处理程序。使用类型的 tp_alloc 槽创建一个新实例。

int PyType_Ready(PyTypeObject *type)
稳定 ABI 的一部分。

完成类型对象的初始化。这应该在所有类型对象上调用以完成它们的初始化。此函数负责从类型的基类添加继承的槽。成功时返回 0,或在错误时返回 -1 并设置异常。

注意

如果一些基类实现了 GC 协议,而提供的类型没有在其标志中包含 Py_TPFLAGS_HAVE_GC,那么 GC 协议将自动从其父类中实现。相反,如果正在创建的类型在其标志中包含 Py_TPFLAGS_HAVE_GC,那么它 **必须** 自己实现 GC 协议,至少要实现 tp_traverse 处理程序。

PyObject *PyType_GetName(PyTypeObject *type)
返回值:新引用。 从版本 3.11 开始是 稳定 ABI 的一部分。

返回类型的名称。等效于获取类型的 __name__ 属性。

在版本 3.11 中添加。

PyObject *PyType_GetQualName(PyTypeObject *type)
返回值:新引用。 从版本 3.11 开始是 稳定 ABI 的一部分。

返回类型的限定名称。等效于获取类型的 __qualname__ 属性。

在版本 3.11 中添加。

void *PyType_GetSlot(PyTypeObject *type, int slot)
从版本 3.4 开始,作为 稳定 ABI 的一部分。

返回存储在给定槽中的函数指针。如果结果为 NULL,则表示该槽为 NULL,或者使用无效参数调用了该函数。调用者通常会将结果指针转换为相应的函数类型。

有关 slot 参数的可能值,请参见 PyType_Slot.slot

在版本 3.4 中添加。

在版本 3.10 中更改:PyType_GetSlot() 现在可以接受所有类型。以前,它仅限于 堆类型

PyObject *PyType_GetModule(PyTypeObject *type)
从版本 3.10 开始,作为 稳定 ABI 的一部分。

返回与给定类型关联的模块对象,当使用 PyType_FromModuleAndSpec() 创建该类型时。

如果与给定类型没有关联的模块,则设置 TypeError 并返回 NULL

此函数通常用于获取定义方法的模块。请注意,在这样的方法中,PyType_GetModule(Py_TYPE(self)) 可能不会返回预期的结果。 Py_TYPE(self) 可能是预期类的 *子类*,子类不一定在与其超类相同的模块中定义。请参见 PyCMethod 以获取定义该方法的类。请参见 PyType_GetModuleByDef(),了解无法使用 PyCMethod 的情况。

在版本 3.9 中添加。

void *PyType_GetModuleState(PyTypeObject *type)
从版本 3.10 开始,作为 稳定 ABI 的一部分。

返回与给定类型关联的模块对象的 state。这是对 PyModule_GetState() 的结果调用 PyType_GetModule() 的快捷方式。

如果与给定类型没有关联的模块,则设置 TypeError 并返回 NULL

如果 type 有关联的模块,但其 state 为 NULL,则返回 NULL 而不设置异常。

在版本 3.9 中添加。

PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)

查找第一个其模块由给定 PyModuleDef def 创建的超类,并返回该模块。

如果未找到模块,则会引发 TypeError 并返回 NULL

此函数旨在与 PyModule_GetState() 一起使用,以从插槽方法(例如 tp_initnb_add)以及其他方法的定义类无法使用 PyCMethod 调用约定传递的地方获取模块状态。

在版本 3.11 中添加。

int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)
这是 不稳定 API。它可能会在次要版本中发生更改,恕不另行通知。

尝试为给定类型分配版本标签。

如果类型已经具有有效的版本标签或已分配了新的版本标签,则返回 1;如果无法分配新的标签,则返回 0。

在 3.12 版本中添加。

创建堆分配类型

以下函数和结构用于创建 堆类型

PyObject *PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
自版本 3.12 起,它是 稳定 ABI 的一部分。

spec 创建并返回 堆类型(参见 Py_TPFLAGS_HEAPTYPE)。

元类 metaclass 用于构造结果类型对象。当 metaclassNULL 时,元类是从 bases(或 Py_tp_base[s] 插槽,如果 basesNULL,请参见下文)派生的。

除了 tp_newNULL 之外,不支持覆盖 tp_new 的元类。(为了向后兼容性,其他 PyType_From* 函数允许这种元类。它们会忽略 tp_new,这可能会导致初始化不完整。这已过时,在 Python 3.14+ 中将不支持这种元类。)

bases 参数可用于指定基类;它可以是单个类或类元组。如果 basesNULL,则使用 Py_tp_bases 槽。如果该槽也为 NULL,则使用 Py_tp_base 槽。如果该槽也为 NULL,则新类型将从 object 派生。

module 参数可用于记录定义新类的模块。它必须是模块对象或 NULL。如果非 NULL,则模块与新类型相关联,并且可以使用 PyType_GetModule() 稍后检索。关联的模块不会被子类继承;它必须为每个类单独指定。

此函数在新类型上调用 PyType_Ready()

请注意,此函数的行为与调用 type() 或使用 class 语句的行为不完全匹配。对于用户提供的基类型或元类,请优先使用 调用 type(或元类)而不是 PyType_From* 函数。具体来说

在 3.12 版本中添加。

PyObject *PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
返回值:新引用。自版本 3.10 起,是 稳定 ABI 的一部分。

等效于 PyType_FromMetaclass(NULL, module, spec, bases)

在版本 3.9 中添加。

在版本 3.10 中更改:该函数现在接受单个类作为 bases 参数,并接受 NULL 作为 tp_doc 槽。

版本 3.12 中的变更: 该函数现在会找到并使用与提供的基类相对应的元类。以前,只返回 type 实例。

元类的 tp_new忽略,这可能会导致初始化不完整。创建元类覆盖 tp_new 的类已弃用,在 Python 3.14 及更高版本中将不再允许。

PyObject *PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
返回值: 新引用。 从版本 3.3 开始是 稳定 ABI 的一部分。

等效于 PyType_FromMetaclass(NULL, NULL, spec, bases)

在版本 3.3 中添加。

版本 3.12 中的变更: 该函数现在会找到并使用与提供的基类相对应的元类。以前,只返回 type 实例。

元类的 tp_new忽略,这可能会导致初始化不完整。创建元类覆盖 tp_new 的类已弃用,在 Python 3.14 及更高版本中将不再允许。

PyObject *PyType_FromSpec(PyType_Spec *spec)
返回值:新引用。稳定 ABI 的一部分。

等效于 PyType_FromMetaclass(NULL, NULL, spec, NULL)

版本 3.12 中的变更: 该函数现在会找到并使用在 Py_tp_base[s] 槽中提供的基类相对应的元类。以前,只返回 type 实例。

元类的 tp_new忽略,这可能会导致初始化不完整。创建元类覆盖 tp_new 的类已弃用,在 Python 3.14 及更高版本中将不再允许。

type PyType_Spec
稳定 ABI 的一部分(包括所有成员)。

定义类型的行为的结构。

const char *name

类型的名称,用于设置 PyTypeObject.tp_name

int basicsize

如果为正数,则指定实例的大小(以字节为单位)。它用于设置 PyTypeObject.tp_basicsize

如果为零,则指定应继承 tp_basicsize

如果为负数,则绝对值指定类的实例除了超类之外还需要多少空间。使用 PyObject_GetTypeData() 获取指向以这种方式保留的特定于子类的内存的指针。

版本 3.12 中的变更: 以前,此字段不能为负数。

int itemsize

变量大小类型中一个元素的大小(以字节为单位)。用于设置 PyTypeObject.tp_itemsize。有关注意事项,请参阅 tp_itemsize 文档。

如果为零,则 tp_itemsize 将被继承。扩展任意可变大小的类很危险,因为某些类型使用固定偏移量来存储可变大小的内存,这可能会与子类使用的固定大小内存发生重叠。为了防止错误,仅在以下情况下才能继承 itemsize

unsigned int flags

类型标志,用于设置 PyTypeObject.tp_flags

如果未设置 Py_TPFLAGS_HEAPTYPE 标志,则 PyType_FromSpecWithBases() 会自动设置它。

PyType_Slot *slots

PyType_Slot 结构的数组。以特殊插槽值 {0, NULL} 结束。

每个插槽 ID 应该最多指定一次。

type PyType_Slot
稳定 ABI 的一部分(包括所有成员)。

定义类型可选功能的结构,包含插槽 ID 和值指针。

int slot

插槽 ID。

插槽 ID 的命名方式与结构 PyTypeObjectPyNumberMethodsPySequenceMethodsPyMappingMethodsPyAsyncMethods 的字段名称相同,并在前面添加了 Py_ 前缀。例如,使用

以下“偏移量”字段不能使用 PyType_Slot 设置

如果无法切换到 MANAGED 标志(例如,对于 vectorcall 或支持低于 3.12 的 Python 版本),请在 Py_tp_members 中指定偏移量。有关详细信息,请参阅 PyMemberDef 文档

在创建堆类型时,以下字段无法设置。

在某些平台上,设置 Py_tp_basesPy_tp_base 可能存在问题。为了避免问题,请使用 PyType_FromSpecWithBases()bases 参数。

在 3.9 版本中变更: 在无限 API 中可以设置 PyBufferProcs 中的插槽。

在 3.11 版本中变更: bf_getbufferbf_releasebuffer 现在在 有限 API 中可用。

void *pfunc

插槽的期望值。在大多数情况下,这是一个指向函数的指针。

除了 Py_tp_doc 之外的插槽不能为 NULL