类型对象

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 的替代方案。返回的字典必须被视为只读。

此函数用于特定的嵌入和语言绑定情况，在这种情况下，直接访问 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_AddWatcher() 返回给它的 *watcher_id* 调用 PyType_ClearWatcher。

在 3.12 版本中加入。

int PyType_Watch(int watcher_id, PyObject *type)

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

扩展不应使用未通过先前调用 PyType_AddWatcher() 返回给它的 *watcher_id* 调用 PyType_Watch。

在 3.12 版本中加入。

typedef int (*PyType_WatchCallback)(PyObject *type)

类型监视器回调函数的类型。

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

在 3.12 版本中加入。

int PyType_HasFeature(PyTypeObject *o, int feature)

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

int PyType_IS_GC(PyTypeObject *o)

如果类型对象包含对循环检测器的支持，则返回 true；这将测试类型标志 Py_TPFLAGS_HAVE_GC。

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

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

此函数仅检查实际的子类型，这意味着不会在 *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，那么它必须通过至少实现 tp_traverse 处理程序来实现 GC 协议本身。

PyObject *PyType_GetName(PyTypeObject *type)
返回值：新引用。 自 3.11 版本起，属于 稳定 ABI 的一部分。

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

3.11 版本新增。

PyObject *PyType_GetQualName(PyTypeObject *type)
返回值：新引用。 自 3.11 版本起，属于 稳定 ABI 的一部分。

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

3.11 版本新增。

PyObject *PyType_GetFullyQualifiedName(PyTypeObject *type)
自 3.13 版本起，属于 稳定 ABI 的一部分。

返回类型的完全限定名称。等效于 f"{type.__module__}.{type.__qualname__}"，如果 type.__module__ 不是字符串或等于 "builtins"，则等效于 type.__qualname__。

3.13 版本新增。

PyObject *PyType_GetModuleName(PyTypeObject *type)
自 3.13 版本起，属于 稳定 ABI 的一部分。

返回类型的模块名称。等效于获取 type.__module__ 属性。

3.13 版本新增。

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 以获取定义该方法的类。对于无法使用 PyCMethod 的情况，请参阅 PyType_GetModuleByDef()。

3.9 版本中新增。

void *PyType_GetModuleState(PyTypeObject *type)
自 3.10 版本起，属于 稳定 ABI 的一部分。

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

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

如果 type 有关联的模块，但其状态为 NULL，则返回 NULL，而不会设置异常。

3.9 版本中新增。

PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
自 3.13 版本起，属于 稳定 ABI 的一部分。

查找其模块是使用给定的 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 派生（如果 bases 为 NULL，则从 Py_tp_base[s] 槽派生，见下文）。

不支持重写 tp_new 的元类，除非 tp_new 为 NULL。（为了向后兼容，其他 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* 函数。具体来说

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

以下“offset”字段不能使用 PyType_Slot 设置

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

在创建堆类型时，以下字段完全不能设置

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

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

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

void *pfunc

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

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