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

---

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

**\[PyNumber\_Check\]int `PyNumber_Check`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

Возвращает

`1`

, если объект

*o*

предоставляет числовые протоколы, и false в противном случае. Эта функция всегда завершается успешно.

**\[PyNumber\_Add\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Add`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_Subtract\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Subtract`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_Multiply\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Multiply`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_Divide\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Divide`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_FloorDivide\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_FloorDivide`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

Возвращает целую часть от деления *o1* на *o2* или *NULL* в случае ошибки. Эквивалентно «классическому» делению целых чисел.

**\[PyNumber\_TrueDivide\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_TrueDivide`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_Remainder\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Remainder`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_Divmod\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Divmod`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_Power\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Power`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o3*)**

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

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

**\[PyNumber\_Negative\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Negative`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

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

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

**\[PyNumber\_Positive\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Positive`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

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

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

**\[PyNumber\_Absolute\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Absolute`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

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

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

**\[PyNumber\_Invert\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Invert`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

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

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

**\[PyNumber\_Lshift\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Lshift`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_Rshift\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Rshift`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_And\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_And`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_Xor\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Xor`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

Возвращает побитовое исключающее ИЛИ (xor) *o1* и *o2* в случае успеха или *NULL* в случае ошибки. Это эквивалент выражения Python `o1 ^ o2`.

**\[PyNumber\_Or\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Or`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_InPlaceAdd\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceAdd`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_InPlaceSubtract\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceSubtract`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_InPlaceMultiply\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceMultiply`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_InPlaceDivide\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceDivide`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_InPlaceFloorDivide\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceFloorDivide`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_InPlaceTrueDivide\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceTrueDivide`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_InPlaceRemainder\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceRemainder`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

Возвращает остаток от деления *o1* на *o2* или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 %= o2`.

**\[PyNumber\_InPlacePower\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlacePower`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o3*)**

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

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

**\[PyNumber\_InPlaceLshift\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceLshift`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_InPlaceRshift\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceRshift`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_InPlaceAnd\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceAnd`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_InPlaceXor\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceXor`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

Возвращает результат побитового исключающего ИЛИ (bitwise exclusive or) *o1* и *o2* в случае успеха или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 ^= o2`.

**\[PyNumber\_InPlaceOr\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_InPlaceOr`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o2*)**

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

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

**\[PyNumber\_Int\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Int`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

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

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

> **Примечание**
>
> Эта функция определена в переходном `intobject.h` заголовочном файле. Она будет полностью удалена в Python 3.1. Вместо неё используйте функцию [`PyNumber_Long`](https://python-all.ru/3.0/c-api/number.html#PyNumber_Long).

**\[PyNumber\_Long\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Long`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

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

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

**\[PyNumber\_Float\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Float`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

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

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

**\[PyNumber\_Index\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_Index`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

Возвращает

*o*

, преобразованный в целое число Python (int) в случае успеха, или

*NULL*

с возбуждением исключения

[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)

при ошибке.

**\[PyNumber\_ToBase\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyNumber_ToBase`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*n*, int *base*)**

Возвращает целое число

*n*

, преобразованное в

*base*

, в виде строки с префиксом основания

`'0b'`

,

`'0o'`

или

`'0x'`

, если это применимо. Если

*base*

не равно 2, 8, 10 или 16, формат имеет вид

`'x#num'`

, где x – это основание. Если

*n*

не является объектом int, оно сначала преобразуется с помощью

[`PyNumber_Index`](https://python-all.ru/3.0/c-api/number.html#PyNumber_Index)

.

**\[PyNumber\_AsSsize\_t\]Py\_ssize\_t `PyNumber_AsSsize_t`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*exc*)**

Возвращает

*o*

, преобразованное в значение Py\_ssize\_t, если

*o*

может быть интерпретировано как целое число. Если

*o*

может быть преобразовано в Python int, но попытка преобразования в Py\_ssize\_t вызовет

[`OverflowError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OverflowError)

, то аргумент

*exc*

– это тип исключения, которое будет возбуждено (обычно

[`IndexError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.IndexError)

или

[`OverflowError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OverflowError)

). Если

*exc*

равен

*NULL*

, то исключение сбрасывается, а значение усекается до

*PY\_SSIZE\_T\_MIN*

для отрицательного целого или

*PY\_SSIZE\_T\_MAX*

для положительного.

**\[PyIndex\_Check\]int `PyIndex_Check`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**

Возвращает True, если

*o*

является индексным целым числом (т.е. имеет заполненный слот nb\_index в структуре tp\_as\_number).