Text of docs.python.org › 3.14 › c-api › long.html as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Integer Objects — Python 3.14.10 documentation

Navigation index modules | next | previous | Python » 3.14.10 documentation » Python/C API reference manual » Concrete Objects Layer » Integer Objects | Theme | 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 PyObject represents a Python integer object. PyTypeObject PyLong_Type ¶ Part of the Stable ABI . This instance of PyTypeObject represents the Python integer type. This is the same object as int in the Python layer. int PyLong_Check ( PyObject * p ) ¶ Return true if its argument is a PyLongObject or 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 PyLongObject object from v , or NULL on failure. CPython implementation detail: CPython keeps an array of integer objects for all integers between -5 and 256 . 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 PyLongObject object from a C unsigned long , or NULL on failure. PyObject * PyLong_FromSsize_t ( Py_ssize_t v ) ¶ Return value: New reference. Part of the Stable ABI . Return a new PyLongObject object from a C Py_ssize_t , or NULL on failure. PyObject * PyLong_FromSize_t ( size_t v ) ¶ Return value: New reference. Part of the Stable ABI . Return a new PyLongObject object from a C size_t , or NULL on failure.

PyObject * PyLong_FromLongLong ( long long v ) ¶ Return value: New reference. Part of the Stable ABI . Return a new PyLongObject object from a C long long , or NULL on failure. PyObject * PyLong_FromUnsignedLongLong ( unsigned long long v ) ¶ Return value: New reference. Part of the Stable ABI . Return a new PyLongObject object from a C unsigned long long , or NULL on failure. PyObject * PyLong_FromInt32 ( int32_t value ) ¶ PyObject * PyLong_FromInt64 ( int64_t value ) ¶ Part of the Stable ABI since version 3.14.

Return a new PyLongObject object from a signed C int32_t or int64_t , or NULL with an exception set on failure. Added in version 3.14. PyObject * PyLong_FromUInt32 ( uint32_t value ) ¶ PyObject * PyLong_FromUInt64 ( uint64_t value ) ¶ Part of the Stable ABI since version 3.14. Return a new PyLongObject object from an unsigned C uint32_t or uint64_t , or NULL with an exception set on failure. Added in version 3.14. PyObject * PyLong_FromDouble ( double v ) ¶ Return value: New reference.

Part of the Stable ABI . Return a new PyLongObject object from the integer part of v , or NULL on failure. PyObject * PyLong_FromString ( const char * str , char * * pend , int base ) ¶ Return value: New reference. Part of the Stable ABI . Return a new PyLongObject based on the string value in str , which is interpreted according to the radix in base , or NULL on failure. If pend is non- NULL , *pend will point to the end of str on success or to the first character that could not be processed on error.

If base is 0 , str is interpreted using the Integer literals definition; in this case, leading zeros in a non-zero decimal number raises a ValueError . If base is not 0 , it must be between 2 and 36 , inclusive. Leading and trailing whitespace and single underscores after a base specifier and between digits are ignored. If there are no digits or str is not NULL-terminated following the digits and trailing whitespace, ValueError will be raised.

See also PyLong_AsNativeBytes() and PyLong_FromNativeBytes() functions can be used to convert a PyLongObject to/from an array of bytes in base 256 . 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. Added 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() . PyObject * PyLong_FromNativeBytes ( const void * buffer , size_t n_bytes , int flags ) ¶ Part of the Stable ABI since version 3.14. Create a Python integer from the value contained in the first n_bytes of buffer , interpreted as a two’s-complement signed number. flags are as for PyLong_AsNativeBytes() .

Passing -1 will select the native endian that CPython was compiled with and assume that the most-significant bit is a sign bit. Passing Py_ASNATIVEBYTES_UNSIGNED_BUFFER will produce the same result as calling PyLong_FromUnsignedNativeBytes() . Other flags are ignored. Added in version 3.13. PyObject * PyLong_FromUnsignedNativeBytes ( const void * buffer , size_t n_bytes , int flags ) ¶ Part of the Stable ABI since version 3.14.

Create a Python integer from the value contained in the first n_bytes of buffer , interpreted as an unsigned number. flags are as for PyLong_AsNativeBytes() . Passing -1 will select the native endian that CPython was compiled with and assume that the most-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 to PyLong_FromLong() or PyLong_FromLongLong() , depending on the size of the system’s PID type. Added in version 3.2. 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 a PyLongObject . Raise OverflowError if the value of obj is out of range for a long .

Returns -1 on error. Use PyErr_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_AS_LONG ( PyObject * obj ) ¶ Exactly equivalent to the preferred PyLong_AsLong . In particular, it can fail with OverflowError or another exception. Soft deprecated since version 3.14. int PyLong_AsInt ( PyObject * obj ) ¶ Part of the Stable ABI since version 3.13.

Similar to PyLong_AsLong() , but store the result in a C int instead of a C long . Added in version 3.13. 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 a PyLongObject . If the value of obj is greater than LONG_MAX or less than LONG_MIN , set *overflow to 1 or -1 , respectively, and return -1 ; otherwise, set *overflow to 0 .

If any other exception occurs set *overflow to 0 and return -1 as usual. Returns -1 on error. Use PyErr_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 a PyLongObject .

Raise OverflowError if the value of obj is out of range for a long long . Returns -1 on error. Use PyErr_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

The rest of this page is on the live site.