Number Protocol¶

intPyNumber_Check(PyObject*o)¶

Part of theStable ABI.

Returns1 if the objecto provides numeric protocols, and false otherwise.This function always succeeds.

Changed in version 3.8:Returns1 ifo is an index integer.

PyObject*PyNumber_Add(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the result of addingo1 ando2, orNULL on failure. This is theequivalent of the Python expressiono1+o2.

PyObject*PyNumber_Subtract(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the result of subtractingo2 fromo1, orNULL on failure. This isthe equivalent of the Python expressiono1-o2.

PyObject*PyNumber_Multiply(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the result of multiplyingo1 ando2, orNULL on failure. This isthe equivalent of the Python expressiono1*o2.

PyObject*PyNumber_MatrixMultiply(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI since version 3.7.

Returns the result of matrix multiplication ono1 ando2, orNULL onfailure. This is the equivalent of the Python expressiono1@o2.

Added in version 3.5.

PyObject*PyNumber_FloorDivide(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Return the floor ofo1 divided byo2, orNULL on failure. This isthe equivalent of the Python expressiono1//o2.

PyObject*PyNumber_TrueDivide(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Return a reasonable approximation for the mathematical value ofo1 divided byo2, orNULL on failure. The return value is “approximate” because binaryfloating-point numbers are approximate; it is not possible to represent all realnumbers in base two. This function can return a floating-point value whenpassed two integers. This is the equivalent of the Python expressiono1/o2.

PyObject*PyNumber_Remainder(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the remainder of dividingo1 byo2, orNULL on failure. This isthe equivalent of the Python expressiono1%o2.

PyObject*PyNumber_Divmod(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

See the built-in functiondivmod(). ReturnsNULL on failure. This isthe equivalent of the Python expressiondivmod(o1,o2).

PyObject*PyNumber_Power(PyObject*o1,PyObject*o2,PyObject*o3)¶

Return value: New reference. Part of theStable ABI.

See the built-in functionpow(). ReturnsNULL on failure. This is theequivalent of the Python expressionpow(o1,o2,o3), whereo3 is optional.Ifo3 is to be ignored, passPy_None in its place (passingNULL foro3 would cause an illegal memory access).

PyObject*PyNumber_Negative(PyObject*o)¶

Return value: New reference. Part of theStable ABI.

Returns the negation ofo on success, orNULL on failure. This is theequivalent of the Python expression-o.

PyObject*PyNumber_Positive(PyObject*o)¶

Return value: New reference. Part of theStable ABI.

Returnso on success, orNULL on failure. This is the equivalent of thePython expression+o.

PyObject*PyNumber_Absolute(PyObject*o)¶

Return value: New reference. Part of theStable ABI.

Returns the absolute value ofo, orNULL on failure. This is the equivalentof the Python expressionabs(o).

PyObject*PyNumber_Invert(PyObject*o)¶

Return value: New reference. Part of theStable ABI.

Returns the bitwise negation ofo on success, orNULL on failure. This isthe equivalent of the Python expression~o.

PyObject*PyNumber_Lshift(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the result of left shiftingo1 byo2 on success, orNULL onfailure. This is the equivalent of the Python expressiono1<<o2.

PyObject*PyNumber_Rshift(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the result of right shiftingo1 byo2 on success, orNULL onfailure. This is the equivalent of the Python expressiono1>>o2.

PyObject*PyNumber_And(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the “bitwise and” ofo1 ando2 on success andNULL on failure.This is the equivalent of the Python expressiono1&o2.

PyObject*PyNumber_Xor(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the “bitwise exclusive or” ofo1 byo2 on success, orNULL onfailure. This is the equivalent of the Python expressiono1^o2.

PyObject*PyNumber_Or(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the “bitwise or” ofo1 ando2 on success, orNULL on failure.This is the equivalent of the Python expressiono1|o2.

PyObject*PyNumber_InPlaceAdd(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the result of addingo1 ando2, orNULL on failure. The operationis donein-place wheno1 supports it. This is the equivalent of the Pythonstatemento1+=o2.

PyObject*PyNumber_InPlaceSubtract(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the result of subtractingo2 fromo1, orNULL on failure. Theoperation is donein-place wheno1 supports it. This is the equivalent ofthe Python statemento1-=o2.

PyObject*PyNumber_InPlaceMultiply(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the result of multiplyingo1 ando2, orNULL on failure. Theoperation is donein-place wheno1 supports it. This is the equivalent ofthe Python statemento1*=o2.

PyObject*PyNumber_InPlaceMatrixMultiply(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI since version 3.7.

Returns the result of matrix multiplication ono1 ando2, orNULL onfailure. The operation is donein-place wheno1 supports it. This isthe equivalent of the Python statemento1@=o2.

Added in version 3.5.

PyObject*PyNumber_InPlaceFloorDivide(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the mathematical floor of dividingo1 byo2, orNULL on failure.The operation is donein-place wheno1 supports it. This is the equivalentof the Python statemento1//=o2.

PyObject*PyNumber_InPlaceTrueDivide(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Return a reasonable approximation for the mathematical value ofo1 divided byo2, orNULL on failure. The return value is “approximate” because binaryfloating-point numbers are approximate; it is not possible to represent all realnumbers in base two. This function can return a floating-point value whenpassed two integers. The operation is donein-place wheno1 supports it.This is the equivalent of the Python statemento1/=o2.

PyObject*PyNumber_InPlaceRemainder(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the remainder of dividingo1 byo2, orNULL on failure. Theoperation is donein-place wheno1 supports it. This is the equivalent ofthe Python statemento1%=o2.

PyObject*PyNumber_InPlacePower(PyObject*o1,PyObject*o2,PyObject*o3)¶

Return value: New reference. Part of theStable ABI.

See the built-in functionpow(). ReturnsNULL on failure. The operationis donein-place wheno1 supports it. This is the equivalent of the Pythonstatemento1**=o2 when o3 isPy_None, or an in-place variant ofpow(o1,o2,o3) otherwise. Ifo3 is to be ignored, passPy_Nonein its place (passingNULL foro3 would cause an illegal memory access).

PyObject*PyNumber_InPlaceLshift(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the result of left shiftingo1 byo2 on success, orNULL onfailure. The operation is donein-place wheno1 supports it. This is theequivalent of the Python statemento1<<=o2.

PyObject*PyNumber_InPlaceRshift(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the result of right shiftingo1 byo2 on success, orNULL onfailure. The operation is donein-place wheno1 supports it. This is theequivalent of the Python statemento1>>=o2.

PyObject*PyNumber_InPlaceAnd(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the “bitwise and” ofo1 ando2 on success andNULL on failure. Theoperation is donein-place wheno1 supports it. This is the equivalent ofthe Python statemento1&=o2.

PyObject*PyNumber_InPlaceXor(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the “bitwise exclusive or” ofo1 byo2 on success, orNULL onfailure. The operation is donein-place wheno1 supports it. This is theequivalent of the Python statemento1^=o2.

PyObject*PyNumber_InPlaceOr(PyObject*o1,PyObject*o2)¶

Return value: New reference. Part of theStable ABI.

Returns the “bitwise or” ofo1 ando2 on success, orNULL on failure. Theoperation is donein-place wheno1 supports it. This is the equivalent ofthe Python statemento1|=o2.

PyObject*PyNumber_Long(PyObject*o)¶

Return value: New reference. Part of theStable ABI.

Returns theo converted to an integer object on success, orNULL onfailure. This is the equivalent of the Python expressionint(o).

PyObject*PyNumber_Float(PyObject*o)¶

Return value: New reference. Part of theStable ABI.

Returns theo converted to a float object on success, orNULL on failure.This is the equivalent of the Python expressionfloat(o).

PyObject*PyNumber_Index(PyObject*o)¶

Return value: New reference. Part of theStable ABI.

Returns theo converted to a Python int on success orNULL with aTypeError exception raised on failure.

Changed in version 3.10:The result always has exact typeint. Previously, the resultcould have been an instance of a subclass ofint.

PyObject*PyNumber_ToBase(PyObject*n,intbase)¶

Return value: New reference. Part of theStable ABI.

Returns the integern converted to basebase as a string. Thebaseargument must be one of 2, 8, 10, or 16. For base 2, 8, or 16, thereturned string is prefixed with a base marker of'0b','0o', or'0x', respectively. Ifn is not a Python int, it is converted withPyNumber_Index() first.

Py_ssize_tPyNumber_AsSsize_t(PyObject*o,PyObject*exc)¶

Part of theStable ABI.

Returnso converted to aPy_ssize_t value ifo can be interpreted as aninteger. If the call fails, an exception is raised and-1 is returned.

Ifo can be converted to a Python int but the attempt toconvert to aPy_ssize_t value would raise anOverflowError, then theexc argument is the type of exception that will be raised (usuallyIndexError orOverflowError). Ifexc isNULL, then theexception is cleared and the value is clipped toPY_SSIZE_T_MIN for a negativeinteger orPY_SSIZE_T_MAX for a positive integer.

intPyIndex_Check(PyObject*o)¶

Part of theStable ABI since version 3.8.

Returns1 ifo is an index integer (has thenb_index slot of thetp_as_number structure filled in), and0 otherwise.This function always succeeds.