# 对象协议

PyObject *`Py_NotImplemented`

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

`Py_RETURN_NOTIMPLEMENTED`

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

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

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

int `PyObject_HasAttr`( PyObject *o, PyObject *attr_name)
  Part of the Stable ABI.

  如果 o 带有属性 attr_name，则返回 `1`，否则返回 `0`。这相当于 Python 表达式 `hasattr(o, attr_name)`。 此函数总是成功。

  注意，在调用 `__getattr__()` 和 `__getattribute__()` 方法时发生的异常将被抑制。若要获得错误报告，请换用 `PyObject_GetAttr()` 。

int `PyObject_HasAttrString`( PyObject *o, const char *attr_name)
  Part of the Stable ABI.

  如果 o 带有属性 attr_name，则返回 `1`，否则返回 `0`。这相当于 Python 表达式 `hasattr(o, attr_name)`。 此函数总是成功。

  注意，在调用 `__getattr__()` 和 `__getattribute__()` 方法并创建一个临时字符串对象时，异常将被抑制。若要获得错误报告，请换用 `PyObject_GetAttrString()` 。

PyObject *`PyObject_GetAttr`( PyObject *o, PyObject *attr_name)
  返回值：新的引用。 Part of the Stable ABI.

  从对象 o 中读取名为 attr_name 的属性。成功返回属性值，失败则返回 `NULL`。 这相当于 Python 表达式 `o.attr_name`。

PyObject *`PyObject_GetAttrString`( PyObject *o, const char *attr_name)
  返回值：新的引用。 Part of the Stable ABI.

  从对象 o 中读取一个名为 attr_name 的属性。成功时返回属性值，失败则返回 `NULL`。这相当于 Python 表达式 `o.attr_name`。

PyObject *`PyObject_GenericGetAttr`( PyObject *o, PyObject *name)
  返回值：新的引用。 Part of the Stable ABI.

  通用的属性获取函数，用于放入类型对象的 `tp_getattro` 槽中。它在类的字典中（位于对象的 MRO 中）查找某个描述符，并在对象的 `__dict__` 中查找某个属性。正如 实现描述器 所述，数据描述符优先于实例属性，而非数据描述符则不优先。失败则会触发 `AttributeError` 。

int `PyObject_SetAttr`( PyObject *o, PyObject *attr_name, PyObject *v)
  Part of the Stable 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)
  Part of the Stable ABI.

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

  如果 v 为 `NULL`，该属性将被删除，但是此功能已被弃用而应改用 `PyObject_DelAttrString()`。

int `PyObject_GenericSetAttr`( PyObject *o, PyObject *name, PyObject *value)
  Part of the Stable 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)

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

PyObject *`PyObject_GenericGetDict`( PyObject *o, void *context)
  返回值：新的引用。 Part of the Stable ABI since version 3.10.

  `__dict__` 描述符的获取函数的一种通用实现。必要时会创建该字典。

  3.3 新版功能.

int `PyObject_GenericSetDict`( PyObject *o, PyObject *value, void *context)
  Part of the Stable ABI since version 3.7.

  `__dict__` 描述符设置函数的一种通用实现。这里不允许删除该字典。

  3.3 新版功能.

PyObject *`PyObject_RichCompare`( PyObject *o1, PyObject *o2, int opid)
  返回值：新的引用。 Part of the Stable 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)
  Part of the Stable ABI.

  用 opid 指定的操作比较 o1 和 o2 的值，必须是 `Py_LT` 、 `Py_LE` 、 `Py_EQ` 、 `Py_NE` 、 `Py_GT` 或 `Py_GE` 之一，分别对应于 `<` 、`<=`、 `==` 、`!=` 、`>` 或 `>=`。错误时返回 `-1`，若结果为 false 则返回 `0`，否则返回 `1`。这相当于 Python 表达式 `o1 op o2`，其中 `op` 是对应于 opid 的操作符。

注解

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

PyObject *`PyObject_Format`( PyObject *obj, PyObject *format_spec)
  Part of the Stable ABI.

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

  format_spec 可以为 `NULL`。 在此情况下调用将等价于 `format(obj)`。 成功时返回已格式化的字符串，失败时返回 `NULL`。

PyObject *`PyObject_Repr`( PyObject *o)
  返回值：新的引用。 Part of the Stable ABI.

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

  在 3.4 版更改: 该函数现在包含一个调试断言，用以确保不会静默地丢弃活动的异常。

PyObject *`PyObject_ASCII`( PyObject *o)
  返回值：新的引用。 Part of the Stable ABI.

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

PyObject *`PyObject_Str`( PyObject *o)
  返回值：新的引用。 Part of the Stable ABI.

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

  在 3.4 版更改: 该函数现在包含一个调试断言，用以确保不会静默地丢弃活动的异常。

PyObject *`PyObject_Bytes`( PyObject *o)
  返回值：新的引用。 Part of the Stable ABI.

  计算对象 o 的字节形式。失败时返回 `NULL`，成功时返回一个字节串对象。这相当于 o 不是整数时的 Python 表达式 `bytes(o)` 。与 `bytes(o)` 不同的是，当 o 是整数而不是初始为 0 的字节串对象时，会触发 TypeError。

int `PyObject_IsSubclass`( PyObject *derived, PyObject *cls)
  Part of the Stable ABI.

  如果 derived 类与 cls 类相同或为其派生类，则返回 `1`，否则返回 `0`。 如果出错则返回 `-1`。

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

  正如 PEP 3119 所述，如果 cls 带有 `__subclasscheck__()` 方法，将会被调用以确定子类的状态。 否则，如果 derived 是个直接或间接子类，即包含在 `cls.__mro__` 中，那么它就是 cls 的一个子类。

  通常只有类对象才会被视为类，即 `type` 或派生类的实例。然而，对象可以通过拥有 `__bases__` 属性（必须是基类的元组）来覆盖这一点。

int `PyObject_IsInstance`( PyObject *inst, PyObject *cls)
  Part of the Stable ABI.

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

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

  正如 PEP 3119 所述，如果 cls 带有 `__subclasscheck__()` 方法，将会被调用以确定子类的状态。 否则，如果 derived 是 cls 的子类，那么它就是 cls 的一个实例。

  实例 inst 可以通过 `__class__` 属性来覆盖其所属类。

  对象 cls 是否被认作类，以及基类是什么，均可通过 `__bases__` 属性（必须是基类的元组）进行覆盖。

Py_hash_t `PyObject_Hash`( PyObject *o)
  Part of the Stable ABI.

  计算并返回对象的哈希值 o。 失败时返回 `-1`。这相当于 Python 表达式 `hash(o)`。

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

Py_hash_t `PyObject_HashNotImplemented`( PyObject *o)
  Part of the Stable ABI.

  设置一个 `TypeError` 来指明 `type(o)` 不是 hashable 并返回 `-1`。 此函数在存储于 `tp_hash` 槽位内时会获得特别对待，允许某个类型显式地向解释器指明它是不可哈希对象。

int `PyObject_IsTrue`( PyObject *o)
  Part of the Stable ABI.

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

int `PyObject_Not`( PyObject *o)
  Part of the Stable ABI.

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

PyObject *`PyObject_Type`( PyObject *o)
  返回值：新的引用。 Part of the Stable 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)
  Part of the Stable 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)
  返回值：新的引用。 Part of the Stable ABI.

  返回对象 key 对应的 o 元素，或在失败时返回 `NULL`。这等同于 Python 表达式 `o[key]`。

int `PyObject_SetItem`( PyObject *o, PyObject *key, PyObject *v)
  Part of the Stable ABI.

  将对象 key 映射到值 v。 失败时引发异常并返回 `-1`；成功时返回 `0`。 这相当于 Python 语句 `o[key] = v`。该函数 不会 偷取 v 的引用计数。

int `PyObject_DelItem`( PyObject *o, PyObject *key)
  Part of the Stable ABI.

  从对象 o 中移除对象 key 的映射。失败时返回 `-1`。 这相当于 Python 语句 `del o[key]`。

PyObject *`PyObject_Dir`( PyObject *o)
  返回值：新的引用。 Part of the Stable ABI.

  相当于 Python 表达式 `dir(o)`，返回一个（可能为空）适合对象参数的字符串列表，如果出错则返回 `NULL`。 如果参数为 `NULL`，类似 Python 的 `dir()`，则返回当前 locals 的名字；这时如果没有活动的执行框架，则返回 `NULL`，但 `PyErr_Occurred()` 将返回 false。

PyObject *`PyObject_GetIter`( PyObject *o)
  返回值：新的引用。 Part of the Stable ABI.

  等同于 Python 表达式 `iter(o)`。为对象参数返回一个新的迭代器，如果该对象已经是一个迭代器，则返回对象本身。如果对象不能被迭代，会引发 `TypeError` ，并返回 `NULL`。

PyObject *`PyObject_GetAIter`( PyObject *o)
  返回值：新的引用。 Part of the Stable ABI since version 3.10.

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

  3.10 新版功能.