类型对象

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 的一部分。

返回 type 的 tp_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 的一部分。

如果a是b的子类型，则返回真。

此函数只检查实际的子类型，这意味着不会在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_init 或 nb_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 用于构造结果类型对象。当 metaclass 为 NULL 时，元类是从 bases（或 Py_tp_base[s] 插槽，如果 bases 为 NULL，请参见下文）派生的。

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

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

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

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

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

• 不会在新类上调用 __new__()（并且它必须设置为 type.__new__）。

• 不会在新类上调用 __init__()。

• 不会在任何基类上调用 __init_subclass__()。

• 不会在新描述符上调用 __set_name__()。

在 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

• 基类不是可变大小的（其 tp_itemsize）。

• 请求的 PyType_Spec.basicsize 为正数，表明基类的内存布局是已知的。

• 请求的 PyType_Spec.basicsize 为零，表明子类不直接访问实例的内存。

• 使用 Py_TPFLAGS_ITEMS_AT_END 标志。

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 的命名方式与结构 PyTypeObject、PyNumberMethods、PySequenceMethods、PyMappingMethods 和 PyAsyncMethods 的字段名称相同，并在前面添加了 Py_ 前缀。例如，使用

• Py_tp_dealloc 设置 PyTypeObject.tp_dealloc

• Py_nb_add 设置 PyNumberMethods.nb_add

• Py_sq_length 设置 PySequenceMethods.sq_length

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

• tp_weaklistoffset（如果可能，请使用 Py_TPFLAGS_MANAGED_WEAKREF）

• tp_dictoffset（如果可能，请使用 Py_TPFLAGS_MANAGED_DICT）

• tp_vectorcall_offset（在 PyMemberDef 中使用 "__vectorcalloffset__"）

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

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

• tp_vectorcall（使用 tp_new 和/或 tp_init）

• 内部字段：tp_dict、tp_mro、tp_cache、tp_subclasses 和 tp_weaklist。

在某些平台上，设置 Py_tp_bases 或 Py_tp_base 可能存在问题。为了避免问题，请使用 PyType_FromSpecWithBases() 的 bases 参数。

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

在 3.11 版本中变更: bf_getbuffer 和 bf_releasebuffer 现在在 有限 API 中可用。

void *pfunc

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

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