数字协议
********

int PyNumber_Check(PyObject *o)
    * 属于 稳定 ABI.*

   如果对象 *o* 提供数字的协议，返回真 "1"，否则返回假。这个函数不会调
   用失败。

   在 3.8 版本发生变更: 如果 *o* 是一个索引整数则返回 "1"。

PyObject *PyNumber_Add(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 、*o2* 相加的结果，如果失败，返回 "NULL"。等价于 Python
   表达式 "o1 + o2"。

PyObject *PyNumber_Subtract(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 减去 *o2* 的结果，如果失败，返回 "NULL"。等价于 Python 表
   达式 "o1 - o2"。

PyObject *PyNumber_Multiply(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1*  、 *o2* 相乘的结果，如果失败，返回 "NULL"。等价于 Python
   表达式 "o1 * o2"。

PyObject *PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI 自 3.7 版起.*

   返回 *o1* 、*o2* 做矩阵乘法的结果，如果失败，返回 "NULL"。等价于
   Python 表达式 "o1 @ o2"。

   在 3.5 版本加入.

PyObject *PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 除以 *o2* 向下取整的值，失败时返回 "NULL"。 这等价于
   Python 表达式 "o1 // o2"。

PyObject *PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 除以 *o2* 的数学值的合理近似值，或失败时返回 "NULL"。 返
   回的是 "近似值" 因为二进制浮点数本身就是近似值；不可能以二进制精确
   表示所有实数。 此函数可以在传入两个整数时返回一个浮点值。 此函数等
   价于 Python 表达式 "o1 / o2"。

PyObject *PyNumber_Remainder(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 除以 *o2* 得到的余数，如果失败，返回 "NULL"。等价于
   Python 表达式 "o1 % o2"。

PyObject *PyNumber_Divmod(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   参考内置函数 "divmod()"。如果失败，返回 "NULL"。等价于 Python 表达
   式 "divmod(o1, o2)"。

PyObject *PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
    *返回值：新的引用。** 属于 稳定 ABI.*

   请参阅内置函数 "pow()"。 如果失败，返回 "NULL"。 等价于 Python 中的
   表达式 "pow(o1, o2, o3)"，其中 *o3* 是可选的。如果要忽略 *o3*，则需
   传入 "Py_None" 作为代替（如果传入 "NULL" 会导致非法内存访问）。

PyObject *PyNumber_Negative(PyObject *o)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o* 的负值，如果失败，返回 "NULL" 。等价于 Python 表达式 "-o"
   。

PyObject *PyNumber_Positive(PyObject *o)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o*，如果失败，返回 "NULL" 。等价于 Python 表达式 "+o"。

PyObject *PyNumber_Absolute(PyObject *o)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o* 的绝对值，如果失败，返回 "NULL"。等价于 Python 表达式
   "abs(o)"。

PyObject *PyNumber_Invert(PyObject *o)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o* 的按位取反后的结果，如果失败，返回 "NULL"。等价于 Python
   表达式 "~o"。

PyObject *PyNumber_Lshift(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 左移 *o2* 个比特后的结果，如果失败，返回 "NULL"。等价于
   Python 表达式 "o1 << o2"。

PyObject *PyNumber_Rshift(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 右移 *o2* 个比特后的结果，如果失败，返回  "NULL" 。等价于
   Python 表达式 "o1 >> o2"。

PyObject *PyNumber_And(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 和 *o2* “按位与”的结果，如果失败，返回 "NULL" 。等价于
   Python 表达式 "o1 & o2"。

PyObject *PyNumber_Xor(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 和 *o2* “按位异或”的结果，如果失败，返回 "NULL" 。等价于
   Python 表达式 "o1 ^ o2"。

PyObject *PyNumber_Or(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 和 *o2* “按位或”的结果，如果失败，返回 "NULL" 。等价于
   Python 表达式 "o1 | o2"。

PyObject *PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 、*o2* 相加的结果，如果失败，返回 "NULL"。当 *o1* 支持时
   ，这个运算直接使用它储存结果。 等价于 Python 语句 "o1 += o2"。

PyObject *PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 、*o2* 相减的结果，如果失败，返回 "NULL" 。当 *o1* 支持时
   ，这个运算直接使用它储存结果。 等价于 Python 语句 "o1 -= o2"。

PyObject *PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 、*o2*相乘的结果，如果失败，返回 ``NULL`` 。当 *o1* 支持
   时，这个运算直接使用它储存结果。 等价于 Python 语句 "o1 *= o2"。

PyObject *PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI 自 3.7 版起.*

   返回 *o1* 、*o2* 做矩阵乘法后的结果，如果失败，返回 "NULL" 。当
   *o1* 支持时，这个运算直接使用它储存结果。 等价于 Python 语句 "o1 @=
   o2"。

   在 3.5 版本加入.

PyObject *PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 除以 *o2* 后向下取整的结果，如果失败，返回 "NULL"。当
   *o1* 支持时，这个运算直接使用它储存结果。 等价于 Python 语句 "o1
   //= o2"。

PyObject *PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 除以 *o2* 的数学值的合理近似值，或失败时返回 "NULL"。 返
   回的是 "近似值" 因为二进制浮点数本身就是近似值；不可能以二进制精确
   表示所有实数。 此函数可以在传入两个整数时返回一个浮点数。 此运算在
   *o1* 支持的时候会 *原地* 执行。此函数等价于 Python 语句 "o1 /= o2"
   。

PyObject *PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 除以 *o2* 得到的余数，如果失败，返回 "NULL"。当 *o1* 支持
   时，这个运算直接使用它储存结果。 等价于 Python 语句 "o1 %= o2"。

PyObject *PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
    *返回值：新的引用。** 属于 稳定 ABI.*

   请参阅内置函数 "pow()"。 如果失败，返回 "NULL"。当 *o1* 支持时，这
   个运算直接使用它储存结果。当 *o3* 是 "Py_None" 时，等价于 Python 语
   句  "o1 **= o2"；否则等价于在原来位置储存结果的 "pow(o1, o2, o3)"
   。如果要忽略 *o3*，则需传入 "Py_None"  （传入 "NULL" 会导致非法内存
   访问）。

PyObject *PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 左移 *o2* 个比特后的结果，如果失败，返回 "NULL"。当 *o1*
   支持时，这个运算直接使用它储存结果。 等价于 Python 语句 "o1 <<= o2"
   。

PyObject *PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回 *o1* 右移 *o2* 个比特后的结果，如果失败，返回 "NULL"。当 *o1*
   支持时，这个运算直接使用它储存结果。 等价于 Python 语句 "o1 >>= o2"
   。

PyObject *PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   成功时返回 *o1* 和 *o2* "按位与" 的结果，失败时返回 "NULL"。 在
   *o1* 支持的前提下该操作将 *原地* 执行。 等价与 Python 语句 "o1 &=
   o2"。

PyObject *PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   成功时返回 *o1* 和 *o2* "按位异或的结果，失败时返回 "NULL"。 在
   *o1* 支持的前提下该操作将 *原地* 执行。 等价与 Python 语句 "o1 ^=
   o2"。

PyObject *PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
    *返回值：新的引用。** 属于 稳定 ABI.*

   成功时返回 *o1* 和 *o2* "按位或" 的结果，失败时返回 "NULL"。 在
   *o1* 支持的前提下该操作将 *原地* 执行。 等价于 Python 语句 "o1 |=
   o2"。

PyObject *PyNumber_Long(PyObject *o)
    *返回值：新的引用。** 属于 稳定 ABI.*

   成功时返回 *o* 转换为整数对象后的结果，失败时返回 "NULL"。 等价于
   Python 表达式 "int(o)"。

PyObject *PyNumber_Float(PyObject *o)
    *返回值：新的引用。** 属于 稳定 ABI.*

   成功时返回 *o* 转换为浮点对象后的结果，失败时返回 "NULL"。 等价于
   Python 表达式 "float(o)"。

PyObject *PyNumber_Index(PyObject *o)
    *返回值：新的引用。** 属于 稳定 ABI.*

   成功时返回 *o* 转换为 Python int 类型后的结果，失败时返回 "NULL" 并
   引发 "TypeError" 异常。

   在 3.10 版本发生变更: 结果总是为 "int" 类型。 在之前版本中，结果可
   能为 "int" 的子类的实例。

PyObject *PyNumber_ToBase(PyObject *n, int base)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回整数 *n* 转换成以 *base* 为基数的字符串后的结果。这个 *base* 参
   数必须是 2，8，10 或者 16 。对于基数 2，8，或 16 ，返回的字符串将分
   别加上基数标识 "'0b'", "'0o'", or "'0x'"。如果 *n* 不是 Python 中的
   整数 *int* 类型，就先通过 "PyNumber_Index()" 将它转换成整数类型。

Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
    * 属于 稳定 ABI.*

   如果 *o* 可以被解读为一个整数则返回 *o* 转换成的 "Py_ssize_t" 值。
   如果调用失败，则会引发一个异常并返回 "-1"。

   如果 *o* 可以被转换为 Python 的 int 值但尝试转换为 "Py_ssize_t" 值
   则会引发 "OverflowError"，则 *exc* 参数将为所引发的异常类型 (通常为
   "IndexError" 或 "OverflowError")。 如果 *exc* 为 "NULL"，则异常会被
   清除并且值会在为负整数时被裁剪为 "PY_SSIZE_T_MIN" 而在为正整数时被
   裁剪为 "PY_SSIZE_T_MAX"。

int PyIndex_Check(PyObject *o)
    * 属于 稳定 ABI 自 3.8 版起.*

   返回 "1" 如果 *o* 是一个索引整数（将 "nb_index" 槽位填充到
   "tp_as_number" 结构体），或者在其他情况下返回 "0"。 此函数总是会成
   功执行。
