对象协议

PyObject *Py_GetConstant(unsigned int constant_id)

自 3.13 版本以来，属于 稳定 ABI 的一部分。

获取对常量的强引用。

如果 constant_id 无效，则设置异常并返回 NULL。

constant_id 必须是以下常量标识符之一

常量标识符	值	返回的对象
Py_CONSTANT_NONE	0	None
Py_CONSTANT_FALSE	1	False
Py_CONSTANT_TRUE	2	True
Py_CONSTANT_ELLIPSIS	3	Ellipsis
Py_CONSTANT_NOT_IMPLEMENTED	4	NotImplemented
Py_CONSTANT_ZERO	5	0
Py_CONSTANT_ONE	6	1
Py_CONSTANT_EMPTY_STR	7	''
Py_CONSTANT_EMPTY_BYTES	8	b''
Py_CONSTANT_EMPTY_TUPLE	9	()

数值仅提供给无法使用常量标识符的项目。

在 3.13 版本中添加。

CPython 实现细节： 在 CPython 中，所有这些常量都是不朽的。

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)

自 3.13 版本以来，属于 稳定 ABI 的一部分。

类似于 Py_GetConstant()，但返回一个借用的引用。

此函数主要用于向后兼容：对于新代码，建议使用 Py_GetConstant()。

该引用是从解释器借用的，并且在解释器完成最终化之前都是有效的。

在 3.13 版本中添加。

PyObject *Py_NotImplemented

NotImplemented 单例，用于表示某个操作对于给定的类型组合未实现。

Py_RETURN_NOTIMPLEMENTED

正确处理从 C 函数中返回 Py_NotImplemented 的情况（即，创建一个对 NotImplemented 的新的强引用并返回它）。

Py_PRINT_RAW

与多个打印对象的函数一起使用的标志（如 PyObject_Print() 和 PyFile_WriteObject()）。如果传递此标志，这些函数将使用对象的 str() 而不是 repr()。

int PyObject_Print(PyObject *o, FILE *fp, int flags)

在文件 fp 上打印对象 o。如果出错，则返回 -1。flags 参数用于启用某些打印选项。目前唯一支持的选项是 Py_PRINT_RAW；如果给定，则写入对象的 str() 而不是 repr()。

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)

自 3.13 版本以来，属于 稳定 ABI 的一部分。

如果 o 具有属性 attr_name，则返回 1，否则返回 0。这等效于 Python 表达式 hasattr(o, attr_name)。如果失败，则返回 -1。

在 3.13 版本中添加。

int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)

自 3.13 版本以来，属于 稳定 ABI 的一部分。

这与 PyObject_HasAttrWithError() 相同，但 attr_name 被指定为 const char* UTF-8 编码的字节字符串，而不是 PyObject*。

在 3.13 版本中添加。

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

属于 稳定 ABI 的一部分。

如果 o 具有属性 attr_name，则返回 1，否则返回 0。此函数始终成功。

注意

当调用 __getattr__() 和 __getattribute__() 方法时发生的异常不会传播，而是传递给 sys.unraisablehook()。为了进行正确的错误处理，请改用 PyObject_HasAttrWithError()，PyObject_GetOptionalAttr() 或 PyObject_GetAttr()。

int PyObject_HasAttrString(PyObject *o, const char *attr_name)

属于 稳定 ABI 的一部分。

此函数与 PyObject_HasAttr() 相同，但 attr_name 是一个 UTF-8 编码的字节字符串 const char*，而不是 PyObject*。

注意

当此函数调用 __getattr__() 和 __getattribute__() 方法时，或者在创建临时的 str 对象时发生的异常会被静默忽略。为了正确处理错误，请改用 PyObject_HasAttrStringWithError(), PyObject_GetOptionalAttrString() 或 PyObject_GetAttrString()。

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)

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

从对象 *o* 中检索名为 *attr_name* 的属性。成功时返回属性值，失败时返回 NULL。这等效于 Python 表达式 o.attr_name。

如果缺失的属性不应被视为失败，可以使用 PyObject_GetOptionalAttr() 来代替。

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)

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

此函数与 PyObject_GetAttr() 相同，但 *attr_name* 是一个 UTF-8 编码的字节字符串 const char*，而不是 PyObject*。

如果缺失的属性不应被视为失败，可以使用 PyObject_GetOptionalAttrString() 来代替。

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);

自 3.13 版本以来，属于 稳定 ABI 的一部分。

此函数是 PyObject_GetAttr() 的变体，如果未找到属性，则不会引发 AttributeError。

如果找到了属性，则返回 1 并将 *result* 设置为该属性的新强引用。如果未找到属性，则返回 0 并将 *result* 设置为 NULL；AttributeError 被静默。如果引发 AttributeError 以外的错误，则返回 -1 并将 *result* 设置为 NULL。

在 3.13 版本中添加。

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);

自 3.13 版本以来，属于 稳定 ABI 的一部分。

此函数与 PyObject_GetOptionalAttr() 相同，但 *attr_name* 是一个 UTF-8 编码的字节字符串 const char*，而不是 PyObject*。

在 3.13 版本中添加。

PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)

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

通用的属性获取函数，旨在放入类型对象的 tp_getattro 插槽中。它会在对象的 MRO 中的类的字典中查找描述符，并在对象的 __dict__ （如果存在）中查找属性。如 实现描述符 中所述，数据描述符优先于实例属性，而非数据描述符则不然。否则，会引发 AttributeError。

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)

属于 稳定 ABI 的一部分。

将对象 *o* 的名为 *attr_name* 的属性的值设置为值 *v*。失败时引发异常并返回 -1；成功时返回 0。这等效于 Python 语句 o.attr_name = v。

如果 *v* 为 NULL，则删除该属性。不建议使用此行为，而建议使用 PyObject_DelAttr()，但目前没有计划删除它。

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)

属于 稳定 ABI 的一部分。

这与 PyObject_SetAttr() 相同，但 attr_name 被指定为一个 const char* UTF-8 编码的字节字符串，而不是一个 PyObject*。

如果 v 为 NULL，则删除该属性，但此功能已被弃用，建议使用 PyObject_DelAttrString()。

传递给此函数的不同属性名称的数量应保持较小，通常使用静态分配的字符串作为 attr_name。对于在编译时未知的属性名称，建议直接调用 PyUnicode_FromString() 和 PyObject_SetAttr()。有关更多详细信息，请参阅 PyUnicode_InternFromString()，它可以在内部用于创建键对象。

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)

属于 稳定 ABI 的一部分。

通用属性设置器和删除器函数，旨在放入类型对象的 tp_setattro 插槽中。它在对象的 MRO 中的类字典中查找数据描述符，如果找到，则优先于在实例字典中设置或删除属性。否则，该属性将在对象的 __dict__（如果存在）中设置或删除。成功时，返回 0，否则引发 AttributeError 并返回 -1。

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)

自 3.13 版本以来，属于 稳定 ABI 的一部分。

删除对象 o 的名为 attr_name 的属性。失败时返回 -1。这等效于 Python 语句 del o.attr_name。

int PyObject_DelAttrString(PyObject *o, const char *attr_name)

自 3.13 版本以来，属于 稳定 ABI 的一部分。

这与 PyObject_DelAttr() 相同，但 attr_name 被指定为一个 const char* UTF-8 编码的字节字符串，而不是一个 PyObject*。

传递给此函数的不同属性名称的数量应保持较小，通常使用静态分配的字符串作为 attr_name。对于在编译时未知的属性名称，建议直接调用 PyUnicode_FromString() 和 PyObject_DelAttr()。有关更多详细信息，请参阅 PyUnicode_InternFromString()，它可以在内部用于为查找创建键对象。

PyObject *PyObject_GenericGetDict(PyObject *o, void *context)

返回值：新的引用。 自 3.10 版本起，属于 稳定的 ABI。

__dict__ 描述符的 getter 的通用实现。它会在必要时创建字典。

此函数也可以被调用以获取对象 o 的 __dict__。调用时，对于 context 传递 NULL。由于此函数可能需要为字典分配内存，因此在访问对象的属性时，调用 PyObject_GetAttr() 可能会更有效。

失败时，返回 NULL 并设置异常。

在 3.3 版本中添加。

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)

自 3.7 版本起，属于 稳定的 ABI。

__dict__ 描述符的 setter 的通用实现。此实现不允许删除字典。

在 3.3 版本中添加。

PyObject **_PyObject_GetDictPtr(PyObject *obj)

返回指向对象 obj 的 __dict__ 的指针。如果没有 __dict__，则返回 NULL 而不设置异常。

此函数可能需要为字典分配内存，因此在访问对象的属性时，调用 PyObject_GetAttr() 可能会更有效。

PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)

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

使用 opid 指定的操作比较 o1 和 o2 的值，其中 opid 必须是 Py_LT、 Py_LE、 Py_EQ、 Py_NE、 Py_GT 或 Py_GE 之一，分别对应于 <、 <=、 ==、 !=、 > 或 >=。 这等价于 Python 表达式 o1 op o2，其中 op 是与 opid 对应的运算符。 成功时返回比较结果的值，失败时返回 NULL。

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)

属于 稳定 ABI 的一部分。

使用 opid 指定的操作比较 o1 和 o2 的值，类似于 PyObject_RichCompare()，但在出错时返回 -1，如果结果为 false 则返回 0，否则返回 1。

注意

如果 o1 和 o2 是同一个对象，则对于 Py_EQ，PyObject_RichCompareBool() 将始终返回 1； 对于 Py_NE，将始终返回 0。

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)

属于 稳定 ABI 的一部分。

使用 format_spec 格式化 obj。 这等价于 Python 表达式 format(obj, format_spec)。

format_spec 可以为 NULL。 在这种情况下，该调用等效于 format(obj)。 成功时返回格式化后的字符串，失败时返回 NULL。

PyObject *PyObject_Repr(PyObject *o)

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

计算对象 o 的字符串表示形式。 成功时返回字符串表示形式，失败时返回 NULL。 这等价于 Python 表达式 repr(o)。 由内置函数 repr() 调用。

在 3.4 版本中变更: 此函数现在包含一个调试断言，以帮助确保它不会静默地丢弃活动异常。

PyObject *PyObject_ASCII(PyObject *o)

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

如同 PyObject_Repr() 一样，计算对象 o 的字符串表示形式，但使用 \x、\u 或 \U 转义符转义 PyObject_Repr() 返回的字符串中的非 ASCII 字符。 这会生成一个类似于 Python 2 中 PyObject_Repr() 返回的字符串。 由内置函数 ascii() 调用。

PyObject *PyObject_Str(PyObject *o)

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

计算对象 o 的字符串表示形式。 成功时返回字符串表示形式，失败时返回 NULL。 这等价于 Python 表达式 str(o)。 由内置函数 str() 调用，因此也由 print() 函数调用。

在 3.4 版本中变更: 此函数现在包含一个调试断言，以帮助确保它不会静默地丢弃活动异常。

PyObject *PyObject_Bytes(PyObject *o)

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

计算对象 o 的字节表示形式。 失败时返回 NULL，成功时返回字节对象。 这等价于 Python 表达式 bytes(o)，当 o 不是整数时。 与 bytes(o) 不同的是，当 o 是整数而不是零初始化的字节对象时，会引发 TypeError。

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

属于 稳定 ABI 的一部分。

如果类 derived 与类 cls 相同或派生自类 cls，则返回 1，否则返回 0。 如果发生错误，则返回 -1。

如果 cls 是一个元组，则将针对 cls 中的每个条目执行检查。 当至少有一个检查返回 1 时，结果将为 1，否则将为 0。

如果 cls 有一个 __subclasscheck__() 方法，则将调用该方法来确定子类状态，如 PEP 3119 中所述。 否则，如果 derived 是直接或间接子类，即包含在 cls.__mro__ 中，则 derived 是 cls 的子类。

通常，只有类对象（即 type 或派生类的实例）才被视为类。 但是，对象可以通过具有 __bases__ 属性（必须是基类的元组）来覆盖此行为。

int PyObject_IsInstance(PyObject *inst, PyObject *cls)

属于 稳定 ABI 的一部分。

如果 inst 是类 cls 的实例或 cls 的子类的实例，则返回 1，否则返回 0。如果发生错误，则返回 -1 并设置一个异常。

如果 cls 是一个元组，则将针对 cls 中的每个条目执行检查。 当至少有一个检查返回 1 时，结果将为 1，否则将为 0。

如果 cls 具有 __instancecheck__() 方法，则将调用该方法来确定子类状态，如 PEP 3119 中所述。否则，如果 inst 的类是 cls 的子类，则 inst 是 cls 的实例。

实例 inst 可以通过具有 __class__ 属性来覆盖其被视为的类。

对象 cls 可以通过具有 __bases__ 属性（必须是基类的元组）来覆盖其是否被视为类以及其基类是什么。

Py_hash_t PyObject_Hash(PyObject *o)

属于 稳定 ABI 的一部分。

计算并返回对象 o 的哈希值。如果失败，则返回 -1。这等效于 Python 表达式 hash(o)。

在 3.2 版本中更改： 返回类型现在为 Py_hash_t。这是一个与 Py_ssize_t 大小相同的有符号整数。

Py_hash_t PyObject_HashNotImplemented(PyObject *o)

属于 稳定 ABI 的一部分。

设置一个 TypeError，指示 type(o) 不可 哈希，并返回 -1。当存储在 tp_hash 插槽中时，此函数会受到特殊处理，从而允许类型明确地向解释器表明它不可哈希。

int PyObject_IsTrue(PyObject *o)

属于 稳定 ABI 的一部分。

如果对象 o 被认为是 true，则返回 1，否则返回 0。这等效于 Python 表达式 not not o。如果失败，则返回 -1。

int PyObject_Not(PyObject *o)

属于 稳定 ABI 的一部分。

如果对象 o 被认为是 true，则返回 0，否则返回 1。这等效于 Python 表达式 not o。如果失败，则返回 -1。

PyObject *PyObject_Type(PyObject *o)

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

当 o 为非 NULL 时，返回一个与对象 o 的对象类型对应的类型对象。如果失败，则引发 SystemError 并返回 NULL。这等效于 Python 表达式 type(o)。此函数会为返回值创建一个新的 强引用。除了需要新的 强引用 时，实际上没有理由使用此函数而不是返回类型为 PyTypeObject* 的指针的 Py_TYPE() 函数。

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

如果对象 o 的类型为 type 或 type 的子类型，则返回非零值，否则返回 0。两个参数都必须为非 NULL。

Py_ssize_t PyObject_Size(PyObject *o)

Py_ssize_t PyObject_Length(PyObject *o)

属于 稳定 ABI 的一部分。

返回对象 o 的长度。如果对象 o 提供了序列和映射协议中的任何一个，则返回序列长度。如果发生错误，则返回 -1。这等效于 Python 表达式 len(o)。

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)

返回对象 o 的估计长度。首先尝试返回其实际长度，然后使用 __length_hint__() 返回估计值，最后返回默认值。如果发生错误，则返回 -1。这等效于 Python 表达式 operator.length_hint(o, defaultvalue)。

在 3.4 版本中添加。

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)

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

返回与对象 key 对应的 o 的元素，如果失败则返回 NULL。 这等效于 Python 表达式 o[key]。

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)

属于 稳定 ABI 的一部分。

将对象 key 映射到值 v。 如果失败，则引发异常并返回 -1；如果成功，则返回 0。 这等效于 Python 语句 o[key] = v。 此函数不会窃取对 v 的引用。

int PyObject_DelItem(PyObject *o, PyObject *key)

属于 稳定 ABI 的一部分。

从对象 o 中移除对象 key 的映射。 如果失败，则返回 -1。 这等效于 Python 语句 del o[key]。

PyObject *PyObject_Dir(PyObject *o)

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

这等效于 Python 表达式 dir(o)，返回适用于对象参数的（可能为空的）字符串列表，或者如果发生错误，则返回 NULL。如果参数为 NULL，则这类似于 Python 的 dir()，返回当前局部变量的名称；在这种情况下，如果没有活动的执行帧，则返回 NULL，但 PyErr_Occurred() 将返回 false。

PyObject *PyObject_GetIter(PyObject *o)

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

这等效于 Python 表达式 iter(o)。 它为对象参数返回一个新的迭代器，或者如果该对象已经是一个迭代器，则返回该对象本身。 如果对象无法迭代，则引发 TypeError 并返回 NULL。

PyObject *PyObject_SelfIter(PyObject *obj)

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

这等效于 Python 的 __iter__(self): return self 方法。 它旨在用于迭代器类型，以便在 PyTypeObject.tp_iter 插槽中使用。

PyObject *PyObject_GetAIter(PyObject *o)

返回值：新的引用。 自 3.10 版本起，属于 稳定的 ABI。

这等效于 Python 表达式 aiter(o)。 接受一个 AsyncIterable 对象，并为其返回一个 AsyncIterator。 这通常是一个新的迭代器，但如果参数是一个 AsyncIterator，则返回它本身。 如果对象无法迭代，则引发 TypeError 并返回 NULL。

3.10 版本中新增。

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)

自 3.12 版本以来，是稳定 ABI 的一部分。

获取为 cls 保留的特定于子类的数据的指针。

对象 o 必须是 cls 的实例，并且 cls 必须使用负的 PyType_Spec.basicsize 创建。 Python 不会检查这一点。

如果发生错误，则设置异常并返回 NULL。

3.12 版本中新增。

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)

自 3.12 版本以来，是稳定 ABI 的一部分。

返回为 cls 保留的实例内存空间的大小，即 PyObject_GetTypeData() 返回的内存大小。

这可能大于使用 -PyType_Spec.basicsize 请求的大小；使用此更大的大小（例如，使用 memset()）是安全的。

类型 cls 必须使用负的 PyType_Spec.basicsize 创建。 Python 不会检查这一点。

如果发生错误，则设置异常并返回一个负值。

3.12 版本中新增。

void *PyObject_GetItemData(PyObject *o)

获取具有 Py_TPFLAGS_ITEMS_AT_END 的类的每个项目数据的指针。

如果发生错误，则设置异常并返回 NULL。 如果 o 没有设置 Py_TPFLAGS_ITEMS_AT_END，则会引发 TypeError。

3.12 版本中新增。

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)

访问obj的托管字典。

此函数只能在设置了Py_TPFLAGS_MANAGED_DICT标志的类型的遍历函数中调用。

在 3.13 版本中添加。

void PyObject_ClearManagedDict(PyObject *obj)

清除obj的托管字典。

此函数只能在设置了Py_TPFLAGS_MANAGED_DICT标志的类型的遍历函数中调用。

在 3.13 版本中添加。