> **Источник:** https://python-all.ru/3.8/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.8/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности. **`PyLongObject`** Этот подтип [`PyObject`](https://python-all.ru/3.8/c-api/structures.html#c.PyObject) представляет целочисленный объект Python. **[PyTypeObject](https://python-all.ru/3.8/c-api/type.html#c.PyTypeObject) `PyLong_Type`** Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.8/c-api/type.html#c.PyTypeObject) представляет целочисленный тип Python. Это тот же объект, что и [`int`](https://python-all.ru/3.8/library/functions.html#int) на уровне Python. #### `int PyLong_Check(PyObject *p)` Возвращает истину, если аргумент является [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject) или подтипом [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). #### `int PyLong_CheckExact(PyObject *p)` Возвращает истину, если аргумент является [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject), но не подтипом [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). #### `PyObject* PyLong_FromLong(long v)` *Возвращаемое значение: новая ссылка.* Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject) из *v* или `NULL` при ошибке. Текущая реализация хранит массив объектов целых чисел для всех целых чисел между `-5` и `256`. Когда создаётся int в этом диапазоне, фактически возвращается ссылка на существующий объект. Поэтому изменение значения `1` должно быть возможным. Поведение Python в этом случае, вероятно, не определено. :-) #### `PyObject* PyLong_FromUnsignedLong(unsigned long v)` *Возвращаемое значение: новая ссылка.* Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject) из C `unsigned long` или `NULL` при ошибке. #### `PyObject* PyLong_FromSsize_t(Py_ssize_t v)` *Возвращаемое значение: новая ссылка.* Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject) из C `Py_ssize_t` или `NULL` при ошибке. #### `PyObject* PyLong_FromSize_t(size_t v)` *Возвращаемое значение: новая ссылка.* Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject) из C `size_t` или `NULL` при ошибке. #### `PyObject* PyLong_FromLongLong(long long v)` *Возвращаемое значение: новая ссылка.* Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject) из C `long long` или `NULL` при ошибке. #### `PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)` *Возвращаемое значение: новая ссылка.* Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject) из C `unsigned long long`, или `NULL` при ошибке. #### `PyObject* PyLong_FromDouble(double v)` *Возвращаемое значение: новая ссылка.* Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject) из целой части *v* или `NULL` в случае ошибки. #### `PyObject* PyLong_FromString(const char *str, char **pend, int base)` *Возвращаемое значение: новая ссылка.* Возвращает новый [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject) на основе строки *str*, которая интерпретируется в соответствии с основанием системы счисления *base*. Если *pend* не равно `NULL`, *\*pend* будет указывать на первый символ в *str*, следующий за представлением числа. Если *base* равно `0`, то *str* интерпретируется с помощью определения [целочисленных литералов](https://python-all.ru/3.8/reference/lexical_analysis.html#integers); в этом случае ведущие нули в ненулевом десятичном числе вызывают [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError). Если *base* не равно `0`, оно должно быть в диапазоне от `2` до `36` включительно. Ведущие пробелы и одиночные символы подчёркивания после указателя основания и между цифрами игнорируются. Если цифры отсутствуют, возникает [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError). #### `PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)` *Возвращаемое значение: новая ссылка.* Преобразует последовательность цифр Unicode в целое число Python. Устарело с версии 3.3, будет удалено в версии 3.10: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.8/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyLong_FromUnicodeObject()`](https://python-all.ru/3.8/c-api/long.html#c.PyLong_FromUnicodeObject). #### `PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)` *Возвращаемое значение: новая ссылка.* Преобразует последовательность цифр Unicode в строке *u* в целое число Python. Новое в версии 3.3. #### `PyObject* PyLong_FromVoidPtr(void *p)` *Возвращаемое значение: новая ссылка.* Создаёт целое число Python из указателя *p*. Значение указателя можно извлечь из полученного значения с помощью [`PyLong_AsVoidPtr()`](https://python-all.ru/3.8/c-api/long.html#c.PyLong_AsVoidPtr). #### `long PyLong_AsLong(PyObject *obj)` Возвращает C-представление `long` объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__) или [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) (если он есть) для преобразования в [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). Возбуждает [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError), если значение *obj* выходит за пределы допустимого диапазона для `long`. При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности. Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__), если доступно. Устарело с версии 3.8: Использование [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) устарело. #### `long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)` Возвращает C-представление `long` объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__) или [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) (если он есть) для преобразования в [`PyLongObject`](https://python-all.ru/3.8/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.8/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности. Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__), если доступно. Устарело с версии 3.8: Использование [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) устарело. #### `long long PyLong_AsLongLong(PyObject *obj)` Возвращает C-представление `long long` объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__) или [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) (если он есть) для преобразования в [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). Возбуждает [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError), если значение *obj* выходит за пределы допустимого диапазона для `long long`. При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности. Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__), если доступно. Устарело с версии 3.8: Использование [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) устарело. #### `long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)` Возвращает C-представление `long long` объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__) или [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) (если он есть) для преобразования в [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). Если значение *obj* больше `PY_LLONG_MAX` или меньше `PY_LLONG_MIN`, устанавливает *\*overflow* в `1` или `-1` соответственно и возвращает `-1`; в противном случае устанавливает *\*overflow* в `0`. Если возникает любое другое исключение, устанавливает *\*overflow* в `0` и возвращает `-1` как обычно. При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности. Новое в версии 3.2. Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__), если доступно. Устарело с версии 3.8: Использование [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) устарело. #### `Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)` Возвращает C-представление `Py_ssize_t` объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). Вызывает [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для `Py_ssize_t`. При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности. #### `unsigned long PyLong_AsUnsignedLong(PyObject *pylong)` Возвращает C-представление `unsigned long` для *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). Вызывает [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для `unsigned long`. Возвращает `(unsigned long)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred). #### `size_t PyLong_AsSize_t(PyObject *pylong)` Возвращает C-представление `size_t` объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). Вызывает [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для `size_t`. Возвращает `(size_t)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred). #### `unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)` Возвращает C-представление `unsigned long long` для *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). Возбуждает [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы допустимого диапазона для `unsigned long long`. Возвращает `(unsigned long long)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred). Изменено в версии 3.1: Отрицательное значение *pylong* теперь вызывает [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError), а не [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError). #### `unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)` Возвращает представление `unsigned long` языка C для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__) или [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) (если присутствует) для преобразования его в [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). Если значение *obj* выходит за пределы допустимого диапазона для `unsigned long`, возвращается приведение этого значения по модулю `ULONG_MAX + 1`. При ошибке возвращает `(unsigned long)-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности. Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__), если доступно. Устарело с версии 3.8: Использование [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) устарело. #### `unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)` Возвращает представление `unsigned long long` языка C для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__) или [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) (если присутствует) для преобразования его в [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). Если значение *obj* выходит за пределы допустимого диапазона для `unsigned long long`, возвращается приведение этого значения по модулю `PY_ULLONG_MAX + 1`. При ошибке возвращает `(unsigned long long)-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности. Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__index__), если доступно. Устарело с версии 3.8: Использование [`__int__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__int__) устарело. #### `double PyLong_AsDouble(PyObject *pylong)` Возвращает C-представление `double` объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.8/c-api/long.html#c.PyLongObject). Вызывает [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для `double`. При ошибке возвращает `-1.0`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности. #### `void* PyLong_AsVoidPtr(PyObject *pylong)` Преобразует целое число Python *pylong* в C-указатель `void`. Если *pylong* не удаётся преобразовать, возбуждается [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError). Гарантированно получается пригодный для использования указатель `void` только для значений, созданных с помощью [`PyLong_FromVoidPtr()`](https://python-all.ru/3.8/c-api/long.html#c.PyLong_FromVoidPtr). При ошибке возвращает `NULL`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.