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

---

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

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

Возвращает

`1`

, если объект

*o*

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Возвращает

*o*

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

*NULL*

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

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

при ошибке.

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyNumber_ToBase`([PyObject](https://python-all.ru/3.1/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.1/c-api/number.html#PyNumber_Index)

.

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

Возвращает

*o*

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

*o*

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

*o*

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

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

, то аргумент

*exc*

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

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

или

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

). Если

*exc*

равен

*NULL*

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

*PY\_SSIZE\_T\_MIN*

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

*PY\_SSIZE\_T\_MAX*

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

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

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

*o*

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