# 对象协议

PyObject* `Py_NotImplemented`

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

`Py_RETURN_NOTIMPLEMENTED`

  C 函数内部应正确处理 `Py_NotImplemented` 的返回过程（即增加 NotImplemented 的引用计数并返回之）。

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)

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

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

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

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

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

PyObject* `PyObject_GetAttr`(PyObject *o, PyObject *attr_name)
  Return value: New reference.

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

PyObject* `PyObject_GetAttrString`(PyObject *o, const char *attr_name)
  Return value: New reference.

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

PyObject* `PyObject_GenericGetAttr`(PyObject *o, PyObject *name)
  Return value: New reference.

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

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

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

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

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

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

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

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

  通用的属性设置和删除函数，用于放入类型对象的 `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)
  Return value: New reference.

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

  3.3 版新加入.

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

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

  3.3 版新加入.

PyObject* `PyObject_RichCompare`(PyObject *o1, PyObject *o2, int opid)
  Return value: New reference.

  用 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)

  用 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_Repr`(PyObject *o)
  Return value: New reference.

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

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

PyObject* `PyObject_ASCII`(PyObject *o)
  Return value: New reference.

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

PyObject* `PyObject_Str`(PyObject *o)
  Return value: New reference.

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

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

PyObject* `PyObject_Bytes`(PyObject *o)
  Return value: New reference.

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

int `PyObject_IsSubclass`(PyObject *derived, PyObject *cls)

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

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

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

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

Py_hash_t `PyObject_HashNotImplemented`(PyObject *o)

  设置一个 `TypeError` 表示 `type(o)` 是不可哈希的，并返回 `-1` 。该函数保存在 `tp_hash` 槽中时会受到特别对待，允许某个类型向解释器显式表明它不可散列。

int `PyObject_IsTrue`(PyObject *o)

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

int `PyObject_Not`(PyObject *o)

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

PyObject* `PyObject_Type`(PyObject *o)
  Return value: New reference.

  当 o 非 `NULL` 时，返回一个与对象 o 的类型相对应的类型对象。失败时，引发 `SystemError` 并返回 `NULL`。这等同于 Python 表达式 `type(o)`。该函数会增加返回值的引用计数。实际上没有理由不去用普通的表达式 `o->ob_type` 而使用该函数，表达式会返回一个类型指针 `PyTypeObject*` ，除非需要增加引用计数。

int `PyObject_TypeCheck`(PyObject *o, PyTypeObject *type)

  Return true if the object o is of type type or a subtype of type. Both parameters must be non-`NULL`.

Py_ssize_t `PyObject_Size`(PyObject *o)
Py_ssize_t `PyObject_Length`(PyObject *o)

  返回对象 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)
  Return value: New reference.

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

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

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

int `PyObject_DelItem`(PyObject *o, PyObject *key)

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

PyObject* `PyObject_Dir`(PyObject *o)
  Return value: New reference.

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

PyObject* `PyObject_GetIter`(PyObject *o)
  Return value: New reference.

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