整数对象¶

所有整数都实现为任意大小的“长”整数对象。

出错时，大多数 PyLong_As* API 返回 (return type)-1，这无法与数字区分开。使用 PyErr_Occurred() 来消除歧义。

type PyLongObject¶: 属于有限 API的一部分（作为不透明结构）。
此 PyObject 的子类型表示一个 Python 整数对象。

PyTypeObject PyLong_Type¶: 属于稳定 ABI的一部分。
此 PyTypeObject 的实例表示 Python 整数类型。这与 Python 层中的 int 对象相同。

int PyLong_Check(PyObject *p)¶: 如果其参数是 PyLongObject 或 PyLongObject 的子类型，则返回 true。此函数始终成功。

int PyLong_CheckExact(PyObject *p)¶: 如果其参数是 PyLongObject，但不是 PyLongObject 的子类型，则返回 true。此函数始终成功。

PyObject *PyLong_FromLong(long v)¶

返回值：新引用。属于稳定 ABI 的一部分。

从 v 返回一个新的 PyLongObject 对象，失败时返回 NULL。

当前实现保留一个整数对象数组，用于介于 -5 和 256 之间的所有整数。当您创建该范围内的整数时，实际上只是获得对现有对象的引用。

PyObject *PyLong_FromUnsignedLong(unsigned long v)¶: 返回值：新引用。属于稳定 ABI 的一部分。
从 C unsigned long 返回一个新的 PyLongObject 对象，失败时返回 NULL。

PyObject *PyLong_FromSsize_t(Py_ssize_t v)¶: 返回值：新引用。属于稳定 ABI 的一部分。
从 C Py_ssize_t 返回一个新的 PyLongObject 对象，失败时返回 NULL。

PyObject *PyLong_FromSize_t(size_t v)¶: 返回值：新引用。属于稳定 ABI 的一部分。
从 C size_t 返回一个新的 PyLongObject 对象，失败时返回 NULL。

PyObject *PyLong_FromLongLong(long long v)¶: 返回值：新引用。属于稳定 ABI 的一部分。
从 C long long 返回一个新的 PyLongObject 对象，失败时返回 NULL。

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)¶: 返回值：新引用。属于稳定 ABI 的一部分。
从 C unsigned long long 返回一个新的 PyLongObject 对象，失败时返回 NULL。

PyObject *PyLong_FromDouble(double v)¶: 返回值：新引用。属于稳定 ABI 的一部分。
从 v 的整数部分返回一个新的 PyLongObject 对象，失败时返回 NULL。

PyObject *PyLong_FromString(const char *str, char **pend, int base)¶: 返回值：新引用。属于稳定 ABI 的一部分。
根据 base 中的基数解释 str 中的字符串值，返回一个新的 PyLongObject，失败时返回 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 为基数的字节数组转换。你可以使用 PyObject_CallMethod() 从 C 中调用这些方法。

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)¶: 返回值：新引用。
将字符串 *u* 中的 Unicode 数字序列转换为 Python 整数值。

在版本 3.3 中添加。

PyObject *PyLong_FromVoidPtr(void *p)¶: 返回值：新引用。属于稳定 ABI 的一部分。
从指针 *p* 创建一个 Python 整数。可以使用 PyLong_AsVoidPtr() 从结果值中检索指针值。

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

从 *buffer* 的前 *n_bytes* 个字节中包含的值创建一个 Python 整数，该值被解释为二进制补码有符号数。

*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)¶

从 *buffer* 的前 *n_bytes* 个字节中包含的值创建一个 Python 整数，该值被解释为无符号数。

*flags* 与 PyLong_AsNativeBytes() 相同。传递 -1 将选择 CPython 编译时使用的本机字节序，并假定最高有效位不是符号位。除了字节序之外的其他标志将被忽略。

在版本 3.13 中添加。

long PyLong_AsLong(PyObject *obj)¶

属于稳定 ABI的一部分。

返回 *obj* 的 C long 表示。如果 *obj* 不是 PyLongObject 的实例，则首先调用其 __index__() 方法（如果存在）将其转换为 PyLongObject。

如果 *obj* 的值超出 C long 的范围，则引发 OverflowError。

错误时返回 -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)¶: 自 3.13 版本以来是稳定 ABI 的一部分。
类似于 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。

如果 obj 的值超出 long long 的范围，则引发 OverflowError。

错误时返回 -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 的实例。

如果 pylong 的值超出 Py_ssize_t 的范围，则引发 OverflowError。

错误时返回 -1。使用 PyErr_Occurred() 来消除歧义。

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)¶

属于稳定 ABI的一部分。

返回 pylong 的 C unsigned long 表示形式。pylong 必须是 PyLongObject 的实例。

如果 pylong 的值超出 unsigned long 的范围，则引发 OverflowError。

错误时返回 (unsigned long)-1。使用 PyErr_Occurred() 来消除歧义。

size_t PyLong_AsSize_t(PyObject *pylong)¶

属于稳定 ABI的一部分。

返回 pylong 的 C size_t 表示形式。pylong 必须是 PyLongObject 的实例。

如果 pylong 的值超出 size_t 的范围，则引发 OverflowError。

错误时返回 (size_t)-1。使用 PyErr_Occurred() 来消除歧义。

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)¶

属于稳定 ABI的一部分。

返回 pylong 的 C unsigned long long 表示形式。pylong 必须是 PyLongObject 的实例。

如果 pylong 的值超出 unsigned long long 的范围，则引发 OverflowError。

错误时返回 (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__()。

double PyLong_AsDouble(PyObject *pylong)¶

属于稳定 ABI的一部分。

返回 pylong 的 C double 表示形式。pylong 必须是 PyLongObject 的实例。

如果 pylong 的值超出 double 的范围，则引发 OverflowError。

出错时返回 -1.0。使用 PyErr_Occurred() 来消除歧义。

void *PyLong_AsVoidPtr(PyObject *pylong)¶

属于稳定 ABI的一部分。

将 Python 整数 pylong 转换为 C void 指针。如果 pylong 无法转换，则会引发 OverflowError。这仅保证对于使用 PyLong_FromVoidPtr() 创建的值生成可用的 void 指针。

出错时返回 NULL。使用 PyErr_Occurred() 来消除歧义。

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

将 Python 整数值 pylong 复制到大小为 n_bytes 的原生 buffer 中。可以将 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 是保留的。

默认情况下，将请求足够的缓冲区以包含符号位。例如，当使用 n_bytes=1 转换 128 时，该函数将返回 2（或更多），以便存储零符号位。

如果指定 Py_ASNATIVEBYTES_UNSIGNED_BUFFER，则会在大小计算中省略零符号位。这允许例如将 128 放入单字节缓冲区中。如果目标缓冲区稍后被视为有符号的，则正输入值可能会变为负数。请注意，该标志不影响负值的处理：对于负值，始终会请求符号位的空间。

如果 pylong 为负数，则指定 Py_ASNATIVEBYTES_REJECT_NEGATIVE 会导致设置异常。如果没有此标志，只要有足够的空间容纳至少一个符号位，无论是否指定了 Py_ASNATIVEBYTES_UNSIGNED_BUFFER，都会复制负值。

如果指定了 Py_ASNATIVEBYTES_ALLOW_INDEX 并且传递了非整数值，则将首先调用其 __index__() 方法。这可能会导致 Python 代码执行并允许其他线程运行，这可能会导致正在使用的其他对象或值发生更改。当 flags 为 -1 时，不会设置此选项，并且非整数值将引发 TypeError。

注意

使用默认的 flags（-1，或没有 REJECT_NEGATIVE 的 UNSIGNED_BUFFER），多个 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。它可能会在次要版本中更改，恕不另行通知。

如果 op 是紧凑的，则返回 1，否则返回 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 中添加。

整数对象¶

上一主题

下一主题

本页