数字协议 — Python 3.14.5 文档

# 数字协议

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`。

  Added in version 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`。

  Added in version 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` 作为 o3 会导致非法内存访问）。

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'`, 或 `'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 版起.

  如果 o 是一个索引整数（即 `tp_as_number` 结构体中填充了 `nb_index` 槽位），则返回 `1`，否则返回 `0`。此函数总是会成功执行。