类型对象

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 并设置异常。

在自由线程构建中，PyType_AddWatcher() 不是线程安全的，因此必须在启动时（在生成第一个线程之前）调用它。

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* 的回调函数将被调用。(如果连续修改 *type* 期间未调用 _PyType_Lookup()，回调函数可能只被调用一次；这是一个实现细节，可能会发生变化。)

扩展不应使用并非由先前对 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 的默认内存分配机制为新实例分配内存，将内存清零，然后通过调用 PyObject_Init() 或 PyObject_InitVar() 来初始化内存。

不要直接调用此函数为对象分配内存；而是调用类型的 tp_alloc 槽。

对于支持垃圾回收的类型（即设置了 Py_TPFLAGS_HAVE_GC 标志的类型），此函数的行为类似于 PyObject_GC_New 或 PyObject_GC_NewVar（但内存保证在初始化前清零），并且应与 tp_free 中的 PyObject_GC_Del() 成对使用。否则，其行为类似于 PyObject_New 或 PyObject_NewVar（但内存保证在初始化前清零），并且应与 tp_free 中的 PyObject_Free() 成对使用。

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 调用约定传递方法定义类的地方获取模块状态。

返回的引用是从 *type* 借用的，只要您持有 *type* 的引用，它就有效。不要使用 Py_DECREF() 或类似函数释放它。

在 3.11 版本中新增。

int PyType_GetBaseByToken(PyTypeObject *type, void *token, PyTypeObject **result)

自 3.14 版本以来，作为 稳定 ABI 的一部分。

在 *type* 的 方法解析顺序 中查找第一个超类，其 Py_tp_token 令牌等于给定的令牌。

• 如果找到，将 *result* 设置为其新的 强引用 并返回 1。

• 如果未找到，将 *result* 设置为 NULL 并返回 0。

• 如果发生错误，将 *result* 设置为 NULL 并返回 -1，同时设置异常。

*result* 参数可以为 NULL，在这种情况下不设置 *result*。如果您只需要返回值，请使用此方法。

*token* 参数不能为 NULL。

在 3.14 版本加入。

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。

参数 *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 的类已被弃用。

在 3.14 版本中变更: 不再允许创建其元类重写 tp_new 的类。

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 的类已被弃用。

在 3.14 版本中变更: 不再允许创建其元类重写 tp_new 的类。

PyObject *PyType_FromSpec(PyType_Spec *spec)

返回值: 新引用。 稳定ABI 的一部分。

等同于 PyType_FromMetaclass(NULL, NULL, spec, NULL)。

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

元类的 tp_new *被忽略*，这可能导致不完全初始化。创建其元类覆盖 tp_new 的类已被弃用。

在 3.14 版本中变更: 不再允许创建其元类重写 tp_new 的类。

int PyType_Freeze(PyTypeObject *type)

自 3.14 版本以来，作为 稳定 ABI 的一部分。

使类型不可变：设置 Py_TPFLAGS_IMMUTABLETYPE 标志。

*type* 的所有基类必须是不可变的。

成功时，返回 0。出错时，设置异常并返回 -1。

在类型变为不可变之前，不得使用该类型。例如，在类型变为不可变之前，不得创建类型实例。

在 3.14 版本加入。

type PyType_Spec

稳定 ABI 的一部分（包括所有成员）。

定义类型行为的结构。

const char *name

类型名称，用于设置 PyTypeObject.tp_name。

int basicsize

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

如果为零，则指定 tp_basicsize 应该被继承。

如果是负数，其绝对值指定了类的实例除了超类之外还需要多少空间。使用 PyObject_GetTypeData() 获取指向以这种方式保留的子类特定内存的指针。对于负数 basicsize，Python 会在需要时插入填充以满足 tp_basicsize 的对齐要求。

在 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

支持一个不对应 PyTypeObject 结构字段的附加槽

• Py_tp_token

以下“偏移量”字段无法使用 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_dict、tp_mro、tp_cache、tp_subclasses 和 tp_weaklist。

在某些平台上设置 Py_tp_bases 或 Py_tp_base 可能会出现问题。为避免问题，请改用 PyType_FromSpecWithBases() 的 *bases* 参数。

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

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

在 3.14 版本中变更: 字段 tp_vectorcall 现在可以使用 Py_tp_vectorcall 设置。有关详细信息，请参阅该字段的文档。

void *pfunc

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

*pfunc* 值不能为 NULL，以下槽除外

• Py_tp_doc

• Py_tp_token (为了清晰起见，最好使用 Py_TP_USE_SPEC 而不是 NULL)

Py_tp_token

一个 槽，用于记录类的静态内存布局 ID。

如果类的 PyType_Spec 是静态分配的，则可以使用特殊值 Py_TP_USE_SPEC 将令牌设置为该规范

static PyType_Slot foo_slots[] = {
   {Py_tp_token, Py_TP_USE_SPEC},

它也可以设置为任意指针，但您必须确保

• 指针的生命周期长于类，因此在类存在期间不会被其他东西重用。

• 它“属于”类所在的扩展模块，因此不会与其他扩展冲突。

使用 PyType_GetBaseByToken() 检查类的超类是否具有给定令牌——即检查内存布局是否兼容。

要获取给定类（不考虑超类）的令牌，请使用 PyType_GetSlot() 和 Py_tp_token。

在 3.14 版本加入。

Py_TP_USE_SPEC

用作 Py_tp_token 的值，将令牌设置为类的 PyType_Spec。展开为 NULL。

在 3.14 版本加入。