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

---

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

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

При ошибке большинство API `PyLong_As*` возвращают `(return type)-1`, который невозможно отличить от числа. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.

#### `type PyLongObject`

*Часть [Limited API](https://python-all.ru/3.12/c-api/stable.html#stable) (как непрозрачная структура).*

Этот подтип [`PyObject`](https://python-all.ru/3.12/c-api/structures.html#c.PyObject) представляет целочисленный объект Python.

#### `PyTypeObject PyLong_Type`

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

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.12/c-api/type.html#c.PyTypeObject) представляет целочисленный тип Python. Это тот же объект, что и [`int`](https://python-all.ru/3.12/library/functions.html#int) на уровне Python.

#### `int PyLong_Check(PyObject *p)`

Возвращает истину, если аргумент является [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject) или подтипом [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject). Эта функция всегда завершается успешно.

#### `int PyLong_CheckExact(PyObject *p)`

Возвращает истину, если аргумент является [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject), но не подтипом [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject). Эта функция всегда завершается успешно.

#### `PyObject *PyLong_FromLong(long v)`

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

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

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

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

#### `PyObject *PyLong_FromUnsignedLong(unsigned long v)`

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

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

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

#### `PyObject *PyLong_FromSsize_t(Py_ssize_t v)`

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

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

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

#### `PyObject *PyLong_FromSize_t(size_t v)`

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

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

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

#### `PyObject *PyLong_FromLongLong(long long v)`

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

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

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

#### `PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)`

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

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

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

#### `PyObject *PyLong_FromDouble(double v)`

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

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

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

#### `PyObject *PyLong_FromString(const char *str, char **pend, int base)`

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

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

Возвращает новый [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject) на основе строкового значения *str*, которое интерпретируется в соответствии с основанием *base*, или `NULL` в случае ошибки. Если *pend* не `NULL`, то *\*pend* будет указывать на конец *str* в случае успеха или на первый символ, который не удалось обработать, в случае ошибки. Если *base* равно `0`, то *str* интерпретируется в соответствии с определением [Integer literals](https://python-all.ru/3.12/reference/lexical_analysis.html#integers); в этом случае ведущие нули в ненулевом десятичном числе вызывают [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError). Если *base* не равно `0`, оно должно быть между `2` и `36` включительно. Начальные и конечные пробелы, а также одиночные символы подчёркивания после спецификатора основания и между цифрами игнорируются. Если цифр нет или *str* не завершается нулевым символом после цифр и конечных пробелов, будет вызвано [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).

> **См. также**
>
> Методы Python [`int.to_bytes()`](https://python-all.ru/3.12/library/stdtypes.html#int.to_bytes) и [`int.from_bytes()`](https://python-all.ru/3.12/library/stdtypes.html#int.from_bytes) для преобразования [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject) в массив байтов по основанию `256` и обратно. Эти методы можно вызывать из C с помощью [`PyObject_CallMethod()`](https://python-all.ru/3.12/c-api/call.html#c.PyObject_CallMethod).

#### `PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)`

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

Преобразует последовательность цифр Unicode в строке *u* в целое число Python.

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

#### `PyObject *PyLong_FromVoidPtr(void *p)`

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

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

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

#### `long PyLong_AsLong(PyObject *obj)`

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

Возвращает представление на C long для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__) (если он присутствует) для преобразования в [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Вызывает [`OverflowError`](https://python-all.ru/3.12/library/exceptions.html#OverflowError), если значение *obj* выходит за пределы допустимого диапазона для long.

При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.

Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__), если доступно.

Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__int__).

#### `long PyLong_AS_LONG(PyObject *obj)`

Псевдоним, [мягко устаревший](https://python-all.ru/3.12/glossary.html#term-soft-deprecated). Полностью эквивалентен предпочтительному `PyLong_AsLong`. В частности, может завершиться ошибкой [`OverflowError`](https://python-all.ru/3.12/library/exceptions.html#OverflowError) или другим исключением.

Устарело с версии 3.14: Функция мягко устарела.

#### `long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)`

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

Возвращает представление на C long для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__) (если он присутствует) для преобразования в [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Если значение *obj* больше `LONG_MAX` или меньше `LONG_MIN`, установите *\*overflow* в `1` или `-1` соответственно и верните `-1`; в противном случае установите *\*overflow* в `0`. Если возникает любое другое исключение, установите *\*overflow* в `0` и верните `-1` как обычно.

При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.

Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__), если доступно.

Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__int__).

#### `long long PyLong_AsLongLong(PyObject *obj)`

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

Возвращает C-представление long long объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__) (если он есть) для преобразования в [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Вызывает [`OverflowError`](https://python-all.ru/3.12/library/exceptions.html#OverflowError), если значение *obj* выходит за пределы допустимого диапазона для long long.

При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.

Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__), если доступно.

Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__int__).

#### `long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)`

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

Возвращает C-представление long long объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__) (если он есть) для преобразования в [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Если значение *obj* больше `LLONG_MAX` или меньше `LLONG_MIN`, устанавливает *\*overflow* в `1` или `-1` соответственно и возвращает `-1`; в противном случае устанавливает *\*overflow* в `0`. Если возникает любое другое исключение, устанавливает *\*overflow* в `0` и возвращает `-1` как обычно.

При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.

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

Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__), если доступно.

Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__int__).

#### `Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)`

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

Возвращает C-представление [`Py_ssize_t`](https://python-all.ru/3.12/c-api/intro.html#c.Py_ssize_t) объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Вызывает [`OverflowError`](https://python-all.ru/3.12/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для [`Py_ssize_t`](https://python-all.ru/3.12/c-api/intro.html#c.Py_ssize_t).

При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.

#### `unsigned long PyLong_AsUnsignedLong(PyObject *pylong)`

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

Возвращает C-представление unsigned long объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Вызывает [`OverflowError`](https://python-all.ru/3.12/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для unsigned long.

Возвращает `(unsigned long)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred).

#### `size_t PyLong_AsSize_t(PyObject *pylong)`

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

Возвращает C-представление `size_t` объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Вызывает [`OverflowError`](https://python-all.ru/3.12/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для `size_t`.

Возвращает `(size_t)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred).

#### `unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)`

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

Возвращает C-представление unsigned long long объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Вызывает [`OverflowError`](https://python-all.ru/3.12/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для unsigned long long.

Возвращает `(unsigned long long)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred).

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

#### `unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)`

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

Возвращает C-представление unsigned long объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__) (если он есть) для преобразования в [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Если значение *obj* выходит за пределы диапазона для unsigned long, возвращается приведение этого значения по модулю `ULONG_MAX + 1`.

При ошибке возвращает `(unsigned long)-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.

Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__), если доступно.

Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__int__).

#### `unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)`

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

Возвращает представление unsigned long long на языке C для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__) (если он есть) для преобразования в [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Если значение *obj* выходит за пределы диапазона для unsigned long long, возвращается приведение этого значения по модулю `ULLONG_MAX + 1`.

При ошибке возвращает `(unsigned long long)-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.

Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__index__), если доступно.

Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__int__).

#### `double PyLong_AsDouble(PyObject *pylong)`

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

Возвращает представление double на языке C для *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.12/c-api/long.html#c.PyLongObject).

Возбуждает исключение [`OverflowError`](https://python-all.ru/3.12/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для double.

При ошибке возвращает `-1.0`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.

#### `void *PyLong_AsVoidPtr(PyObject *pylong)`

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

Преобразует целое число Python *pylong* в указатель void на языке C. Если *pylong* не удаётся преобразовать, возбуждается исключение [`OverflowError`](https://python-all.ru/3.12/library/exceptions.html#OverflowError). Это гарантирует, что полученный указатель void будет пригоден для использования только для значений, созданных с помощью [`PyLong_FromVoidPtr()`](https://python-all.ru/3.12/c-api/long.html#c.PyLong_FromVoidPtr).

При ошибке возвращает `NULL`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.

#### `PyObject *PyLong_GetInfo(void)`

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

В случае успеха возвращает доступный только для чтения [именованный кортеж](https://python-all.ru/3.12/glossary.html#term-named-tuple), содержащий информацию о внутреннем представлении целых чисел в Python. Описание отдельных полей см. в [`sys.int_info`](https://python-all.ru/3.12/library/sys.html#sys.int_info).

При ошибке возвращает `NULL` с установленным исключением.

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

#### `int PyUnstable_Long_IsCompact(const PyLongObject *op)`

> *Это [нестабильное API](https://python-all.ru/3.12/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*

Возвращает 1, если *op* компактный, и 0 в противном случае.

Эта функция позволяет коду, критичному к производительности, реализовать «быстрый путь» для малых целых чисел. Для компактных значений используйте [`PyUnstable_Long_CompactValue()`](https://python-all.ru/3.12/c-api/long.html#c.PyUnstable_Long_CompactValue); для остальных – обратитесь к функции [`PyLong_As*`](https://python-all.ru/3.12/c-api/long.html#c.PyLong_AsSize_t) или [`calling`](https://python-all.ru/3.12/c-api/call.html#c.PyObject_CallMethod) [`int.to_bytes()`](https://python-all.ru/3.12/library/stdtypes.html#int.to_bytes).

Ожидается, что ускорение будет незначительным для большинства пользователей.

Какие именно значения считаются компактными, является деталью реализации и может измениться.

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

#### `Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)`

> *Это [нестабильное API](https://python-all.ru/3.12/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*

Если *op* компактный, как определено с помощью [`PyUnstable_Long_IsCompact()`](https://python-all.ru/3.12/c-api/long.html#c.PyUnstable_Long_IsCompact), вернуть его значение.

В противном случае возвращаемое значение не определено.

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