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

---

# Целочисленные объекты

Все целые числа реализованы как «длинные» целочисленные объекты произвольного размера.

**\[PyLongObject\]`PyLongObject`**

Этот подтип

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

представляет целочисленный объект Python.

**\[PyLong\_Type\][PyTypeObject](https://python-all.ru/3.0/c-api/type.html#PyTypeObject) `PyLong_Type`**

Этот экземпляр

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

представляет целочисленный тип Python. Это тот же объект, что и

`int`

.

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

Возвращает истину, если аргумент является

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

или подтипом

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

.

**\[PyLong\_CheckExact\]int `PyLong_CheckExact`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**

Возвращает истину, если аргумент является

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

, но не подтипом

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

.

**\[PyLong\_FromLong\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyLong_FromLong`(long *v*)**

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

Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.0/c-api/long.html#PyLongObject) из *v* или *NULL* в случае ошибки.

Текущая реализация хранит массив объектов целых чисел для всех целых чисел между `-5` и `256`. Когда создаётся int в этом диапазоне, фактически возвращается ссылка на существующий объект. Поэтому изменение значения `1` должно быть возможным. Поведение Python в этом случае, вероятно, не определено. :-)

**\[PyLong\_FromUnsignedLong\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyLong_FromUnsignedLong`(unsigned long *v*)**

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

Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.0/c-api/long.html#PyLongObject) из C `unsigned long` или *NULL* в случае ошибки.

**\[PyLong\_FromSsize\_t\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyLong_FromSsize_t`(Py\_ssize\_t *v*)**

Возвращает новый объект

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

из C

`Py_ssize_t`

или

*NULL*

в случае ошибки.

**\[PyLong\_FromSize\_t\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyLong_FromSize_t`(size\_t *v*)**

Возвращает новый объект

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

из C

`size_t`

или

*NULL*

в случае ошибки.

**\[PyLong\_FromLongLong\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyLong_FromLongLong`(PY\_LONG\_LONG *v*)**

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

Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.0/c-api/long.html#PyLongObject) из C `long long` или *NULL* в случае ошибки.

**\[PyLong\_FromUnsignedLongLong\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyLong_FromUnsignedLongLong`(unsigned PY\_LONG\_LONG *v*)**

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

Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.0/c-api/long.html#PyLongObject) из C `unsigned long long` или *NULL* в случае ошибки.

**\[PyLong\_FromDouble\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyLong_FromDouble`(double *v*)**

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

Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.0/c-api/long.html#PyLongObject) из целой части *v* или *NULL* в случае ошибки.

**\[PyLong\_FromString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyLong_FromString`(char *\*str*, char *\*\*pend*, int *base*)**

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

Возвращает новый [`PyLongObject`](https://python-all.ru/3.0/c-api/long.html#PyLongObject) на основе строкового значения *str*, которое интерпретируется в соответствии с основанием *base*. Если *pend* не *NULL*, `*pend` будет указывать на первый символ в *str*, следующий за представлением числа. Если *base* равно `0`, основание будет определено по начальным символам *str*: если *str* начинается с `'0x'` или `'0X'`, используется основание 16; если *str* начинается с `'0o'` или `'0O'`, используется основание 8; если *str* начинается с `'0b'` или `'0B'`, используется основание 2; в противном случае используется основание 10. Если *base* не равно `0`, оно должно быть между `2` и `36` включительно. Начальные пробелы игнорируются. Если цифры отсутствуют, вызывается [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError).

**\[PyLong\_FromUnicode\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyLong_FromUnicode`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*u*, Py\_ssize\_t *length*, int *base*)**

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

Преобразует последовательность цифр Unicode в целое число Python. Строка Unicode сначала кодируется в байтовую строку с помощью `PyUnicode_EncodeDecimal`, а затем преобразуется с помощью [`PyLong_FromString`](https://python-all.ru/3.0/c-api/long.html#PyLong_FromString).

**\[PyLong\_FromVoidPtr\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyLong_FromVoidPtr`(void *\*p*)**

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

Создаёт целое число Python из указателя *p*. Значение указателя можно получить из результирующего числа с помощью [`PyLong_AsVoidPtr`](https://python-all.ru/3.0/c-api/long.html#PyLong_AsVoidPtr).

**\[PyLong\_AsLong\]long `PyLong_AsLong`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*pylong*)**

Возвращает представление содержимого *pylong* в виде C `long`. Если *pylong* больше `LONG_MAX`, возникает исключение [`OverflowError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OverflowError), и возвращается -1. Не-long объекты автоматически преобразуются в long, и если при этом возникают исключения, возвращается -1.

**\[PyLong\_AsLongAndOverflow\]long `PyLong_AsLongAndOverflow`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*pylong*, int\* *overflow*)**

Возвращает представление содержимого

*pylong*

в виде C

`long`

. Если

*pylong*

больше

`LONG_MAX`

, возвращает -1 и устанавливает

*\*overflow*

в 1 (для переполнения) или -1 (для отрицательного переполнения). Если из-за ошибок типа возникает исключение, также возвращается -1.

**\[PyLong\_AsSsize\_t\]Py\_ssize\_t `PyLong_AsSsize_t`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*pylong*)**

Возвращает `Py_ssize_t` – представление содержимого *pylong* на языке C. Если *pylong* больше `PY_SSIZE_T_MAX`, возбуждается исключение [`OverflowError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OverflowError) и возвращается `-1`.

**\[PyLong\_AsUnsignedLong\]unsigned long `PyLong_AsUnsignedLong`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*pylong*)**

Возвращает представление содержимого *pylong* в виде C `unsigned long`. Если *pylong* больше `ULONG_MAX`, возникает исключение [`OverflowError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OverflowError).

**Py\_ssize\_t `PyLong_AsSsize_t`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*pylong*)**

Возвращает `Py_ssize_t` – представление содержимого *pylong*. Если *pylong* больше `PY_SSIZE_T_MAX`, возбуждается исключение [`OverflowError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OverflowError).

**\[PyLong\_AsSize\_t\]size\_t `PyLong_AsSize_t`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*pylong*)**

Возвращает представление содержимого

*pylong*

в виде

`size_t`

. Если

*pylong*

больше максимального значения для

`size_t`

, возникает исключение

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

.

**\[PyLong\_AsLongLong\]PY\_LONG\_LONG `PyLong_AsLongLong`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*pylong*)**

Возвращает C-тип

`long long`

из целого Python. Если

*pylong*

нельзя представить как

`long long`

, будет возбуждено исключение

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

.

**\[PyLong\_AsUnsignedLongLong\]unsigned PY\_LONG\_LONG `PyLong_AsUnsignedLongLong`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*pylong*)**

Возвращает C-тип

`unsigned long long`

из целого Python. Если

*pylong*

нельзя представить как

`unsigned long long`

, то для положительного значения будет возбуждено исключение

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

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

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

.

**\[PyLong\_AsUnsignedLongMask\]unsigned long `PyLong_AsUnsignedLongMask`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*io*)**

Возвращает C

`unsigned long`

из Python-целого, без проверки на переполнение.

**\[PyLong\_AsUnsignedLongLongMask\]unsigned PY\_LONG\_LONG `PyLong_AsUnsignedLongLongMask`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*io*)**

Возвращает C

`unsigned long long`

из целого числа Python, без проверки на переполнение.

**\[PyLong\_AsDouble\]double `PyLong_AsDouble`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*pylong*)**

Возвращает представление содержимого

*pylong*

в виде C

`double`

. Если

*pylong*

не может быть приблизительно представлен как

`double`

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

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

и возвращается

`-1.0`

.

**\[PyLong\_AsVoidPtr\]void\* `PyLong_AsVoidPtr`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*pylong*)**

Преобразует целое число Python

*pylong*

в указатель C

`void`

. Если

*pylong*

не может быть преобразовано, будет возбуждено исключение

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

. Гарантируется, что полученный указатель

`void`

будет пригоден для использования только для значений, созданных с помощью

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

.