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

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

При ошибке большинство 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. При создании int в этом диапазоне фактически возвращается ссылка на существующий объект.

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 интерпретируется в соответствии с определением Integer literals; в этом случае ведущие нули в ненулевом десятичном числе вызывают ValueError. Если base не равно 0, оно должно быть между 2 и 36 включительно. Начальные и конечные пробелы, а также одиночные символы подчёркивания после спецификатора основания и между цифрами игнорируются. Если цифр нет или str не завершается нулевым символом после цифр и конечных пробелов, будет вызвано 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.

PyLong_FromPid(pid)¶

Макрос для создания целого числа Python из идентификатора процесса.

Может быть определён как псевдоним PyLong_FromLong() или PyLong_FromLongLong() в зависимости от размера типа PID в системе.

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

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)¶: Полностью эквивалентна предпочтительной PyLong_AsLong. В частности, может завершиться ошибкой с OverflowError или другим исключением.

Soft deprecated since version 3.14.

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.

Возвращает представление unsigned long long на языке C для 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.

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

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

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

void *PyLong_AsVoidPtr(PyObject *pylong)¶

Часть Stable ABI.

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

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

PyLong_AsPid(pid)¶

Макрос для преобразования целого числа Python в идентификатор процесса.

Он может быть определён как псевдоним для PyLong_AsLong(), PyLong_FromLongLong() или PyLong_AsInt() в зависимости от размера типа PID в системе.

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

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 никогда не будет возвращён.

Значения всегда копируются в дополнительном коде.

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

int32_t value;
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);
if (bytes < 0) {
    // Не удалось. Установлено исключение Python с указанием причины.
    return NULL;
}
else if (bytes <= (Py_ssize_t)sizeof(value)) {
    // Успешно!
}
else {
    // Произошло переполнение, но 'value' содержит усечённые
    // младшие биты pylong.
}

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

Примечание

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

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

// Запрос необходимого объёма памяти.
Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);
if (expected < 0) {
    // Не удалось. Установлено исключение Python с указанием причины.
    return NULL;
}
assert(expected != 0);  // Невозможно согласно определению API.
uint8_t *bignum = malloc(expected);
if (!bignum) {
    PyErr_SetString(PyExc_MemoryError, "bignum malloc failed.");
    return NULL;
}
// Безопасно получить всё значение.
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);
if (bytes < 0) {  // Установлено исключение.
    free(bignum);
    return NULL;
}
else if (bytes > expected) {  // Этого не должно быть возможно.
    PyErr_SetString(PyExc_RuntimeError,
        "Unexpected bignum truncation after a size check.");
    free(bignum);
    return NULL;
}
// Ожидаемый успех с учётом предварительной проверки выше.
// ... использовать 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)¶

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

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

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

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

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

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

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)¶

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

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

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

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