通用对象结构

在 Python 的对象类型定义中使用了大量的结构体。本节描述了这些结构体以及它们的使用方式。

基本对象类型和宏

所有 Python 对象最终都在内存中对象表示的开头共享少量的字段。这些字段由 PyObject 和 PyVarObject 类型表示，而这两个类型又是通过一些宏的扩展来定义的，这些宏也直接或间接地用于所有其他 Python 对象的定义中。更多宏可以在 引用计数 下找到。

type PyObject

有限 API 的一部分。（只有一部分成员是稳定 ABI 的一部分。）

所有对象类型都是此类型的扩展。此类型包含 Python 将指向对象的指针视为对象所需的信息。在正常的“发布”构建中，它只包含对象的引用计数和指向相应类型对象的指针。实际上没有任何内容被声明为 PyObject，但每个指向 Python 对象的指针都可以转换为 PyObject*。必须使用宏 Py_REFCNT 和 Py_TYPE 来访问成员。

type PyVarObject

有限 API 的一部分。（只有一部分成员是稳定 ABI 的一部分。）

这是 PyObject 的扩展，它添加了 ob_size 字段。这仅用于具有一定*长度*概念的对象。此类型在 Python/C API 中并不常见。必须使用宏 Py_REFCNT、Py_TYPE 和 Py_SIZE 来访问成员。

PyObject_HEAD

这是一个宏，用于声明表示长度不固定的对象的类型。PyObject_HEAD 宏展开为

PyObject ob_base;

请参阅上面 PyObject 的文档。

PyObject_VAR_HEAD

这是一个宏，用于声明表示长度随实例而异的对象的类型。PyObject_VAR_HEAD 宏展开为

PyVarObject ob_base;

请参阅上面 PyVarObject 的文档。

int Py_Is(PyObject *x, PyObject *y)

从版本 3.10 开始成为 稳定 ABI 的一部分。

测试 x 对象是否为 y 对象，与 Python 中的 x is y 相同。

3.10 版新增。

int Py_IsNone(PyObject *x)

从版本 3.10 开始成为 稳定 ABI 的一部分。

测试对象是否为 None 单例，与 Python 中的 x is None 相同。

3.10 版新增。

int Py_IsTrue(PyObject *x)

从版本 3.10 开始成为 稳定 ABI 的一部分。

测试对象是否为 True 单例，与 Python 中的 x is True 相同。

3.10 版新增。

int Py_IsFalse(PyObject *x)

从版本 3.10 开始成为 稳定 ABI 的一部分。

测试对象是否为 False 单例，与 Python 中的 x is False 相同。

3.10 版新增。

PyTypeObject *Py_TYPE(PyObject *o)

获取 Python 对象 o 的类型。

返回一个 借用引用。

使用 Py_SET_TYPE() 函数设置对象类型。

在 3.11 版更改: Py_TYPE() 已更改为内联静态函数。参数类型不再是 const PyObject*。

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)

如果对象 o 的类型是 type，则返回非零值。否则返回零。等效于：Py_TYPE(o) == type。

3.9 版新增。

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)

将对象 o 的类型设置为 type。

3.9 版新增。

Py_ssize_t Py_SIZE(PyVarObject *o)

获取 Python 对象 o 的大小。

使用 Py_SET_SIZE() 函数设置对象大小。

在 3.11 版更改: Py_SIZE() 已更改为内联静态函数。参数类型不再是 const PyVarObject*。

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)

将对象 o 的大小设置为 size。

3.9 版新增。

PyObject_HEAD_INIT(type)

这是一个宏，它扩展为新 PyObject 类型的初始化值。此宏扩展为

_PyObject_EXTRA_INIT
1, type,

PyVarObject_HEAD_INIT(type, size)

这是一个宏，它扩展为新 PyVarObject 类型的初始化值，包括 ob_size 字段。此宏扩展为

_PyObject_EXTRA_INIT
1, type, size,

实现函数和方法

type PyCFunction

稳定 ABI 的一部分。

用于在 C 中实现大多数 Python 可调用对象的函数类型。此类型的函数接受两个 PyObject* 参数并返回一个这样的值。如果返回值为 NULL，则应设置异常。如果不是 NULL，则返回值将解释为 Python 中公开的函数的返回值。该函数必须返回一个新引用。

函数签名为

PyObject *PyCFunction(PyObject *self,
                      PyObject *args);

type PyCFunctionWithKeywords

稳定 ABI 的一部分。

用于在 C 中实现带有签名 METH_VARARGS | METH_KEYWORDS 的 Python 可调用对象的函数类型。函数签名为

PyObject *PyCFunctionWithKeywords(PyObject *self,
                                  PyObject *args,
                                  PyObject *kwargs);

type _PyCFunctionFast

用于在 C 中实现带有签名 METH_FASTCALL 的 Python 可调用对象的函数类型。函数签名为

PyObject *_PyCFunctionFast(PyObject *self,
                           PyObject *const *args,
                           Py_ssize_t nargs);

type _PyCFunctionFastWithKeywords

用于在 C 中实现带有签名 METH_FASTCALL | METH_KEYWORDS 的 Python 可调用对象的函数类型。函数签名为

PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
                                       PyObject *const *args,
                                       Py_ssize_t nargs,
                                       PyObject *kwnames);

type PyCMethod

用于在 C 中实现带有签名 METH_METHOD | METH_FASTCALL | METH_KEYWORDS 的 Python 可调用对象的函数类型。函数签名为

PyObject *PyCMethod(PyObject *self,
                    PyTypeObject *defining_class,
                    PyObject *const *args,
                    Py_ssize_t nargs,
                    PyObject *kwnames)

3.9 版新增。

type PyMethodDef

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

用于描述扩展类型的方法的结构。此结构有四个字段

const char *ml_name

方法的名称。

PyCFunction ml_meth

指向 C 实现的指针。

int ml_flags

指示如何构造调用的标志位。

const char *ml_doc

指向文档字符串的内容。

ml_meth 是一个 C 函数指针。函数可以是不同类型的，但它们总是返回 PyObject*。如果函数不是 PyCFunction 类型的，编译器将需要在方法表中进行强制转换。即使 PyCFunction 将第一个参数定义为 PyObject*，但方法实现通常使用 self 对象的特定 C 类型。

ml_flags 字段是一个位域，可以包含以下标志。各个标志表示调用约定或绑定约定。

以下是调用约定

METH_VARARGS

这是典型的调用约定，其中方法的类型为 PyCFunction。该函数需要两个 PyObject* 值。第一个是方法的 self 对象；对于模块函数，它是模块对象。第二个参数（通常称为 args）是一个元组对象，表示所有参数。此参数通常使用 PyArg_ParseTuple() 或 PyArg_UnpackTuple() 进行处理。

METH_KEYWORDS

只能与其他标志组合使用：METH_VARARGS | METH_KEYWORDS、METH_FASTCALL | METH_KEYWORDS 和 METH_METHOD | METH_FASTCALL | METH_KEYWORDS。

METH_VARARGS | METH_KEYWORDS

具有这些标志的方法必须是 PyCFunctionWithKeywords 类型。该函数需要三个参数：self、args、kwargs，其中 kwargs 是所有关键字参数的字典，如果没有关键字参数，则可能为 NULL。这些参数通常使用 PyArg_ParseTupleAndKeywords() 进行处理。

METH_FASTCALL

快速调用约定，仅支持位置参数。这些方法的类型为 _PyCFunctionFast。第一个参数是 self，第二个参数是一个 PyObject* 值的 C 数组，表示参数，第三个参数是参数的数量（数组的长度）。

3.7 版的新功能。

在 3.10 版更改: METH_FASTCALL 现在是 稳定 ABI 的一部分。

METH_FASTCALL | METH_KEYWORDS

METH_FASTCALL 的扩展，也支持关键字参数，方法类型为 _PyCFunctionFastWithKeywords。关键字参数的传递方式与 向量调用协议 相同：有一个额外的第四个 PyObject* 参数，它是一个元组，表示关键字参数的名称（保证是字符串），如果没有关键字，则可能为 NULL。关键字参数的值存储在 args 数组中，位于位置参数之后。

3.7 版的新功能。

METH_METHOD

只能与其他标志组合使用：METH_METHOD | METH_FASTCALL | METH_KEYWORDS。

METH_METHOD | METH_FASTCALL | METH_KEYWORDS

METH_FASTCALL | METH_KEYWORDS 的扩展，支持*定义类*，即包含相关方法的类。定义类可能是 Py_TYPE(self) 的超类。

该方法需要是 PyCMethod 类型，与 METH_FASTCALL | METH_KEYWORDS 相同，并在 self 之后添加了 defining_class 参数。

3.9 版新增。

METH_NOARGS

如果没有参数，则如果方法使用 METH_NOARGS 标志列出，则无需检查是否提供了参数。它们需要是 PyCFunction 类型。第一个参数通常命名为 self，它将保存对模块或对象实例的引用。在所有情况下，第二个参数都将是 NULL。

该函数必须有两个参数。由于第二个参数未使用，可以使用 Py_UNUSED 来防止编译器警告。

METH_O

可以使用 METH_O 标志列出具有单个对象参数的方法，而不是使用 "O" 参数调用 PyArg_ParseTuple()。它们的类型为 PyCFunction，带有 self 参数和一个表示单个参数的 PyObject* 参数。

这两个常量不用于指示调用约定，而是用于指示与类方法一起使用时的绑定。这些不能用于为模块定义的函数。对于任何给定方法，最多可以设置其中一个标志。

METH_CLASS

该方法将传递类型对象作为第一个参数，而不是类型的实例。这用于创建*类方法*，类似于使用 classmethod() 内置函数创建的方法。

METH_STATIC

该方法将传递 NULL 作为第一个参数，而不是该类型的实例。这用于创建*静态方法*，类似于使用 staticmethod() 内置函数创建的方法。

另一个常量控制是否加载一个方法来代替具有相同方法名称的另一个定义。

METH_COEXIST

该方法将加载到现有定义的位置。如果没有 METH_COEXIST，则默认行为是跳过重复的定义。由于槽包装器在方法表之前加载，因此例如 sq_contains 槽的存在将生成一个名为 __contains__() 的包装方法，并阻止加载具有相同名称的相应 PyCFunction。定义了该标志后，PyCFunction 将加载到包装器对象的位置，并将与该槽共存。这很有帮助，因为对 PyCFunction 的调用比包装器对象调用优化得更多。

PyObject *PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)

返回值：新的引用。 从版本 3.9 开始成为 稳定 ABI 的一部分。

将 ml 转换为 Python 可调用对象。调用者必须确保 ml 比 可调用对象 的寿命长。通常，ml 被定义为静态变量。

调用时，self 参数将作为 self 参数传递给 ml->ml_meth 中的 C 函数。self 可以是 NULL。

可调用对象 的 __module__ 属性可以从给定的 module 参数设置。module 应该是一个 Python 字符串，它将用作定义该函数的模块的名称。如果不可用，可以将其设置为 None 或 NULL。

另请参阅

function.__module__

cls 参数将作为 defining_class 参数传递给 C 函数。如果在 ml->ml_flags 上设置了 METH_METHOD，则必须设置该参数。

3.9 版新增。

PyObject *PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)

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

等效于 PyCMethod_New(ml, self, module, NULL)。

PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)

返回值：新的引用。 从版本 3.4 开始成为 稳定 ABI 的一部分。

等效于 PyCMethod_New(ml, self, NULL, NULL)。

访问扩展类型的属性

type PyMemberDef

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

描述类型属性的结构，该属性对应于 C 结构成员。定义类时，请在 tp_members 槽中放置一个以 NULL 结尾的此类结构数组。

其字段依次为：

const char *name

成员的名称。NULL 值标记 PyMemberDef[] 数组的结尾。

该字符串应该是静态的，不会对其进行复制。

int type

C 结构中成员的类型。有关可能的值，请参阅 成员类型。

Py_ssize_t offset

成员在类型对象结构上的偏移量（以字节为单位）。

int flags

零个或多个 成员标志，使用按位或运算符组合。

const char *doc

文档字符串，或 NULL。该字符串应该是静态的，不会对其进行复制。通常，它是使用 PyDoc_STR 定义的。

默认情况下（当 flags 为 0 时），成员允许读写访问。对只读访问使用 Py_READONLY 标志。某些类型，例如 Py_T_STRING，隐含 Py_READONLY。只有 Py_T_OBJECT_EX（和旧版 T_OBJECT）成员可以被删除。

对于堆分配类型（使用 PyType_FromSpec() 或类似方法创建），PyMemberDef 可以包含对特殊成员 "__vectorcalloffset__" 的定义，该成员对应于类型对象中的 tp_vectorcall_offset。这些必须使用 Py_T_PYSSIZET 和 Py_READONLY 进行定义，例如

static PyMemberDef spam_type_members[] = {
    {"__vectorcalloffset__", Py_T_PYSSIZET,
     offsetof(Spam_object, vectorcall), Py_READONLY},
    {NULL}  /* Sentinel */
};

（您可能需要 #include <stddef.h> 来使用 offsetof()。）

可以使用 "__dictoffset__" 和 "__weaklistoffset__" 成员以类似方式定义旧偏移量 tp_dictoffset 和 tp_weaklistoffset，但强烈建议扩展使用 Py_TPFLAGS_MANAGED_DICT 和 Py_TPFLAGS_MANAGED_WEAKREF 来代替。

版本 3.12 中的变化： PyMemberDef 始终可用。以前，它需要包含 "structmember.h"。

PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)

稳定 ABI 的一部分。

获取地址为 *obj_addr* 的对象所属的属性。该属性由 PyMemberDef *m* 描述。如果出错，则返回 NULL。

版本 3.12 中的变化： PyMember_GetOne 始终可用。以前，它需要包含 "structmember.h"。

int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)

稳定 ABI 的一部分。

将地址为 *obj_addr* 的对象所属的属性设置为对象 *o*。要设置的属性由 PyMemberDef *m* 描述。如果成功，则返回 0，如果失败，则返回负值。

版本 3.12 中的变化： PyMember_SetOne 始终可用。以前，它需要包含 "structmember.h"。

成员标志

以下标志可以与 PyMemberDef.flags 一起使用

Py_READONLY

不可写。

Py_AUDIT_READ

在读取之前发出 object.__getattr__ 审计事件。

Py_RELATIVE_OFFSET

表示此 PyMemberDef 条目的 offset 表示从子类特定数据的偏移量，而不是从 PyObject 的偏移量。

仅在使用负 basicsize 创建类时，才能将其用作 Py_tp_members slot 的一部分。在这种情况下，它是强制性的。

此标志仅在 PyType_Slot 中使用。在创建类期间设置 tp_members 时，Python 会清除它并将 PyMemberDef.offset 设置为从 PyObject 结构体的偏移量。

版本 3.10 中的变化： 不推荐使用包含 #include "structmember.h" 的 RESTRICTED、READ_RESTRICTED 和 WRITE_RESTRICTED 宏。READ_RESTRICTED 和 RESTRICTED 等效于 Py_AUDIT_READ；WRITE_RESTRICTED 不执行任何操作。

版本 3.12 中的变化： READONLY 宏已重命名为 Py_READONLY。PY_AUDIT_READ 宏已使用 Py_ 前缀重命名。新名称现在始终可用。以前，这些名称需要 #include "structmember.h"。该标头仍然可用，并且提供了旧名称。

成员类型

PyMemberDef.type 可以是以下宏之一，对应于各种 C 类型。当在 Python 中访问该成员时，它将被转换为等效的 Python 类型。当从 Python 设置它时，它将被转换回 C 类型。如果无法做到这一点，则会引发异常，例如 TypeError 或 ValueError。

除非标记为 (D)，否则不能使用例如 del 或 delattr() 删除以此方式定义的属性。

宏名称	C 类型	Python 类型
Py_T_BYTE	char	int
Py_T_SHORT	short	int
Py_T_INT	int	int
Py_T_LONG	long	int
Py_T_LONGLONG	long long	int
Py_T_UBYTE	unsigned char	int
Py_T_UINT	unsigned int	int
Py_T_USHORT	unsigned short	int
Py_T_ULONG	unsigned long	int
Py_T_ULONGLONG	unsigned long long	int
Py_T_PYSSIZET	Py_ssize_t	int
Py_T_FLOAT	float	float
Py_T_DOUBLE	double	float
Py_T_BOOL	char（写入为 0 或 1）	bool
Py_T_STRING	const char* (*)	str (RO)
Py_T_STRING_INPLACE	const char[] (*)	str (RO)
Py_T_CHAR	char (0-127)	str (**)
Py_T_OBJECT_EX	PyObject*	object (D)

(*): 以零结尾的 UTF8 编码 C 字符串。使用 Py_T_STRING 时，C 表示形式是指针；使用 Py_T_STRING_INPLACE 时，字符串直接存储在结构中。

(**): 长度为 1 的字符串。仅接受 ASCII。

(RO): 表示 Py_READONLY。

(D): 可以删除，在这种情况下，指针设置为 NULL。读取 NULL 指针会引发 AttributeError。

版本 3.12 中的新内容: 在以前的版本中，宏只能通过 #include "structmember.h" 使用，并且命名时没有 Py_ 前缀（例如 T_INT）。该头文件仍然可用，其中包含旧名称以及以下已弃用的类型

T_OBJECT

与 Py_T_OBJECT_EX 类似，但 NULL 会转换为 None。这会导致 Python 中出现意外行为：删除属性实际上是将其设置为 None。

T_NONE

始终为 None。必须与 Py_READONLY 一起使用。

定义 Getter 和 Setter

type PyGetSetDef

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

用于定义类型的类似属性访问的结构。另请参阅 PyTypeObject.tp_getset 槽的描述。

const char *name

属性名称

getter get

用于获取属性的 C 函数。

setter set

可选的用于设置或删除属性的 C 函数。如果为 NULL，则属性为只读。

const char *doc

可选的文档字符串

void *closure

可选的用户数据指针，为 getter 和 setter 提供额外的数据。

typedef PyObject *(*getter)(PyObject*, void*)

稳定 ABI 的一部分。

get 函数接受一个 PyObject* 参数（实例）和一个用户数据指针（关联的 closure）

成功时应返回一个新引用，失败时应返回带有设置异常的 NULL。

typedef int (*setter)(PyObject*, PyObject*, void*)

稳定 ABI 的一部分。

set 函数接受两个 PyObject* 参数（实例和要设置的值）和一个用户数据指针（关联的 closure）。

如果要删除该属性，则第二个参数为 NULL。成功应返回 0，失败则设置异常并返回 -1。