对象协议

PyObject *Py_GetConstant(unsigned int constant_id)

属于 稳定 ABI 自 3.13 版起.

获取一个指向常量的 strong reference。

如果 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	()

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

Added in version 3.13.

CPython 实现细节： 在 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, const char *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__() 方法时发生的异常将被静默地忽略。 想要进行适当的错误处理，请改用 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 所描述的子类状态。 在其他情况下，如果 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 所描述的子类状态。 在其他情况下，如果 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]。

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_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.

int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj)

这是 不稳定 API。它可在次发布版中不经警告地改变。

Enable deferred reference counting on obj, if supported by the runtime. In the free-threaded build, this allows the interpreter to avoid reference count adjustments to obj, which may improve multi-threaded performance. The tradeoff is that obj will only be deallocated by the tracing garbage collector.

This function returns 1 if deferred reference counting is enabled on obj (including when it was enabled before the call), and 0 if deferred reference counting is not supported or if the hint was ignored by the runtime. This function is thread-safe, and cannot fail.

This function does nothing on builds with the GIL enabled, which do not support deferred reference counting. This also does nothing if obj is not an object tracked by the garbage collector (see gc.is_tracked() and PyObject_GC_IsTracked()).

This function is intended to be used soon after obj is created, by the code that creates it.

Added in version 3.14.0a1 (unreleased).