> **Источник:** https://python-all.ru/3.13/c-api/number.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Протокол чисел

#### `int PyNumber_Check(PyObject *o)`

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает `1`, если объект *o* предоставляет числовые протоколы, и false в противном случае. Эта функция всегда завершается успешно.

Изменено в версии 3.8: Возвращает `1`, если *o* является индексным целым.

#### `PyObject *PyNumber_Add(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат сложения *o1* и *o2*, или `NULL` при ошибке. Это эквивалентно выражению Python `o1 + o2`.

#### `PyObject *PyNumber_Subtract(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат вычитания *o2* из *o1*, или `NULL` при ошибке. Это эквивалентно выражению Python `o1 - o2`.

#### `PyObject *PyNumber_Multiply(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат умножения *o1* на *o2*, или `NULL` при ошибке. Это эквивалентно выражению Python `o1 * o2`.

#### `PyObject *PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*

Возвращает результат матричного умножения *o1* на *o2*, или `NULL` при ошибке. Это эквивалентно выражению Python `o1 @ o2`.

Добавлено в версии 3.5.

#### `PyObject *PyNumber_FloorDivide(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат деления *o1* на *o2* с округлением вниз, или `NULL` при ошибке. Это эквивалентно выражению Python `o1 // o2`.

#### `PyObject *PyNumber_TrueDivide(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает разумное приближение математического значения *o1*, делённого на *o2*, или `NULL` при ошибке. Возвращаемое значение является «приближённым», поскольку двоичные числа с плавающей запятой являются приближёнными; невозможно представить все вещественные числа в двоичной системе. Эта функция может вернуть значение с плавающей запятой при передаче двух целых чисел. Это эквивалентно выражению Python `o1 / o2`.

#### `PyObject *PyNumber_Remainder(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает остаток от деления *o1* на *o2*, или `NULL` при ошибке. Это эквивалентно выражению Python `o1 % o2`.

#### `PyObject *PyNumber_Divmod(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Смотрите встроенную функцию [`divmod()`](https://python-all.ru/3.13/library/functions.html#divmod). Возвращает `NULL` при ошибке. Это эквивалентно выражению Python `divmod(o1, o2)`.

#### `PyObject *PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Смотрите встроенную функцию [`pow()`](https://python-all.ru/3.13/library/functions.html#pow). Возвращает `NULL` при ошибке. Это эквивалентно выражению Python `pow(o1, o2, o3)`, где *o3* является необязательным. Если *o3* нужно игнорировать, передайте [`Py_None`](https://python-all.ru/3.13/c-api/none.html#c.Py_None) вместо него (передача `NULL` для *o3* приведёт к недопустимому доступу к памяти).

#### `PyObject *PyNumber_Negative(PyObject *o)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает отрицание *o* при успехе или `NULL` при ошибке. Это эквивалентно выражению Python `-o`.

#### `PyObject *PyNumber_Positive(PyObject *o)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает *o* при успехе или `NULL` при ошибке. Это эквивалентно выражению Python `+o`.

#### `PyObject *PyNumber_Absolute(PyObject *o)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает абсолютное значение *o* или `NULL` при ошибке. Это эквивалентно выражению Python `abs(o)`.

#### `PyObject *PyNumber_Invert(PyObject *o)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает побитовое отрицание *o* при успехе или `NULL` при ошибке. Это эквивалентно выражению Python `~o`.

#### `PyObject *PyNumber_Lshift(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат сдвига влево *o1* на *o2* при успехе, или `NULL` в случае неудачи. Это эквивалент выражения Python `o1 << o2`.

#### `PyObject *PyNumber_Rshift(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат сдвига вправо *o1* на *o2* при успехе, или `NULL` в случае неудачи. Это эквивалент выражения Python `o1 >> o2`.

#### `PyObject *PyNumber_And(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат побитового И между *o1* и *o2* при успехе и `NULL` в случае неудачи. Это эквивалент выражения Python `o1 & o2`.

#### `PyObject *PyNumber_Xor(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат побитового исключающего ИЛИ между *o1* и *o2* при успехе, или `NULL` в случае неудачи. Это эквивалент выражения Python `o1 ^ o2`.

#### `PyObject *PyNumber_Or(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат побитового ИЛИ между *o1* и *o2* при успехе, или `NULL` в случае неудачи. Это эквивалент выражения Python `o1 | o2`.

#### `PyObject *PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат сложения *o1* и *o2*, или `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент инструкции Python `o1 += o2`.

#### `PyObject *PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат вычитания *o2* из *o1*, или `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент инструкции Python `o1 -= o2`.

#### `PyObject *PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат умножения *o1* и *o2*, или `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент инструкции Python `o1 *= o2`.

#### `PyObject *PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*

Возвращает результат матричного умножения *o1* и *o2*, или `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это eквивалент инструкции Python `o1 @= o2`.

Добавлено в версии 3.5.

#### `PyObject *PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает математическое округление вниз от деления *o1* на *o2*, или `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент инструкции Python `o1 //= o2`.

#### `PyObject *PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает разумное приближение математического значения от деления *o1* на *o2*, или `NULL` в случае неудачи. Возвращаемое значение является «приближённым», потому что двоичные числа с плавающей запятой приближённы; невозможно представить все вещественные числа в двоичной системе. Эта функция может вернуть значение с плавающей запятой, если ей переданы два целых числа. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент инструкции Python `o1 /= o2`.

#### `PyObject *PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает остаток от деления *o1* на *o2*, или `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент инструкции Python `o1 %= o2`.

#### `PyObject *PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Смотрите встроенную функцию [`pow()`](https://python-all.ru/3.13/library/functions.html#pow). Возвращает `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент инструкции Python `o1 **= o2`, когда o3 равно [`Py_None`](https://python-all.ru/3.13/c-api/none.html#c.Py_None), или вариант на месте `pow(o1, o2, o3)` в противном случае. Если *o3* нужно игнорировать, передайте `Py_None` вместо него (передача `NULL` для *o3* вызовет недопустимое обращение к памяти).

#### `PyObject *PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат сдвига влево *o1* на *o2* при успехе, или `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это eквивалент инструкции Python `o1 <<= o2`.

#### `PyObject *PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат сдвига вправо *o1* на *o2* при успехе, или `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это eквивалент инструкции Python `o1 >>= o2`.

#### `PyObject *PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает результат побитового И между *o1* и *o2* при успехе и `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент инструкции Python `o1 &= o2`.

#### `PyObject *PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает «побитовое исключающее ИЛИ» *o1* с *o2* в случае успеха или `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 ^= o2`.

#### `PyObject *PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает «побитовое ИЛИ» *o1* и *o2* в случае успеха или `NULL` в случае неудачи. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 |= o2`.

#### `PyObject *PyNumber_Long(PyObject *o)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает *o*, преобразованный в объект целого числа в случае успеха, или `NULL` в случае неудачи. Это эквивалент выражения Python `int(o)`.

#### `PyObject *PyNumber_Float(PyObject *o)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает *o*, преобразованный в объект числа с плавающей запятой в случае успеха, или `NULL` в случае неудачи. Это эквивалент выражения Python `float(o)`.

#### `PyObject *PyNumber_Index(PyObject *o)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает *o*, преобразованный в Python int в случае успеха, или `NULL` с возбуждением исключения [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError) в случае неудачи.

Изменено в версии 3.10: Результат всегда имеет точный тип [`int`](https://python-all.ru/3.13/library/functions.html#int). Ранее результат мог быть экземпляром подкласса `int`.

#### `PyObject *PyNumber_ToBase(PyObject *n, int base)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает целое число *n*, преобразованное в строку по основанию *base*. Аргумент *base* должен быть одним из значений 2, 8, 10 или 16. Для оснований 2, 8 или 16 возвращаемая строка начинается с префикса основания `'0b'`, `'0o'` или `'0x'` соответственно. Если *n* не является Python int, он сначала преобразуется с помощью [`PyNumber_Index()`](https://python-all.ru/3.13/c-api/number.html#c.PyNumber_Index).

#### `Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)`

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*

Возвращает *o*, преобразованный в значение [`Py_ssize_t`](https://python-all.ru/3.13/c-api/intro.html#c.Py_ssize_t), если *o* можно интерпретировать как целое число. В случае неудачи возбуждается исключение и возвращается `-1`.

Если *o* можно преобразовать в Python int, но попытка преобразования в значение [`Py_ssize_t`](https://python-all.ru/3.13/c-api/intro.html#c.Py_ssize_t) вызовет [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError), то аргумент *exc* – это тип возбуждаемого исключения (обычно [`IndexError`](https://python-all.ru/3.13/library/exceptions.html#IndexError) или `OverflowError`). Если *exc* равно `NULL`, то исключение сбрасывается, а значение усекается до `PY_SSIZE_T_MIN` для отрицательного целого или `PY_SSIZE_T_MAX` для положительного.

#### `int PyIndex_Check(PyObject *o)`

*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) с версии 3.8.*

Возвращает `1`, если *o* является индексным целым (заполнен слот `nb_index` структуры `tp_as_number`), и `0` в противном случае. Эта функция всегда завершается успешно.