对象协议

对象协议

PyObject *Py_GetConstant(unsigned int constant_id)

属于稳定 ABI 自 3.13 版起. 获取一个指向常量的 strong reference。

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

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

常量标识符

值

返回的对象

Py_CONSTANT_NONE

None

Py_CONSTANT_FALSE

False

Py_CONSTANT_TRUE

True

Py_CONSTANT_ELLIPSIS

Ellipsis

Py_CONSTANT_NOT_IMPLEMENTED

NotImplemented

Py_CONSTANT_ZERO

0

Py_CONSTANT_ONE

1

Py_CONSTANT_EMPTY_STR

''

Py_CONSTANT_EMPTY_BYTES

b''

Py_CONSTANT_EMPTY_TUPLE

()

仅对无法使用常量标识符的项目才会给出数字值。

Added in version 3.13.

在 CPython 中，所有这些常量都属于 immortal 对象。

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)

属于稳定 ABI 自 3.13 版起. 类似于 Py_GetConstant()，但会返回一个 borrowed reference。

此函数的主要目的是用于向下兼容：对于新代码推荐使用 Py_GetConstant()。

该引用是从解释器借入的，并将保持可用直到解释器最终化。

Added in version 3.13.

PyObject *Py_NotImplemented

NotImplemented 单例，用于标记某个操作没有针对给定类型组合的实现。

Py_RETURN_NOTIMPLEMENTED

正确处理从 C 函数内部返回 Py_NotImplemented 的问题（即新建一个指向 NotImplemented 的 strong reference 并返回它）。

Py_PRINT_RAW

要与多个打印对象的函数 (如 PyObject_Print() 和 PyFile_WriteObject()) 一起使用的旗标。如果传入，这些函数应当使用对象的 str() 而不是 repr()。

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

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

int PyObject_HasAttrWithError(PyObject o, PyObject attr_name)

属于稳定 ABI 自 3.13 版起. 如果 o 具有属性 attr_name 则返回 1，否则返回 0。这相当于 Python 表达式 hasattr(o, attr_name)。当失败时，将返回 -1。

Added in version 3.13.

int PyObject_HasAttrStringWithError(PyObject o, const char attr_name)

属于稳定 ABI 自 3.13 版起. 这与 PyObject_HasAttrWithError() 相同，但 attr_name 被指定为 const char UTF-8 编码的字节串，而不是 PyObject。

Added in version 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 被指定为 const char UTF-8 编码的字节串，而不是 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 被指定为 const char UTF-8 编码的字节串，而不是 PyObject。

如果缺少属性不应被视为执行失败，你可以改用 PyObject_GetOptionalAttrString()。

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

属于稳定 ABI 自 3.13 版起. PyObject_GetAttr() 的变化形式，它在未找到键时不会引发 AttributeError。

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

Added in version 3.13.

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

属于稳定 ABI 自 3.13 版起. 这与 PyObject_GetOptionalAttr() 相同，但 attr_name 被指定为 const char UTF-8 编码的字节串，而不是 PyObject。

Added in version 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)

属于稳定 ABI 自 3.13 版起. 删除对象 o 中名为 attr_name 的属性。失败时返回 -1。这相当于 Python 语句 del o.attr_name。

int PyObject_DelAttrString(PyObject o, const char attr_name)

属于稳定 ABI 自 3.13 版起. 这与 PyObject_DelAttr() 相同，但 attr_name 被指定为 const char UTF-8 编码的字节串，而不是 PyObject。

传给该函数的不同属性名称应当保持在较少的数量，通过是通过使用静态分配的字符串作为 attr_name 来做到这一点。对于编译时未知的属性名称，建议直接调用 PyUnicode_FromString() 和 PyObject_DelAttr()。更多相关细节，请参阅 PyUnicode_InternFromString()，它可在内部用于创建供查找的键对象。

PyObject PyObject_GenericGetDict(PyObject o, void *context)

返回值：新的引用。属于稳定 ABI 自 3.10 版起. __dict__ 描述符的获取函数的一种通用实现。必要时会创建该字典。

此函数还可能会被调用以获取对象 o 的 __dict__。当调用它时可传入 NULL 作为 context。由于此函数可能需要为字典分配内存，所以在访问对象上的属性时调用 PyObject_GetAttr() 可能会更为高效。

当失败时，将返回 NULL 并设置一个异常。

Added in version 3.3.

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

属于稳定 ABI 自 3.7 版起. __dict__ 描述符设置函数的一种通用实现。这里不允许删除该字典。

Added in version 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 的值，操作必须为 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 所指定的操作，例如 PyObject_RichCompare() 来比较 o1 和 o2 的值，但在出错时返回 -1，在结果为假值时返回 0，在其他情况下返回 1。

备注

如果 o1 和 o2 是同一个对象，PyObject_RichCompareBool() 将总是为 Py_EQ 返回 1 并为 Py_NE 返回 0。

PyObject PyObject_Format(PyObject obj, PyObject *format_spec)

属于稳定 ABI. 格式 obj 使用 format_spec。这等价于 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 的字符串形式，但在 PyObject_Repr() 返回的字符串中用 \x、\u 或 \U 转义非 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，成功时返回一个字节串对象。这相当于 o 不是整数时的 Python 表达式 bytes(o) 。与 bytes(o) 不同的是，当 o 是整数而不是初始为 0 的字节串对象时，会触发 TypeError。

int PyObject_IsSubclass(PyObject derived, PyObject cls)

属于稳定 ABI. 如果 derived 类与 cls 类相同或为其派生类，则返回 1，否则返回 0。如果出错则返回 -1。

如果 cls 是元组，则会对 cls 进行逐项检测。如果至少有一次检测返回 1，结果将为 1，否则将是 0。

如果 cls 具有 __subclasscheck__() 方法，它将被调用以确定 PEP 3119 [https://peps.python.org/pep-3119/] 所描述的子类状态。在其他情况下，如果 derived 是一个直接或间接子类即包含在 cls.__mro__ 中则它就是 cls 的子类。

通常只有类对象，即 type 或其派生类的实例才会被视为类。但是，对象可以通过设置 __bases__ 属性（它必须是由基类组成的元组）来覆盖此定义。

int PyObject_IsInstance(PyObject inst, PyObject cls)

属于稳定 ABI. 如果 inst 是 cls 类或其子类的实例，则返回 1，如果不是则返回 0。如果出错则返回 -1 并设置一个异常。

如果 cls 是元组，则会对 cls 进行逐项检测。如果至少有一次检测返回 1，结果将为 1，否则将是 0。

如果 cls 具有 __instancecheck__() 方法，它将被调用以确定 PEP 3119 [https://peps.python.org/pep-3119/] 所描述的子类状态。在其他情况下，如果 inst 的类是 cls 的子类则它就是 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) 不是 hashable 并返回 -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，则返回 1，否则返回 0。这相当于 Python 表达式 not not o。失败则返回 -1。

PyObject PyObject_Type(PyObject o)

返回值：新的引用。属于稳定 ABI. 当 o 不为 NULL 时，返回一个与对象 o 的类型相对应的类型对象。当失败时，将引发 SystemError 并返回 NULL。这等同于 Python 表达式 type(o)。该函数会新建一个指向返回值的 strong reference。实际上没有多少理由使用此函数来替代 Py_TYPE() 函数，后者将返回一个 PyTypeObject* 类型的指针，除非是需要一个新的 strong reference。

int PyObject_TypeCheck(PyObject o, PyTypeObject type)

如果对象 o 是 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)。

Added in version 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]。

int PyObject_DelItemString(PyObject o, const char key)

属于稳定 ABI. 这与 PyObject_DelItem() 相同，但 key 被指定为 const char UTF-8 编码的字节串，而不是 PyObject。

PyObject PyObject_Dir(PyObject o)

返回值：新的引用。属于稳定 ABI. 相当于 Python 表达式 dir(o)，返回一个（可能为空）适合对象参数的字符串列表，如果出错则返回 NULL。如果参数为 NULL，类似 Python 的 dir()，则返回当前 locals 的名字；这时如果没有活动的执行框架，则返回 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 方法。它是针对 iterator 类型设计的，将在 PyTypeObject.tp_iter 槽位中使用。

PyObject PyObject_GetAIter(PyObject o)

返回值：新的引用。属于稳定 ABI 自 3.10 版起. 等同于 Python 表达式 aiter(o)。接受一个 AsyncIterable 对象，并为其返回一个 AsyncIterator。通常返回的是一个新迭代器，但如果参数是一个 AsyncIterator，将返回其自身。如果该对象不能被迭代，会引发 TypeError，并返回 NULL。

Added in version 3.10.

void PyObject_GetTypeData(PyObject o, PyTypeObject *cls)

属于稳定 ABI 自 3.12 版起. 获取一个指向为 cls 保留的子类专属数据的指针。

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

发生错误时，将设置异常并返回 NULL。

Added in version 3.12.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)

属于稳定 ABI 自 3.12 版起. 返回为 cls 保留的实例内存空间大小，即 PyObject_GetTypeData() 所返回的内存大小。

这可能会大于使用 -PyType_Spec.basicsize 请求到的大小；可以安全地使用这个更大的值 (例如通过 memset())。

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

当失败时，将设置异常并返回一个负值。

Added in version 3.12.

void PyObject_GetItemData(PyObject o)

使用 Py_TPFLAGS_ITEMS_AT_END 获取一个指向类的单独条目数据的指针。

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

Added in version 3.12.

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

访问被管理的 obj 的字典。

此函数必须只在设置了 Py_TPFLAGS_MANAGED_DICT 旗标的类型的遍历函数中被调用。

Added in version 3.13.

void PyObject_ClearManagedDict(PyObject *obj)

清空被管理的 obj 的字典。.

此函数必须只在设置了 Py_TPFLAGS_MANAGED_DICT 旗标的类型的遍历函数中被调用。

Added in version 3.13.