Integer Objects¶

All integers are implemented as “long” integer objects of arbitrary size.

On error, mostPyLong_As* APIs return(returntype)-1 which cannot bedistinguished from a number. UsePyErr_Occurred() to disambiguate.

typePyLongObject¶

Part of theLimited API (as an opaque struct).

This subtype ofPyObject represents a Python integer object.

PyTypeObjectPyLong_Type¶

Part of theStable ABI.

This instance ofPyTypeObject represents the Python integer type.This is the same object asint in the Python layer.

intPyLong_Check(PyObject*p)¶

Return true if its argument is aPyLongObject or a subtype ofPyLongObject. This function always succeeds.

intPyLong_CheckExact(PyObject*p)¶

Return true if its argument is aPyLongObject, but not a subtype ofPyLongObject. This function always succeeds.

PyObject*PyLong_FromLong(longv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object fromv, orNULL on failure.

CPython implementation detail: CPython keeps an array of integer objects for all integersbetween-5 and256. When you create an int in that rangeyou actually just get back a reference to the existing object.

PyObject*PyLong_FromUnsignedLong(unsignedlongv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from a Cunsignedlong, orNULL on failure.

PyObject*PyLong_FromSsize_t(Py_ssize_tv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from a CPy_ssize_t, orNULL on failure.

PyObject*PyLong_FromSize_t(size_tv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from a Csize_t, orNULL on failure.

PyObject*PyLong_FromLongLong(longlongv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from a Clonglong, orNULLon failure.

PyObject*PyLong_FromInt32(int32_tvalue)¶

PyObject*PyLong_FromInt64(int64_tvalue)¶

Part of theStable ABI since version 3.14.

Return a newPyLongObject object from a signed Cint32_t orint64_t, orNULLwith an exception set on failure.

Added in version 3.14.

PyObject*PyLong_FromUnsignedLongLong(unsignedlonglongv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from a Cunsignedlonglong,orNULL on failure.

PyObject*PyLong_FromUInt32(uint32_tvalue)¶

PyObject*PyLong_FromUInt64(uint64_tvalue)¶

Part of theStable ABI since version 3.14.

Return a newPyLongObject object from an unsigned Cuint32_t oruint64_t, orNULLwith an exception set on failure.

Added in version 3.14.

PyObject*PyLong_FromDouble(doublev)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from the integer part ofv, orNULL on failure.

PyObject*PyLong_FromString(constchar*str,char**pend,intbase)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject based on the string value instr, whichis interpreted according to the radix inbase, orNULL on failure. Ifpend is non-NULL,*pend will point to the end ofstr on success orto the first character that could not be processed on error. Ifbase is0,str is interpreted using theInteger literals definition; in this case, leadingzeros in a non-zero decimal number raises aValueError. Ifbase is not0, it must be between2 and36, inclusive. Leading and trailingwhitespace and single underscores after a base specifier and between digits areignored. If there are no digits orstr is not NULL-terminated following thedigits and trailing whitespace,ValueError will be raised.

See also

PyLong_AsNativeBytes() andPyLong_FromNativeBytes() functions can be used to convertaPyLongObject to/from an array of bytes in base256.

PyObject*PyLong_FromUnicodeObject(PyObject*u,intbase)¶

Return value: New reference.

Convert a sequence of Unicode digits in the stringu to a Python integervalue.

Added in version 3.3.

PyObject*PyLong_FromVoidPtr(void*p)¶

Return value: New reference. Part of theStable ABI.

Create a Python integer from the pointerp. The pointer value can beretrieved from the resulting value usingPyLong_AsVoidPtr().

PyObject*PyLong_FromNativeBytes(constvoid*buffer,size_tn_bytes,intflags)¶

Part of theStable ABI since version 3.14.

Create a Python integer from the value contained in the firstn_bytes ofbuffer, interpreted as a two’s-complement signed number.

flags are as forPyLong_AsNativeBytes(). Passing-1 will selectthe native endian that CPython was compiled with and assume that themost-significant bit is a sign bit. PassingPy_ASNATIVEBYTES_UNSIGNED_BUFFER will produce the same result as callingPyLong_FromUnsignedNativeBytes(). Other flags are ignored.

Added in version 3.13.

PyObject*PyLong_FromUnsignedNativeBytes(constvoid*buffer,size_tn_bytes,intflags)¶

Part of theStable ABI since version 3.14.

Create a Python integer from the value contained in the firstn_bytes ofbuffer, interpreted as an unsigned number.

flags are as forPyLong_AsNativeBytes(). Passing-1 will selectthe native endian that CPython was compiled with and assume that themost-significant bit is not a sign bit. Flags other than endian are ignored.

Added in version 3.13.

PyLong_FromPid(pid)¶

Macro for creating a Python integer from a process identifier.

This can be defined as an alias toPyLong_FromLong() orPyLong_FromLongLong(), depending on the size of the system’sPID type.

Added in version 3.2.

longPyLong_AsLong(PyObject*obj)¶

Part of theStable ABI.

Return a Clong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__() method(if present) to convert it to aPyLongObject.

RaiseOverflowError if the value ofobj is out of range for along.

Returns-1 on error. UsePyErr_Occurred() to disambiguate.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

longPyLong_AS_LONG(PyObject*obj)¶

Asoft deprecated alias.Exactly equivalent to the preferredPyLong_AsLong. In particular,it can fail withOverflowError or another exception.

Deprecated since version 3.14:The function is soft deprecated.

intPyLong_AsInt(PyObject*obj)¶

Part of theStable ABI since version 3.13.

Similar toPyLong_AsLong(), but store the result in a Cint instead of a Clong.

Added in version 3.13.

longPyLong_AsLongAndOverflow(PyObject*obj,int*overflow)¶

Part of theStable ABI.

Return a Clong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.

If the value ofobj is greater thanLONG_MAX or less thanLONG_MIN, set*overflow to1 or-1, respectively, andreturn-1; otherwise, set*overflow to0. If any other exceptionoccurs set*overflow to0 and return-1 as usual.

Returns-1 on error. UsePyErr_Occurred() to disambiguate.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

longlongPyLong_AsLongLong(PyObject*obj)¶

Part of theStable ABI.

Return a Clonglong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__() method(if present) to convert it to aPyLongObject.

RaiseOverflowError if the value ofobj is out of range for alonglong.

Returns-1 on error. UsePyErr_Occurred() to disambiguate.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

longlongPyLong_AsLongLongAndOverflow(PyObject*obj,int*overflow)¶

Part of theStable ABI.

Return a Clonglong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__() method(if present) to convert it to aPyLongObject.

If the value ofobj is greater thanLLONG_MAX or less thanLLONG_MIN, set*overflow to1 or-1, respectively,and return-1; otherwise, set*overflow to0. If any otherexception occurs set*overflow to0 and return-1 as usual.

Returns-1 on error. UsePyErr_Occurred() to disambiguate.

Added in version 3.2.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

Py_ssize_tPyLong_AsSsize_t(PyObject*pylong)¶

Part of theStable ABI.

Return a CPy_ssize_t representation ofpylong.pylong mustbe an instance ofPyLongObject.

RaiseOverflowError if the value ofpylong is out of range for aPy_ssize_t.

Returns-1 on error. UsePyErr_Occurred() to disambiguate.

unsignedlongPyLong_AsUnsignedLong(PyObject*pylong)¶

Part of theStable ABI.

Return a Cunsignedlong representation ofpylong.pylongmust be an instance ofPyLongObject.

RaiseOverflowError if the value ofpylong is out of range for aunsignedlong.

Returns(unsignedlong)-1 on error.UsePyErr_Occurred() to disambiguate.

size_tPyLong_AsSize_t(PyObject*pylong)¶

Part of theStable ABI.

Return a Csize_t representation ofpylong.pylong must bean instance ofPyLongObject.

RaiseOverflowError if the value ofpylong is out of range for asize_t.

Returns(size_t)-1 on error.UsePyErr_Occurred() to disambiguate.

unsignedlonglongPyLong_AsUnsignedLongLong(PyObject*pylong)¶

Part of theStable ABI.

Return a Cunsignedlonglong representation ofpylong.pylongmust be an instance ofPyLongObject.

RaiseOverflowError if the value ofpylong is out of range for anunsignedlonglong.

Returns(unsignedlonglong)-1 on error.UsePyErr_Occurred() to disambiguate.

Changed in version 3.1:A negativepylong now raisesOverflowError, notTypeError.

unsignedlongPyLong_AsUnsignedLongMask(PyObject*obj)¶

Part of theStable ABI.

Return a Cunsignedlong representation ofobj. Ifobj is notan instance ofPyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.

If the value ofobj is out of range for anunsignedlong,return the reduction of that value moduloULONG_MAX+1.

Returns(unsignedlong)-1 on error. UsePyErr_Occurred() todisambiguate.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

unsignedlonglongPyLong_AsUnsignedLongLongMask(PyObject*obj)¶

Part of theStable ABI.

Return a Cunsignedlonglong representation ofobj. Ifobjis not an instance ofPyLongObject, first call its__index__() method (if present) to convert it to aPyLongObject.

If the value ofobj is out of range for anunsignedlonglong,return the reduction of that value moduloULLONG_MAX+1.

Returns(unsignedlonglong)-1 on error. UsePyErr_Occurred()to disambiguate.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

intPyLong_AsInt32(PyObject*obj,int32_t*value)¶

intPyLong_AsInt64(PyObject*obj,int64_t*value)¶

Part of theStable ABI since version 3.14.

Set*value to a signed Cint32_t orint64_trepresentation ofobj.

Ifobj is not an instance ofPyLongObject, first call its__index__() method (if present) to convert it to aPyLongObject.

If theobj value is out of range, raise anOverflowError.

Set*value and return0 on success.Set an exception and return-1 on error.

value must not beNULL.

Added in version 3.14.

intPyLong_AsUInt32(PyObject*obj,uint32_t*value)¶

intPyLong_AsUInt64(PyObject*obj,uint64_t*value)¶

Part of theStable ABI since version 3.14.

Set*value to an unsigned Cuint32_t oruint64_trepresentation ofobj.

Ifobj is not an instance ofPyLongObject, first call its__index__() method (if present) to convert it to aPyLongObject.

• Ifobj is negative, raise aValueError.

• If theobj value is out of range, raise anOverflowError.

Set*value and return0 on success.Set an exception and return-1 on error.

value must not beNULL.

Added in version 3.14.

doublePyLong_AsDouble(PyObject*pylong)¶

Part of theStable ABI.

Return a Cdouble representation ofpylong.pylong must bean instance ofPyLongObject.

RaiseOverflowError if the value ofpylong is out of range for adouble.

Returns-1.0 on error. UsePyErr_Occurred() to disambiguate.

void*PyLong_AsVoidPtr(PyObject*pylong)¶

Part of theStable ABI.

Convert a Python integerpylong to a Cvoid pointer.Ifpylong cannot be converted, anOverflowError will be raised. Thisis only assured to produce a usablevoid pointer for values createdwithPyLong_FromVoidPtr().

ReturnsNULL on error. UsePyErr_Occurred() to disambiguate.

Py_ssize_tPyLong_AsNativeBytes(PyObject*pylong,void*buffer,Py_ssize_tn_bytes,intflags)¶

Part of theStable ABI since version 3.14.

Copy the Python integer valuepylong to a nativebuffer of sizen_bytes. Theflags can be set to-1 to behave similarly to a C cast,or to values documented below to control the behavior.

Returns-1 with an exception raised on error. This may happen ifpylong cannot be interpreted as an integer, or ifpylong was negativeand thePy_ASNATIVEBYTES_REJECT_NEGATIVE flag was set.

Otherwise, returns the number of bytes required to store the value.If this is equal to or less thann_bytes, the entire value was copied.Alln_bytes of the buffer are written: large buffers are padded withzeroes.

If the returned value is greater thann_bytes, the value wastruncated: as many of the lowest bits of the value as could fit are written,and the higher bits are ignored. This matches the typical behaviorof a C-style downcast.

Note

Overflow is not considered an error. If the returned valueis larger thann_bytes, most significant bits were discarded.

0 will never be returned.

Values are always copied as two’s-complement.

Usage example:

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

Passing zero ton_bytes will return the size of a buffer that wouldbe large enough to hold the value. This may be larger than technicallynecessary, but not unreasonably so. Ifn_bytes=0,buffer may beNULL.

Note

Passingn_bytes=0 to this function is not an accurate way to determinethe bit length of the value.

To get at the entire Python value of an unknown size, the function can becalled twice: first to determine the buffer size, then to fill it:

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

flags is either-1 (Py_ASNATIVEBYTES_DEFAULTS) to select defaultsthat behave most like a C cast, or a combination of the other flags inthe table below.Note that-1 cannot be combined with other flags.

Currently,-1 corresponds toPy_ASNATIVEBYTES_NATIVE_ENDIAN|Py_ASNATIVEBYTES_UNSIGNED_BUFFER.

Flag	Value
Py_ASNATIVEBYTES_DEFAULTS¶ Part of theStable ABI since version 3.14.	-1
Py_ASNATIVEBYTES_BIG_ENDIAN¶ Part of theStable ABI since version 3.14.	0
Py_ASNATIVEBYTES_LITTLE_ENDIAN¶ Part of theStable ABI since version 3.14.	1
Py_ASNATIVEBYTES_NATIVE_ENDIAN¶ Part of theStable ABI since version 3.14.	3
Py_ASNATIVEBYTES_UNSIGNED_BUFFER¶ Part of theStable ABI since version 3.14.	4
Py_ASNATIVEBYTES_REJECT_NEGATIVE¶ Part of theStable ABI since version 3.14.	8
Py_ASNATIVEBYTES_ALLOW_INDEX¶ Part of theStable ABI since version 3.14.	16

SpecifyingPy_ASNATIVEBYTES_NATIVE_ENDIAN will override any other endianflags. Passing2 is reserved.

By default, sufficient buffer will be requested to include a sign bit.For example, when converting 128 withn_bytes=1, the function will return2 (or more) in order to store a zero sign bit.

IfPy_ASNATIVEBYTES_UNSIGNED_BUFFER is specified, a zero sign bitwill be omitted from size calculations. This allows, for example, 128 to fitin a single-byte buffer. If the destination buffer is later treated assigned, a positive input value may become negative.Note that the flag does not affect handling of negative values: for those,space for a sign bit is always requested.

SpecifyingPy_ASNATIVEBYTES_REJECT_NEGATIVE causes an exception to be setifpylong is negative. Without this flag, negative values will be copiedprovided there is enough space for at least one sign bit, regardless ofwhetherPy_ASNATIVEBYTES_UNSIGNED_BUFFER was specified.

IfPy_ASNATIVEBYTES_ALLOW_INDEX is specified and a non-integer value ispassed, its__index__() method will be called first. This mayresult in Python code executing and other threads being allowed to run, whichcould cause changes to other objects or values in use. Whenflags is-1, this option is not set, and non-integer values will raiseTypeError.

Note

With the defaultflags (-1, orUNSIGNED_BUFFER withoutREJECT_NEGATIVE), multiple Python integers can map to a single valuewithout overflow. For example, both255 and-1 fit a single-bytebuffer and set all its bits.This matches typical C cast behavior.

Added in version 3.13.

PyLong_AsPid(pid)¶

Macro for converting a Python integer into a process identifier.

This can be defined as an alias toPyLong_AsLong(),PyLong_FromLongLong(), orPyLong_AsInt(), depending on thesize of the system’s PID type.

Added in version 3.2.

intPyLong_GetSign(PyObject*obj,int*sign)¶

Get the sign of the integer objectobj.

On success, set*sign to the integer sign (0, -1 or +1 for zero, negative orpositive integer, respectively) and return 0.

On failure, return -1 with an exception set. This function always succeedsifobj is aPyLongObject or its subtype.

Added in version 3.14.

intPyLong_IsPositive(PyObject*obj)¶

Check if the integer objectobj is positive (obj>0).

Ifobj is an instance ofPyLongObject or its subtype,return1 when it’s positive and0 otherwise. Else set anexception and return-1.

Added in version 3.14.

intPyLong_IsNegative(PyObject*obj)¶

Check if the integer objectobj is negative (obj<0).

Ifobj is an instance ofPyLongObject or its subtype,return1 when it’s negative and0 otherwise. Else set anexception and return-1.

Added in version 3.14.

intPyLong_IsZero(PyObject*obj)¶

Check if the integer objectobj is zero.

Ifobj is an instance ofPyLongObject or its subtype,return1 when it’s zero and0 otherwise. Else set anexception and return-1.

Added in version 3.14.

PyObject*PyLong_GetInfo(void)¶

Part of theStable ABI.

On success, return a read onlynamed tuple, that holdsinformation about Python’s internal representation of integers.Seesys.int_info for description of individual fields.

On failure, returnNULL with an exception set.

Added in version 3.1.

intPyUnstable_Long_IsCompact(constPyLongObject*op)¶

This isUnstable API. It may change without warning in minor releases.

Return 1 ifop is compact, 0 otherwise.

This function makes it possible for performance-critical code to implementa “fast path” for small integers. For compact values usePyUnstable_Long_CompactValue(); for others fall back to aPyLong_As* function orPyLong_AsNativeBytes().

The speedup is expected to be negligible for most users.

Exactly what values are considered compact is an implementation detailand is subject to change.

Added in version 3.12.

Py_ssize_tPyUnstable_Long_CompactValue(constPyLongObject*op)¶

This isUnstable API. It may change without warning in minor releases.

Ifop is compact, as determined byPyUnstable_Long_IsCompact(),return its value.

Otherwise, the return value is undefined.

Added in version 3.12.