`long.md`

448 строк · 37.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/c-api/long.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Целочисленные объекты89Все целые числа реализованы как «длинные» целочисленные объекты произвольного размера.1011При ошибке большинство API `PyLong_As*` возвращают `(return type)-1`, который невозможно отличить от числа. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.1213#### `type PyLongObject`1415*Часть [Limited API](https://python-all.ru/3.13/c-api/stable.html#stable) (как непрозрачная структура).*1617Этот подтип [`PyObject`](https://python-all.ru/3.13/c-api/structures.html#c.PyObject) представляет целочисленный объект Python.1819#### `PyTypeObject PyLong_Type`2021*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*2223Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject) представляет целочисленный тип Python. Это тот же объект, что и [`int`](https://python-all.ru/3.13/library/functions.html#int) на уровне Python.2425#### `int PyLong_Check(PyObject *p)`2627Возвращает истину, если аргумент является [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject) или подтипом `PyLongObject`. Эта функция всегда завершается успешно.2829#### `int PyLong_CheckExact(PyObject *p)`3031Возвращает истину, если аргумент является [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject), но не подтипом `PyLongObject`. Эта функция всегда завершается успешно.3233#### `PyObject *PyLong_FromLong(long v)`3435*Возвращаемое значение: новая ссылка.*3637*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*3839Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject) из *v* или `NULL` при ошибке.4041**Деталь реализации CPython:** CPython хранит массив целочисленных объектов для всех целых чисел в диапазоне от `-5` до `256`. При создании int в этом диапазоне фактически возвращается ссылка на существующий объект.4243#### `PyObject *PyLong_FromUnsignedLong(unsigned long v)`4445*Возвращаемое значение: новая ссылка.*4647*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*4849Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject) из C unsigned long или `NULL` при ошибке.5051#### `PyObject *PyLong_FromSsize_t(Py_ssize_t v)`5253*Возвращаемое значение: новая ссылка.*5455*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*5657Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject) из C [`Py_ssize_t`](https://python-all.ru/3.13/c-api/intro.html#c.Py_ssize_t) или `NULL` при ошибке.5859#### `PyObject *PyLong_FromSize_t(size_t v)`6061*Возвращаемое значение: новая ссылка.*6263*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*6465Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject) из C `size_t` или `NULL` при ошибке.6667#### `PyObject *PyLong_FromLongLong(long long v)`6869*Возвращаемое значение: новая ссылка.*7071*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*7273Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject) из C long long или `NULL` при ошибке.7475#### `PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)`7677*Возвращаемое значение: новая ссылка.*7879*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*8081Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject) из C unsigned long long или `NULL` при ошибке.8283#### `PyObject *PyLong_FromDouble(double v)`8485*Возвращаемое значение: новая ссылка.*8687*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*8889Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject) из целой части *v* или `NULL` в случае ошибки.9091#### `PyObject *PyLong_FromString(const char *str, char **pend, int base)`9293*Возвращаемое значение: новая ссылка.*9495*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*9697Возвращает новый [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject) на основе строкового значения *str*, которое интерпретируется в соответствии с основанием *base*, или `NULL` в случае ошибки. Если *pend* не `NULL`, то *\*pend* будет указывать на конец *str* в случае успеха или на первый символ, который не удалось обработать, в случае ошибки. Если *base* равно `0`, то *str* интерпретируется в соответствии с определением [Integer literals](https://python-all.ru/3.13/reference/lexical_analysis.html#integers); в этом случае ведущие нули в ненулевом десятичном числе вызывают [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError). Если *base* не равно `0`, оно должно быть между `2` и `36` включительно. Начальные и конечные пробелы, а также одиночные символы подчёркивания после спецификатора основания и между цифрами игнорируются. Если цифр нет или *str* не завершается нулевым символом после цифр и конечных пробелов, будет вызвано `ValueError`.9899> **См. также**100>101> Методы Python [`int.to_bytes()`](https://python-all.ru/3.13/library/stdtypes.html#int.to_bytes) и [`int.from_bytes()`](https://python-all.ru/3.13/library/stdtypes.html#int.from_bytes) для преобразования [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject) в массив байтов по основанию `256` и обратно. Эти методы можно вызывать из C с помощью [`PyObject_CallMethod()`](https://python-all.ru/3.13/c-api/call.html#c.PyObject_CallMethod).102103#### `PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)`104105*Возвращаемое значение: новая ссылка.*106107Преобразует последовательность цифр Unicode в строке *u* в целое число Python.108109Добавлено в версии 3.3.110111#### `PyObject *PyLong_FromVoidPtr(void *p)`112113*Возвращаемое значение: новая ссылка.*114115*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*116117Создаёт целое число Python из указателя *p*. Значение указателя можно извлечь из полученного значения с помощью [`PyLong_AsVoidPtr()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_AsVoidPtr).118119#### `PyObject *PyLong_FromNativeBytes(const void *buffer, size_t n_bytes, int flags)`120121Создаёт целое число Python из значения, содержащегося в первых *n\_bytes* буфера *buffer*, интерпретируемого как знаковое число в дополнительном коде.122123*flags* – как для [`PyLong_AsNativeBytes()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_AsNativeBytes). Передача `-1` выберет нативный порядок байтов, используемый CPython, и будет считать, что старший бит является знаковым. Передача `Py_ASNATIVEBYTES_UNSIGNED_BUFFER` даёт тот же результат, что и вызов [`PyLong_FromUnsignedNativeBytes()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_FromUnsignedNativeBytes). Остальные флаги игнорируются.124125Добавлено в версии 3.13.126127#### `PyObject *PyLong_FromUnsignedNativeBytes(const void *buffer, size_t n_bytes, int flags)`128129Создаёт целое число Python из значения, содержащегося в первых *n\_bytes* буфера *buffer*, интерпретируемого как беззнаковое число.130131*flags* – как для [`PyLong_AsNativeBytes()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_AsNativeBytes). Передача `-1` выберет нативный порядок байтов, используемый CPython, и будет считать, что старший бит не является знаковым. Флаги, не связанные с порядком байтов, игнорируются.132133Добавлено в версии 3.13.134135#### `PyLong_FromPid(pid)`136137Макрос для создания целого числа Python из идентификатора процесса.138139Может быть определён как псевдоним [`PyLong_FromLong()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_FromLong) или [`PyLong_FromLongLong()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_FromLongLong) в зависимости от размера типа PID в системе.140141Добавлено в версии 3.2.142143#### `long PyLong_AsLong(PyObject *obj)`144145*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*146147Возвращает представление на C long для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__) (если он присутствует) для преобразования в `PyLongObject`.148149Вызывает [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError), если значение *obj* выходит за пределы допустимого диапазона для long.150151При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.152153Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__), если доступно.154155Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__int__).156157#### `long PyLong_AS_LONG(PyObject *obj)`158159Полностью эквивалентна предпочтительной `PyLong_AsLong`. В частности, может завершиться ошибкой с [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError) или другим исключением.160161[Soft deprecated](https://python-all.ru/3.13/glossary.html#term-soft-deprecated) since version 3.14.162163#### `int PyLong_AsInt(PyObject *obj)`164165*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable), начиная с версии 3.13.*166167Аналогична [`PyLong_AsLong()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_AsLong), но сохраняет результат в C int вместо C long.168169Добавлено в версии 3.13.170171#### `long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)`172173*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*174175Возвращает представление на C long для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__) (если он присутствует) для преобразования в `PyLongObject`.176177Если значение *obj* больше `LONG_MAX` или меньше `LONG_MIN`, установите *\*overflow* в `1` или `-1` соответственно и верните `-1`; в противном случае установите *\*overflow* в `0`. Если возникает любое другое исключение, установите *\*overflow* в `0` и верните `-1` как обычно.178179При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.180181Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__), если доступно.182183Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__int__).184185#### `long long PyLong_AsLongLong(PyObject *obj)`186187*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*188189Возвращает C-представление long long объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__) (если он есть) для преобразования в `PyLongObject`.190191Вызывает [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError), если значение *obj* выходит за пределы допустимого диапазона для long long.192193При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.194195Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__), если доступно.196197Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__int__).198199#### `long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)`200201*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*202203Возвращает C-представление long long объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__) (если он есть) для преобразования в `PyLongObject`.204205Если значение *obj* больше `LLONG_MAX` или меньше `LLONG_MIN`, устанавливает *\*overflow* в `1` или `-1` соответственно и возвращает `-1`; в противном случае устанавливает *\*overflow* в `0`. Если возникает любое другое исключение, устанавливает *\*overflow* в `0` и возвращает `-1` как обычно.206207При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.208209Добавлено в версии 3.2.210211Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__), если доступно.212213Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__int__).214215#### `Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)`216217*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*218219Возвращает C-представление [`Py_ssize_t`](https://python-all.ru/3.13/c-api/intro.html#c.Py_ssize_t) объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject).220221Вызывает [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для [`Py_ssize_t`](https://python-all.ru/3.13/c-api/intro.html#c.Py_ssize_t).222223При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.224225#### `unsigned long PyLong_AsUnsignedLong(PyObject *pylong)`226227*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*228229Возвращает C-представление unsigned long объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject).230231Вызывает [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для unsigned long.232233Возвращает `(unsigned long)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred).234235#### `size_t PyLong_AsSize_t(PyObject *pylong)`236237*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*238239Возвращает C-представление `size_t` объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject).240241Вызывает [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для `size_t`.242243Возвращает `(size_t)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred).244245#### `unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)`246247*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*248249Возвращает C-представление unsigned long long объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject).250251Вызывает [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для unsigned long long.252253Возвращает `(unsigned long long)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred).254255Изменено в версии 3.1: Отрицательное значение *pylong* теперь вызывает [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError), а не [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError).256257#### `unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)`258259*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*260261Возвращает C-представление unsigned long объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__) (если он есть) для преобразования в `PyLongObject`.262263Если значение *obj* выходит за пределы диапазона для unsigned long, возвращается приведение этого значения по модулю `ULONG_MAX + 1`.264265При ошибке возвращает `(unsigned long)-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.266267Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__), если доступно.268269Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__int__).270271#### `unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)`272273*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*274275Возвращает представление unsigned long long на языке C для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__) (если он есть) для преобразования в `PyLongObject`.276277Если значение *obj* выходит за пределы диапазона для unsigned long long, возвращается приведение этого значения по модулю `ULLONG_MAX + 1`.278279При ошибке возвращает `(unsigned long long)-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.280281Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__), если доступно.282283Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__int__).284285#### `double PyLong_AsDouble(PyObject *pylong)`286287*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*288289Возвращает представление double на языке C для *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.13/c-api/long.html#c.PyLongObject).290291Возбуждает исключение [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для double.292293При ошибке возвращает `-1.0`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.294295#### `void *PyLong_AsVoidPtr(PyObject *pylong)`296297*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*298299Преобразует целое число Python *pylong* в указатель void на языке C. Если *pylong* не удаётся преобразовать, возбуждается исключение [`OverflowError`](https://python-all.ru/3.13/library/exceptions.html#OverflowError). Это гарантирует, что полученный указатель void будет пригоден для использования только для значений, созданных с помощью [`PyLong_FromVoidPtr()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_FromVoidPtr).300301При ошибке возвращает `NULL`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.302303#### `PyLong_AsPid(pid)`304305Макрос для преобразования целого числа Python в идентификатор процесса.306307Он может быть определён как псевдоним для [`PyLong_AsLong()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_AsLong), [`PyLong_FromLongLong()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_FromLongLong) или [`PyLong_AsInt()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_AsInt) в зависимости от размера типа PID в системе.308309Добавлено в версии 3.2.310311#### `Py_ssize_t PyLong_AsNativeBytes(PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)`312313Копирует значение целого числа Python *pylong* в нативный *buffer* размера *n\_bytes*. Флаг *flags* можно установить в `-1` для поведения, аналогичного приведению в C, или в значения, описанные ниже, для управления поведением.314315Возвращает `-1` с возбуждением исключения при ошибке. Это может произойти, если *pylong* не удаётся интерпретировать как целое число, или если *pylong* было отрицательным и был установлен флаг `Py_ASNATIVEBYTES_REJECT_NEGATIVE`.316317В противном случае возвращает количество байт, необходимое для хранения значения. Если оно меньше или равно *n\_bytes*, значение было скопировано целиком. Заполняются все *n\_bytes* буфера: оставшиеся байты заполняются копиями знакового бита.318319Если возвращённое значение больше *n\_bytes*, значение было усечено: записывается столько младших битов значения, сколько помещается, а старшие биты игнорируются. Это соответствует типичному поведению нисходящего приведения в стиле C.320321> **Примечание**322>323> Переполнение не считается ошибкой. Если возвращённое значение больше *n\_bytes*, старшие биты были отброшены.324325`0` никогда не будет возвращён.326327Значения всегда копируются в дополнительном коде.328329Пример использования:330331```c332int32_t value;333Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);334if (bytes < 0) {335    // Не удалось. Установлено исключение Python с указанием причины.336    return NULL;337}338else if (bytes <= (Py_ssize_t)sizeof(value)) {339    // Успешно!340}341else {342    // Произошло переполнение, но 'value' содержит усечённые343    // младшие биты pylong.344}345```346347Передача нуля в *n\_bytes* возвращает размер буфера, которого будет достаточно для хранения значения. Он может быть больше, чем технически необходимо, но не чрезмерно. Если *n\_bytes=0*, *buffer* может быть `NULL`.348349> **Примечание**350>351> Передача *n\_bytes=0* в эту функцию не является надёжным способом определения битовой длины значения.352353Чтобы получить всё значение Python неизвестного размера, функцию можно вызвать дважды: сначала для определения размера буфера, затем для его заполнения:354355```c356// Запрос необходимого объёма памяти.357Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);358if (expected < 0) {359    // Не удалось. Установлено исключение Python с указанием причины.360    return NULL;361}362assert(expected != 0);  // Невозможно согласно определению API.363uint8_t *bignum = malloc(expected);364if (!bignum) {365    PyErr_SetString(PyExc_MemoryError, "bignum malloc failed.");366    return NULL;367}368// Безопасно получить всё значение.369Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);370if (bytes < 0) {  // Установлено исключение.371    free(bignum);372    return NULL;373}374else if (bytes > expected) {  // Этого не должно быть возможно.375    PyErr_SetString(PyExc_RuntimeError,376        "Unexpected bignum truncation after a size check.");377    free(bignum);378    return NULL;379}380// Ожидаемый успех с учётом предварительной проверки выше.381// ... использовать bignum ...382free(bignum);383```384385*flags* может быть либо `-1` (`Py_ASNATIVEBYTES_DEFAULTS`) для выбора значений по умолчанию, поведение которых наиболее похоже на приведение C, либо комбинацией других флагов из таблицы ниже. Обратите внимание, что `-1` нельзя комбинировать с другими флагами.386387В настоящее время `-1` соответствует `Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER`.388389| Флаг | Значение |390| --- | --- |391| Py\_ASNATIVEBYTES\_DEFAULTS | `-1` |392| Py\_ASNATIVEBYTES\_BIG\_ENDIAN | `0` |393| Py\_ASNATIVEBYTES\_LITTLE\_ENDIAN | `1` |394| Py\_ASNATIVEBYTES\_NATIVE\_ENDIAN | `3` |395| Py\_ASNATIVEBYTES\_UNSIGNED\_BUFFER | `4` |396| Py\_ASNATIVEBYTES\_REJECT\_NEGATIVE | `8` |397| Py\_ASNATIVEBYTES\_ALLOW\_INDEX | `16` |398399Указание `Py_ASNATIVEBYTES_NATIVE_ENDIAN` переопределяет любые другие флаги порядка байтов. Передача `2` зарезервирована.400401По умолчанию будет запрошен буфер достаточного размера для включения знакового бита. Например, при преобразовании 128 с *n\_bytes=1* функция вернёт 2 (или больше), чтобы сохранить нулевой знаковый бит.402403Если указан `Py_ASNATIVEBYTES_UNSIGNED_BUFFER`, нулевой знаковый бит будет опущен при расчёте размера. Это позволяет, например, 128 поместиться в однобайтовый буфер. Если впоследствии целевой буфер будет трактоваться как знаковый, положительное входное значение может стать отрицательным. Обратите внимание, что флаг не влияет на обработку отрицательных значений: для них всегда запрашивается место под знаковый бит.404405Указание `Py_ASNATIVEBYTES_REJECT_NEGATIVE` приводит к установке исключения, если *pylong* отрицательно. Без этого флага отрицательные значения будут копироваться при условии, что достаточно места хотя бы для одного знакового бита, независимо от того, было ли указано `Py_ASNATIVEBYTES_UNSIGNED_BUFFER`.406407Если указан `Py_ASNATIVEBYTES_ALLOW_INDEX` и передано нецелое значение, сначала будет вызван его метод [`__index__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__index__). Это может привести к выполнению кода Python и возможности выполнения других потоков, что может вызвать изменения других объектов или используемых значений. Когда *flags* равно `-1`, эта опция не установлена, и нецелые значения вызовут [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError).408409> **Примечание**410>411> С флагами по умолчанию *flags* (`-1`, или *UNSIGNED\_BUFFER* без *REJECT\_NEGATIVE*) несколько целых чисел Python могут отображаться на одно значение без переполнения. Например, и `255`, и `-1` помещаются в однобайтовый буфер и устанавливают все его биты. Это соответствует типичному поведению приведения в C.412413Добавлено в версии 3.13.414415#### `PyObject *PyLong_GetInfo(void)`416417*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*418419В случае успеха возвращает доступный только для чтения [именованный кортеж](https://python-all.ru/3.13/glossary.html#term-named-tuple), содержащий информацию о внутреннем представлении целых чисел в Python. Описание отдельных полей см. в [`sys.int_info`](https://python-all.ru/3.13/library/sys.html#sys.int_info).420421При ошибке возвращает `NULL` с установленным исключением.422423Добавлено в версии 3.1.424425#### `int PyUnstable_Long_IsCompact(const PyLongObject *op)`426427> *Это [нестабильное API](https://python-all.ru/3.13/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*428429Возвращает 1, если *op* компактный, и 0 в противном случае.430431Эта функция позволяет критичному к производительности коду реализовать «быстрый путь» для малых целых чисел. Для компактных значений используйте [`PyUnstable_Long_CompactValue()`](https://python-all.ru/3.13/c-api/long.html#c.PyUnstable_Long_CompactValue); для остальных используйте [`PyLong_As*`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_AsSize_t) или [`PyLong_AsNativeBytes()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_AsNativeBytes).432433Ожидается, что ускорение будет незначительным для большинства пользователей.434435Какие именно значения считаются компактными, является деталью реализации и может измениться.436437Добавлено в версии 3.12.438439#### `Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)`440441> *Это [нестабильное API](https://python-all.ru/3.13/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*442443Если *op* компактный, как определено с помощью [`PyUnstable_Long_IsCompact()`](https://python-all.ru/3.13/c-api/long.html#c.PyUnstable_Long_IsCompact), вернуть его значение.444445В противном случае возвращаемое значение не определено.446447Добавлено в версии 3.12.448