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

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

При возникновении ошибки большинство функций API PyLong_As* возвращают (return type)-1, которое невозможно отличить от числа. Используйте PyErr_Occurred() для устранения неоднозначности.

type PyLongObject: Часть Limited API (как непрозрачная структура).
Этот подтип PyObject представляет целочисленный объект Python.

PyTypeObject PyLong_Type: Часть Stable ABI.
Этот экземпляр PyTypeObject представляет целочисленный тип Python. Это тот же объект, что и int на уровне Python.

int PyLong_Check(PyObject *p): Возвращает истину, если аргумент является PyLongObject или подтипом PyLongObject. Эта функция всегда завершается успешно.

int PyLong_CheckExact(PyObject *p): Возвращает истину, если аргумент является PyLongObject, но не подтипом PyLongObject. Эта функция всегда завершается успешно.

PyObject *PyLong_FromLong(long v): Возвращаемое значение: Новая ссылка. Часть Stable ABI.
Возвращает новый объект PyLongObject из v или NULL в случае неудачи.

Особенности реализации CPython: CPython хранит массив целочисленных объектов для всех целых чисел в диапазоне от -5 до 256. При создании целого числа в этом диапазоне вы фактически получаете ссылку на уже существующий объект.

PyObject *PyLong_FromUnsignedLong(unsigned long v): Возвращаемое значение: Новая ссылка. Часть Stable ABI.
Возвращает новый объект PyLongObject из C-значения unsigned long или NULL в случае неудачи.

PyObject *PyLong_FromSsize_t(Py_ssize_t v): Возвращаемое значение: Новая ссылка. Часть Stable ABI.
Возвращает новый объект PyLongObject из C-значения Py_ssize_t или NULL в случае неудачи.

PyObject *PyLong_FromSize_t(size_t v): Возвращаемое значение: Новая ссылка. Часть Stable ABI.
Возвращает новый объект PyLongObject из C-значения size_t или NULL в случае неудачи.

PyObject *PyLong_FromLongLong(long long v): Возвращаемое значение: Новая ссылка. Часть Stable ABI.
Возвращает новый объект PyLongObject из C-значения long long или NULL в случае неудачи.

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v): Возвращаемое значение: Новая ссылка. Часть Stable ABI.
Возвращает новый объект PyLongObject из C-значения unsigned long long или NULL в случае неудачи.

PyObject *PyLong_FromDouble(double v): Возвращаемое значение: Новая ссылка. Часть Stable ABI.
Возвращает новый объект PyLongObject из целой части v или NULL в случае неудачи.

PyObject *PyLong_FromString(const char *str, char **pend, int base): Возвращаемое значение: Новая ссылка. Часть Stable ABI.
Возвращает новый PyLongObject на основе строкового значения в str, интерпретируемого в соответствии с основанием системы счисления в base, или NULL в случае неудачи. Если pend не равен NULL, *pend будет указывать на конец str при успешном выполнении или на первый символ, который не удалось обработать, при ошибке. Если base равен 0, str интерпретируется с использованием определения Целочисленные литералы; в этом случае ведущие нули в ненулевом десятичном числе вызывают ValueError. Если base не равен 0, он должен находиться в диапазоне от 2 до 36 включительно. Начальные и конечные пробельные символы, а также одиночные символы подчеркивания после спецификатора основания и между цифрами игнорируются. Если цифры отсутствуют или строка str не заканчивается символом NULL после цифр и конечных пробельных символов, будет вызвано исключение ValueError.

См. также

Методы Python int.to_bytes() и int.from_bytes() для преобразования PyLongObject в массив байтов с основанием 256 и обратно. Их можно вызвать из C с помощью PyObject_CallMethod().

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base): Возвращаемое значение: Новая ссылка.
Преобразует последовательность символов-цифр Unicode в строке u в целочисленное значение Python.

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

PyObject *PyLong_FromVoidPtr(void *p): Возвращаемое значение: Новая ссылка. Часть Stable ABI.
Создает целое число Python из указателя p. Значение указателя можно получить из результирующего значения с помощью PyLong_AsVoidPtr().

PyObject *PyLong_FromNativeBytes(const void *buffer, size_t n_bytes, int flags)

Создает целое число Python из значения, содержащегося в первых n_bytes буфера buffer, интерпретируемого как число со знаком в дополнительном коде.

Параметр flags аналогичен PyLong_AsNativeBytes(). Передача -1 выберет нативный порядок байтов, с которым был скомпилирован CPython, и будет считать, что старший бит является знаковым. Передача Py_ASNATIVEBYTES_UNSIGNED_BUFFER даст тот же результат, что и вызов PyLong_FromUnsignedNativeBytes(). Другие флаги игнорируются.

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

PyObject *PyLong_FromUnsignedNativeBytes(const void *buffer, size_t n_bytes, int flags)

Создает целое число Python из значения, содержащегося в первых n_bytes буфера buffer, интерпретируемого как число без знака.

Параметр flags аналогичен PyLong_AsNativeBytes(). Передача -1 выберет нативный порядок байтов, с которым был скомпилирован CPython, и будет считать, что старший бит не является знаковым. Флаги, отличные от порядка байтов, игнорируются.

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

long PyLong_AsLong(PyObject *obj)

Часть Stable ABI.

Возвращает C-представление типа long для obj. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он присутствует), чтобы преобразовать его в PyLongObject.

Вызывает исключение OverflowError, если значение obj выходит за пределы диапазона для long.

Возвращает -1 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.8: Использовать __index__(), если доступен.

Изменено в версии 3.10: Эта функция больше не будет использовать __int__().

long PyLong_AS_LONG(PyObject *obj): Псевдоним со статусом soft deprecated. Полностью эквивалентен предпочтительному PyLong_AsLong. В частности, он может завершиться ошибкой OverflowError или другим исключением.

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

int PyLong_AsInt(PyObject *obj): Часть Stable ABI начиная с версии 3.13.
Аналогично PyLong_AsLong(), но сохраняет результат в C int вместо C long.

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

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

Часть Stable ABI.

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

Возвращает -1 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.8: Использовать __index__(), если доступен.

Изменено в версии 3.10: Эта функция больше не будет использовать __int__().

long long PyLong_AsLongLong(PyObject *obj)

Часть Stable ABI.

Возвращает C-представление типа long long для obj. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он присутствует), чтобы преобразовать его в PyLongObject.

Вызывает исключение OverflowError, если значение obj выходит за пределы диапазона для long long.

Возвращает -1 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.8: Использовать __index__(), если доступен.

Изменено в версии 3.10: Эта функция больше не будет использовать __int__().

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

Часть Stable ABI.

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

Возвращает -1 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

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

Изменено в версии 3.8: Использовать __index__(), если доступен.

Изменено в версии 3.10: Эта функция больше не будет использовать __int__().

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

Часть Stable ABI.

Возвращает C-представление типа Py_ssize_t для pylong. pylong должен быть экземпляром PyLongObject.

Вызывает исключение OverflowError, если значение pylong выходит за пределы диапазона для Py_ssize_t.

Возвращает -1 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

Часть Stable ABI.

Возвращает C-представление типа unsigned long для pylong. pylong должен быть экземпляром PyLongObject.

Вызывает исключение OverflowError, если значение pylong выходит за пределы диапазона для unsigned long.

Возвращает (unsigned long)-1 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

size_t PyLong_AsSize_t(PyObject *pylong)

Часть Stable ABI.

Возвращает C-представление типа size_t для pylong. pylong должен быть экземпляром PyLongObject.

Вызывает исключение OverflowError, если значение pylong выходит за пределы диапазона для size_t.

Возвращает (size_t)-1 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

Часть Stable ABI.

Возвращает C-представление типа unsigned long long для pylong. pylong должен быть экземпляром PyLongObject.

Вызывает исключение OverflowError, если значение pylong выходит за пределы диапазона для unsigned long long.

Возвращает (unsigned long long)-1 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.1: Отрицательное значение pylong теперь вызывает исключение OverflowError, а не TypeError.

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)

Часть Stable ABI.

Возвращает C-представление типа unsigned long для obj. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он присутствует), чтобы преобразовать его в PyLongObject.

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

Возвращает (unsigned long)-1 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.8: Использовать __index__(), если доступен.

Изменено в версии 3.10: Эта функция больше не будет использовать __int__().

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)

Часть Stable ABI.

Возвращает C-представление типа unsigned long long для obj. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он присутствует), чтобы преобразовать его в PyLongObject.

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

Возвращает (unsigned long long)-1 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.8: Использовать __index__(), если доступен.

Изменено в версии 3.10: Эта функция больше не будет использовать __int__().

double PyLong_AsDouble(PyObject *pylong)

Часть Stable ABI.

Возвращает C-представление типа double для pylong. pylong должен быть экземпляром PyLongObject.

Вызывает исключение OverflowError, если значение pylong выходит за пределы диапазона для double.

Возвращает -1.0 при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

void *PyLong_AsVoidPtr(PyObject *pylong)

Часть Stable ABI.

Преобразует целое число Python pylong в указатель C void. Если pylong не может быть преобразован, будет вызвано исключение OverflowError. Корректный пригодный к использованию указатель void гарантированно возвращается только для значений, созданных с помощью PyLong_FromVoidPtr().

Возвращает NULL при ошибке. Используйте PyErr_Occurred() для устранения неоднозначности.

Py_ssize_t PyLong_AsNativeBytes(PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)

Копирует целочисленное значение Python pylong в нативный буфер buffer размера n_bytes. Параметр flags может быть установлен в -1 для поведения, аналогичного приведению типов в C, или в значения, описанные ниже, для управления поведением.

Возвращает -1 с возбуждением исключения при ошибке. Это может произойти, если pylong не может быть интерпретирован как целое число или если pylong был отрицательным, а флаг Py_ASNATIVEBYTES_REJECT_NEGATIVE был установлен.

В противном случае возвращает количество байтов, необходимое для сохранения значения. Если оно меньше или равно n_bytes, значение было скопировано полностью. Записываются все n_bytes буфера: большие буферы дополняются нулями.

Если возвращаемое значение больше n_bytes, значение было усечено: записывается столько младших битов значения, сколько поместилось, а старшие биты игнорируются. Это соответствует типичному поведению понижающего приведения типов в стиле C.

Примечание

Переполнение не считается ошибкой. Если возвращаемое значение больше n_bytes, старшие значащие биты были отброшены.

0 никогда не возвращается.

Значения всегда копируются в дополнительном коде (two’s-complement).

Пример использования:

int32_t value;
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);
if (bytes < 0) {
    // Failed. A Python exception was set with the reason.
    return NULL;
}
else if (bytes <= (Py_ssize_t)sizeof(value)) {
    // Success!
}
else {
    // Overflow occurred, but 'value' contains the truncated
    // lowest bits of pylong.
}

Передача нуля в n_bytes вернет размер буфера, который был бы достаточным для хранения значения. Он может быть больше, чем технически необходимо, но в разумных пределах. Если n_bytes=0, buffer может быть равен NULL.

Примечание

Передача n_bytes=0 в эту функцию не является точным способом определения битовой длины значения.

Чтобы получить все значение Python неизвестного размера, функцию можно вызвать дважды: сначала для определения размера буфера, затем для его заполнения:

// Ask how much space we need.
Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);
if (expected < 0) {
    // Failed. A Python exception was set with the reason.
    return NULL;
}
assert(expected != 0);  // Impossible per the API definition.
uint8_t *bignum = malloc(expected);
if (!bignum) {
    PyErr_SetString(PyExc_MemoryError, "bignum malloc failed.");
    return NULL;
}
// Safely get the entire value.
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);
if (bytes < 0) {  // Exception has been set.
    free(bignum);
    return NULL;
}
else if (bytes > expected) {  // This should not be possible.
    PyErr_SetString(PyExc_RuntimeError,
        "Unexpected bignum truncation after a size check.");
    free(bignum);
    return NULL;
}
// The expected success given the above pre-check.
// ... use bignum ...
free(bignum);

Параметр flags задается либо как -1 (Py_ASNATIVEBYTES_DEFAULTS) для выбора значений по умолчанию, наиболее близких к приведению типов в C, либо как комбинация других флагов из таблицы ниже. Обратите внимание, что -1 нельзя комбинировать с другими флагами.

В настоящее время -1 соответствует Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER.

Флаг	Значение
`Py_ASNATIVEBYTES_DEFAULTS`	`-1`
`Py_ASNATIVEBYTES_BIG_ENDIAN`	`0`
`Py_ASNATIVEBYTES_LITTLE_ENDIAN`	`1`
`Py_ASNATIVEBYTES_NATIVE_ENDIAN`	`3`
`Py_ASNATIVEBYTES_UNSIGNED_BUFFER`	`4`
`Py_ASNATIVEBYTES_REJECT_NEGATIVE`	`8`
`Py_ASNATIVEBYTES_ALLOW_INDEX`	`16`

Указание Py_ASNATIVEBYTES_NATIVE_ENDIAN переопределит любые другие флаги порядка байтов. Передача 2 зарезервирована.

По умолчанию запрашивается буфер достаточного размера, чтобы включить знаковый бит. Например, при преобразовании 128 с n_bytes=1 функция вернет 2 (или больше), чтобы сохранить нулевой знаковый бит.

Если указан флаг Py_ASNATIVEBYTES_UNSIGNED_BUFFER, нулевой знаковый бит будет исключен из расчетов размера. Это позволяет, например, числу 128 поместиться в однобайтовый буфер. Если буфер назначения позже будет рассматриваться как знаковый, положительное входное значение может стать отрицательным. Обратите внимание, что этот флаг не влияет на обработку отрицательных значений: для них место под знаковый бит запрашивается всегда.

Указание Py_ASNATIVEBYTES_REJECT_NEGATIVE приводит к установке исключения, если pylong отрицателен. Без этого флага отрицательные значения будут скопированы при условии, что места достаточно хотя бы для одного знакового бита, независимо от того, был ли указан флаг Py_ASNATIVEBYTES_UNSIGNED_BUFFER.

Если указан флаг Py_ASNATIVEBYTES_ALLOW_INDEX и передано нецелочисленное значение, сначала будет вызван его метод __index__(). Это может привести к выполнению кода Python и переключению на другие потоки, что может повлечь за собой изменение других используемых объектов или значений. Если flags равен -1, эта опция не установлена, и нецелочисленные значения вызовут TypeError.

Примечание

При флагах flags по умолчанию (-1 или UNSIGNED_BUFFER без REJECT_NEGATIVE) несколько целых чисел Python могут отображаться в одно значение без переполнения. Например, как 255, так и -1 помещаются в однобайтовый буфер и устанавливают все его биты. Это соответствует типичному поведению приведения типов в C.

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

PyObject *PyLong_GetInfo(void)

Часть Stable ABI.

При успешном выполнении возвращает доступный только для чтения именованный кортеж, содержащий информацию о внутреннем представлении целых чисел в Python. Описание отдельных полей см. в sys.int_info.

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

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

int PyUnstable_Long_IsCompact(const PyLongObject *op)

Это Unstable API. Оно может изменяться без предварительного уведомления в минорных релизах.

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

Эта функция позволяет критичному к производительности коду реализовывать «быстрый путь» (fast path) для небольших целых чисел. Для компактных значений используйте PyUnstable_Long_CompactValue(); для остальных переходите на функции PyLong_As* или PyLong_AsNativeBytes().

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

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

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

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)

Это Unstable API. Оно может изменяться без предварительного уведомления в минорных релизах.

Если op является компактным, как определено с помощью PyUnstable_Long_IsCompact(), возвращает его значение.

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

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