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

---

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

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

**`PyLongObject`**

Этот подтип

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

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

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

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

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

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

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

на уровне Python.

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

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

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

или подтипом

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

.

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

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

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

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

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

.

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

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

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

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

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

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

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

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

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

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

из C

`Py_ssize_t`

или

*NULL*

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

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

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

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

из C

`size_t`

или

*NULL*

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

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

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

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

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

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

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

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

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

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

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

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

Возвращает новый [`PyLongObject`](https://python-all.ru/3.1/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.1/library/exceptions.html#ValueError).

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyLong_FromUnicode`([Py\_UNICODE](https://python-all.ru/3.1/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.1/c-api/long.html#PyLong_FromString).

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

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

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

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

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

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

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

*pylong*

в виде C

`long`

. Если

*pylong*

больше

`LONG_MAX`

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

*\*overflow*

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

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

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

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

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

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

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

*pylong*

в виде

`size_t`

. Если

*pylong*

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

`size_t`

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

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

.

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

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

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

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

Изменено в версии 3.1: Отрицательное значение *pylong* теперь возбуждает [`OverflowError`](https://python-all.ru/3.1/library/exceptions.html#OverflowError), а не [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError).

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

Возвращает C

`unsigned long`

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

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

Возвращает C

`unsigned long long`

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

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

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

*pylong*

в виде C

`double`

. Если

*pylong*

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

`double`

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

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

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

`-1.0`

.

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

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

*pylong*

в указатель C

`void`

. Если

*pylong*

не удаётся преобразовать, возбуждается

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

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

`void`

можно только для значений, созданных с помощью

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

.