对象协议

PyObject *Py_NotImplemented

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

Py_RETURN_NOTIMPLEMENTED

正确处理从 C 函数（即，创建对 NotImplemented 的新 强引用 并返回它）中返回 Py_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_HasAttr(PyObject *o, PyObject *attr_name)

是 稳定 ABI 的一部分。

如果 o 具有属性 attr_name，则返回 1，否则返回 0。这等效于 Python 表达式 hasattr(o, attr_name)。此函数始终成功。

注意

当调用 __getattr__() 和 __getattribute__() 方法时发生的异常会被静默忽略。为了进行正确的错误处理，请使用 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_GetAttrString()。

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

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

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

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

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

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

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()。

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)

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

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

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

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

返回值：新引用。 自版本 3.10 起成为 稳定 ABI 的一部分。

一个通用的 __dict__ 描述符获取器实现。如果需要，它会创建字典。

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

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

在版本 3.3 中添加。

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

自 3.7 版本起，作为 稳定 ABI 的一部分。

用于 __dict__ 描述符设置器的通用实现。此实现不允许删除字典。

在版本 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，结果为假时返回 0，否则返回 1。

注意

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

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被认为是真，则返回1，否则返回0。这等效于 Python 表达式not not o。如果失败，则返回-1。

int PyObject_Not(PyObject *o)

是 稳定 ABI 的一部分。

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

PyObject *PyObject_Type(PyObject *o)

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

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

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_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 版本中添加。