Integer Objects¶
All integers are implemented as “long” integer objects of arbitrary size.
On error, most PyLong_As* APIs return (return type)-1 which cannot be
distinguished from a number.  Use PyErr_Occurred() to disambiguate.
- 
type PyLongObject¶
-  Part of the Limited API (as an opaque struct).This subtype of PyObjectrepresents a Python integer object.
- 
PyTypeObject PyLong_Type¶
-  Part of the Stable ABI.This instance of PyTypeObjectrepresents the Python integer type. This is the same object asintin the Python layer.
- 
int PyLong_Check(PyObject *p)¶
- Return true if its argument is a - PyLongObjector a subtype of- PyLongObject. This function always succeeds.
- 
int PyLong_CheckExact(PyObject *p)¶
- Return true if its argument is a - PyLongObject, but not a subtype of- PyLongObject. This function always succeeds.
- 
PyObject *PyLong_FromLong(long v)¶
- Return value: New reference. Part of the Stable ABI.Return a new PyLongObjectobject from v, orNULLon failure.The current implementation keeps an array of integer objects for all integers between -5and256. When you create an int in that range you actually just get back a reference to the existing object.
- 
PyObject *PyLong_FromUnsignedLong(unsigned long v)¶
- Return value: New reference. Part of the Stable ABI.Return a new PyLongObjectobject from a C unsigned long, orNULLon failure.
- 
PyObject *PyLong_FromSsize_t(Py_ssize_t v)¶
- Return value: New reference. Part of the Stable ABI.Return a new PyLongObjectobject from a CPy_ssize_t, orNULLon failure.
- 
PyObject *PyLong_FromSize_t(size_t v)¶
- Return value: New reference. Part of the Stable ABI.Return a new PyLongObjectobject from a Csize_t, orNULLon failure.
- 
PyObject *PyLong_FromLongLong(long long v)¶
- Return value: New reference. Part of the Stable ABI.Return a new PyLongObjectobject from a C long long, orNULLon failure.
- 
PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)¶
- Return value: New reference. Part of the Stable ABI.Return a new PyLongObjectobject from a C unsigned long long, orNULLon failure.
- 
PyObject *PyLong_FromDouble(double v)¶
- Return value: New reference. Part of the Stable ABI.Return a new PyLongObjectobject from the integer part of v, orNULLon failure.
- 
PyObject *PyLong_FromString(const char *str, char **pend, int base)¶
- Return value: New reference. Part of the Stable ABI.Return a new PyLongObjectbased on the string value in str, which is interpreted according to the radix in base. If pend is non-NULL, *pend will point to the first character in str which follows the representation of the number. If base is0, str is interpreted using the Integer literals definition; in this case, leading zeros in a non-zero decimal number raises aValueError. If base is not0, it must be between2and36, inclusive. Leading spaces and single underscores after a base specifier and between digits are ignored. If there are no digits,ValueErrorwill be raised.See also Python methods int.to_bytes()andint.from_bytes()to convert aPyLongObjectto/from an array of bytes in base256. You can call those from C usingPyObject_CallMethod().
- 
PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)¶
- Return value: New reference.Convert a sequence of Unicode digits in the string u to a Python integer value. New in version 3.3. 
- 
PyObject *PyLong_FromVoidPtr(void *p)¶
- Return value: New reference. Part of the Stable ABI.Create a Python integer from the pointer p. The pointer value can be retrieved from the resulting value using PyLong_AsVoidPtr().
- 
long PyLong_AsLong(PyObject *obj)¶
-  Part of the Stable ABI.Return a C long representation of obj. If obj is not an instance of PyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.Raise OverflowErrorif the value of obj is out of range for a long.Returns -1on 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__().
- 
long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)¶
-  Part of the Stable ABI.Return a C long representation of obj. If obj is not an instance of PyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.If the value of obj is greater than LONG_MAXor less thanLONG_MIN, set *overflow to1or-1, respectively, and return-1; otherwise, set *overflow to0. If any other exception occurs set *overflow to0and return-1as usual.Returns -1on 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__().
- 
long long PyLong_AsLongLong(PyObject *obj)¶
-  Part of the Stable ABI.Return a C long long representation of obj. If obj is not an instance of PyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.Raise OverflowErrorif the value of obj is out of range for a long long.Returns -1on 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__().
- 
long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)¶
-  Part of the Stable ABI.Return a C long long representation of obj. If obj is not an instance of PyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.If the value of obj is greater than LLONG_MAXor less thanLLONG_MIN, set *overflow to1or-1, respectively, and return-1; otherwise, set *overflow to0. If any other exception occurs set *overflow to0and return-1as usual.Returns -1on error. UsePyErr_Occurred()to disambiguate.New 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_t PyLong_AsSsize_t(PyObject *pylong)¶
-  Part of the Stable ABI.Return a C Py_ssize_trepresentation of pylong. pylong must be an instance ofPyLongObject.Raise OverflowErrorif the value of pylong is out of range for aPy_ssize_t.Returns -1on error. UsePyErr_Occurred()to disambiguate.
- 
unsigned long PyLong_AsUnsignedLong(PyObject *pylong)¶
-  Part of the Stable ABI.Return a C unsigned long representation of pylong. pylong must be an instance of PyLongObject.Raise OverflowErrorif the value of pylong is out of range for a unsigned long.Returns (unsigned long)-1on error. UsePyErr_Occurred()to disambiguate.
- 
size_t PyLong_AsSize_t(PyObject *pylong)¶
-  Part of the Stable ABI.Return a C size_trepresentation of pylong. pylong must be an instance ofPyLongObject.Raise OverflowErrorif the value of pylong is out of range for asize_t.Returns (size_t)-1on error. UsePyErr_Occurred()to disambiguate.
- 
unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)¶
-  Part of the Stable ABI.Return a C unsigned long long representation of pylong. pylong must be an instance of PyLongObject.Raise OverflowErrorif the value of pylong is out of range for an unsigned long long.Returns (unsigned long long)-1on error. UsePyErr_Occurred()to disambiguate.Changed in version 3.1: A negative pylong now raises OverflowError, notTypeError.
- 
unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)¶
-  Part of the Stable ABI.Return a C unsigned long representation of obj. If obj is not an instance of PyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.If the value of obj is out of range for an unsigned long, return the reduction of that value modulo ULONG_MAX + 1.Returns (unsigned long)-1on 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__().
- 
unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)¶
-  Part of the Stable ABI.Return a C unsigned long long representation of obj. If obj is not an instance of PyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.If the value of obj is out of range for an unsigned long long, return the reduction of that value modulo ULLONG_MAX + 1.Returns (unsigned long long)-1on 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__().
- 
double PyLong_AsDouble(PyObject *pylong)¶
-  Part of the Stable ABI.Return a C double representation of pylong. pylong must be an instance of PyLongObject.Raise OverflowErrorif the value of pylong is out of range for a double.Returns -1.0on error. UsePyErr_Occurred()to disambiguate.
- 
void *PyLong_AsVoidPtr(PyObject *pylong)¶
-  Part of the Stable ABI.Convert a Python integer pylong to a C void pointer. If pylong cannot be converted, an OverflowErrorwill be raised. This is only assured to produce a usable void pointer for values created withPyLong_FromVoidPtr().Returns NULLon error. UsePyErr_Occurred()to disambiguate.