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

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

В случае ошибки большинство API PyLong_As* возвращают (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 в случае сбоя.

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

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_FromInt32(int32_t value)

PyObject *PyLong_FromInt64(int64_t value)

Часть стабильного ABI начиная с версии 3.14.

Возвращает новый объект PyLongObject из знакового значения C-типа int32_t или int64_t либо NULL с установленным исключением в случае сбоя.

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

PyObject *PyLong_FromUInt32(uint32_t value)

PyObject *PyLong_FromUInt64(uint64_t value)

Часть стабильного ABI начиная с версии 3.14.

Возвращает новый объект PyLongObject из беззнакового значения C-типа uint32_t или uint64_t либо NULL с установленным исключением в случае сбоя.

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

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.

См. также

Функции PyLong_AsNativeBytes() и PyLong_FromNativeBytes() можно использовать для преобразования PyLongObject в массив байтов с основанием 256 и обратно.

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)

Возвращаемое значение: новая ссылка.

Преобразует последовательность цифр Юникода в строке 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)

Часть стабильного ABI начиная с версии 3.14.

Создаёт целое число 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)

Часть стабильного ABI начиная с версии 3.14.

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

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

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

PyLong_FromPid(pid)

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

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

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

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 в виде значения C-типа long. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он есть), чтобы преобразовать объект в PyLongObject.

Если значение 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 в виде значения C-типа long long. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он есть), чтобы преобразовать объект в PyLongObject.

Если значение 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)

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

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

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

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

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

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

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

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

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

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

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)

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

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

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

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

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

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

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

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

int PyLong_AsInt32(PyObject *obj, int32_t *value)

int PyLong_AsInt64(PyObject *obj, int64_t *value)

Входит в стабильный ABI с версии 3.14.

Установить *value в представление obj в виде знакового C-типа int32_t или int64_t.

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

Если значение obj выходит за допустимый диапазон, вызвать исключение OverflowError.

При успехе установить *value и вернуть 0. При ошибке установить исключение и вернуть -1.

value не должен быть NULL.

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

int PyLong_AsUInt32(PyObject *obj, uint32_t *value)

int PyLong_AsUInt64(PyObject *obj, uint64_t *value)

Входит в стабильный ABI с версии 3.14.

Установить *value в представление obj в виде беззнакового C-типа uint32_t или uint64_t.

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

• Если obj отрицателен, вызвать исключение ValueError.
• Если значение obj выходит за допустимый диапазон, вызвать исключение OverflowError.

При успехе установить *value и вернуть 0. При ошибке установить исключение и вернуть -1.

value не должен быть NULL.

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

double PyLong_AsDouble(PyObject *pylong)

Входит в стабильный ABI.

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

Вызвать исключение OverflowError, если значение pylong выходит за допустимый диапазон типа double.

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

void *PyLong_AsVoidPtr(PyObject *pylong)

Входит в стабильный 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)

Входит в стабильный ABI с версии 3.14.

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

В случае ошибки возвращает -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 Входит в стабильный ABI с версии 3.14.	-1
Py_ASNATIVEBYTES_BIG_ENDIAN Входит в стабильный ABI с версии 3.14.	0
Py_ASNATIVEBYTES_LITTLE_ENDIAN Входит в стабильный ABI с версии 3.14.	1
Py_ASNATIVEBYTES_NATIVE_ENDIAN Входит в стабильный ABI с версии 3.14.	3
Py_ASNATIVEBYTES_UNSIGNED_BUFFER Входит в стабильный ABI с версии 3.14.	4
Py_ASNATIVEBYTES_REJECT_NEGATIVE Входит в стабильный ABI с версии 3.14.	8
Py_ASNATIVEBYTES_ALLOW_INDEX Входит в стабильный ABI с версии 3.14.	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.

PyLong_AsPid(pid)

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

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

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

int PyLong_GetSign(PyObject *obj, int *sign)

Получить знак целочисленного объекта obj.

При успехе установить *sign в знак целого числа (0, -1 или +1 для нуля, отрицательного или положительного целого числа соответственно) и вернуть 0.

При ошибке вернуть -1, установив исключение. Эта функция всегда завершается успешно, если obj — PyLongObject или его подкласс.

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

int PyLong_IsPositive(PyObject *obj)

Проверить, является ли целочисленный объект obj положительным (obj > 0).

Если obj является экземпляром PyLongObject или его подклассом, вернуть 1, если он положительный, и 0 в противном случае. Иначе установить исключение и вернуть -1.

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

int PyLong_IsNegative(PyObject *obj)

Проверить, является ли целочисленный объект obj отрицательным (obj < 0).

Если obj является экземпляром PyLongObject или его подклассом, вернуть 1, если он отрицательный, и 0 в противном случае. Иначе установить исключение и вернуть -1.

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

int PyLong_IsZero(PyObject *obj)

Проверить, равен ли нулю целочисленный объект obj.

Если obj является экземпляром PyLongObject или его подклассом, вернуть 1, если он равен нулю, и 0 в противном случае. Иначе установить исключение и вернуть -1.

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

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.