Целые объекты

Все целые числа реализуются как объекты “long” произвольного размера.

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

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

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

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

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

PyObject *PyLong_FromLong(long v)

Значение возврата: Новая ссылка. Часть Стабильного ABI.

Возвращает новый объект PyLongObject из v или NULL при ошибке.

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

PyObject *PyLong_FromUnsignedLong(unsigned long v): Значение возврата: Новая ссылка. Часть Стабильного ABI.
Возвращает новый объект PyLongObject из C unsigned long, или NULL при ошибке.

PyObject *PyLong_FromSsize_t(Py_ssize_t v): Значение возврата: Новая ссылка. Часть Стабильного ABI.
Возвращает новый объект PyLongObject из C Py_ssize_t, или NULL при ошибке.

PyObject *PyLong_FromSize_t(size_t v): Значение возврата: Новая ссылка. Часть Стабильного ABI.
Возвращает новый объект PyLongObject из C size_t, или NULL при ошибке.

PyObject *PyLong_FromLongLong(long long v): Значение возврата: Новая ссылка. Часть Стабильного ABI.
Возвращает новый объект PyLongObject из C long long, или NULL при ошибке.

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v): Значение возврата: Новая ссылка. Часть Стабильного ABI.
Возвращает новый объект PyLongObject из C unsigned long long, или NULL при ошибке.

PyObject *PyLong_FromDouble(double v): Значение возврата: Новая ссылка. Часть Стабильного ABI.
Возвращает новый объект PyLongObject из целой части v, или NULL при ошибке.

PyObject *PyLong_FromString(const char *str, char **pend, int base): Значение возврата: Новая ссылка. Часть Стабильного ABI.
Возвращает новый объект PyLongObject на основе строкового значения в str, которое интерпретируется в соответствии с основанием в base, или NULL при ошибке. Если pend не NULL, *pend будет указывать на конец str при успехе или на первый символ, который не мог быть обработан при ошибке. Если base равно 0, str интерпретируется в соответствии с определением Целочисленных литералов; в этом случае ведущие нули в не-нулевом десятичном числе вызывают 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): Значение возврата: Новая ссылка. Часть Стабильного 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.

END_OF_DOCUMENT_MARKER

long PyLong_AsLong(PyObject *obj)

Часть Стабильной ABI.

Возвращает представление значения obj в виде C long. Если 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 или другое исключение.

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

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

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

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

Часть Стабильной 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)

Часть Стабильной ABI.

Возвращает представление значения obj в виде C long long. Если 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)

Часть Стабильной 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)

Часть Стабильной ABI.

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

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

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

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

Часть Стабильной ABI.

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

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

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

size_t PyLong_AsSize_t(PyObject *pylong)

Часть Стабильного API.

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

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

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

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

Часть Стабильного API.

Возвращает 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)

Часть Стабильного API.

Возвращает 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)

Часть Стабильного API.

Возвращает 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)

Часть Стабильного API.

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

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

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

void *PyLong_AsVoidPtr(PyObject *pylong)

Часть Стабильного API.

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

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

END_OF_DOCUMENT_MARKER

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) {
    // 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.

Примечание

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

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

PyObject *PyLong_GetInfo(void)

Часть Стабильной 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.