# 对象协议

PyObject* `Py_NotImplemented`

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

`Py_RETURN_NOTIMPLEMENTED`

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

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)

  如果 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__` 属性（必须是基类的元组）来覆盖它是否被认作类的状态，及其基类。

int `PyCallable_Check`( PyObject *o)

  确定对象 o 是可调对象。如果对象是可调对象则返回 `1` ，其他情况返回 `0` 。这个函数不会调用失败。

PyObject* `PyObject_Call`( PyObject *callable, PyObject *args, PyObject *kwargs)
  Return value: New reference.

  调用一个可调用的 Python 对象 callable，附带由元组 args 所给出的参数，以及由字典 kwargs 所给出的关键字参数。

  args must not be `NULL`, use an empty tuple if no arguments are needed. If no named arguments are needed, kwargs can be `NULL`.

  Return the result of the call on success, or raise an exception and return `NULL` on failure.

  这等价于 Python 表达式 `callable(*args, **kwargs)`。

PyObject* `PyObject_CallObject`( PyObject *callable, PyObject *args)
  Return value: New reference.

  Call a callable Python object callable, with arguments given by the tuple args. If no arguments are needed, then args can be `NULL`.

  Return the result of the call on success, or raise an exception and return `NULL` on failure.

  这等价于 Python 表达式 `callable(*args)`。

PyObject* `PyObject_CallFunction`( PyObject *callable, const char *format, ...)
  Return value: New reference.

  Call a callable Python object callable, with a variable number of C arguments. The C arguments are described using a `Py_BuildValue()` style format string. The format can be `NULL`, indicating that no arguments are provided.

  Return the result of the call on success, or raise an exception and return `NULL` on failure.

  这等价于 Python 表达式 `callable(*args)`。

  Note that if you only pass `PyObject *` args, `PyObject_CallFunctionObjArgs()` is a faster alternative.

  在 3.4 版更改: 这个 format 类型已从 `char *` 更改。

PyObject* `PyObject_CallMethod`( PyObject *obj, const char *name, const char *format, ...)
  Return value: New reference.

  Call the method named name of object obj with a variable number of C arguments. The C arguments are described by a `Py_BuildValue()` format string that should produce a tuple.

  The format can be `NULL`, indicating that no arguments are provided.

  Return the result of the call on success, or raise an exception and return `NULL` on failure.

  这和Python表达式``obj.name(arg1, arg2, ...)``是一样的。

  Note that if you only pass `PyObject *` args, `PyObject_CallMethodObjArgs()` is a faster alternative.

  在 3.4 版更改: The types of name and format were changed from `char *`.

PyObject* `PyObject_CallFunctionObjArgs`( PyObject *callable, ..., NULL)
  Return value: New reference.

  Call a callable Python object callable, with a variable number of `PyObject*` arguments. The arguments are provided as a variable number of parameters followed by `NULL`.

  Return the result of the call on success, or raise an exception and return `NULL` on failure.

  这和Python表达式``callable(arg1, arg2, ...)``是一样的。

PyObject* `PyObject_CallMethodObjArgs`( PyObject *obj, PyObject *name, ..., NULL)
  Return value: New reference.

  Calls a method of the Python object obj, where the name of the method is given as a Python string object in name. It is called with a variable number of `PyObject*` arguments. The arguments are provided as a variable number of parameters followed by `NULL`.

  Return the result of the call on success, or raise an exception and return `NULL` on failure.

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.

  When o is non-`NULL`, returns a type object corresponding to the object type of object o. On failure, raises `SystemError` and returns `NULL`. This is equivalent to the Python expression `type(o)`. This function increments the reference count of the return value. There's really no reason to use this function instead of the common expression `o->ob_type`, which returns a pointer of type `PyTypeObject*`, except when the incremented reference count is needed.

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

  如果对象Return true if the object o 为 type 类型或 type 的子类型则返回真值。 两个参数都必须非 `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 default)

  Return an estimated length for the object o. First try to return its actual length, then an estimate using `__length_hint__()`, and finally return the default value. On error return `-1`. This is the equivalent to the Python expression `operator.length_hint(o, default)`.

  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)

  Map the object key to the value v. Raise an exception and return `-1` on failure; return `0` on success. This is the equivalent of the Python statement `o[key] = 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`。