Number Protocol¶

intPyNumber_Check(PyObject *o)¶

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.

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.

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.

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.

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

New in version 3.5.

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

Return value: New reference.

Return the floor ofo1 divided byo2, orNULL on failure. This isequivalent to the “classic” division of integers.

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

Return value: New reference.

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.

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

Return value: New reference.

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.

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.

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.

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.

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

PyObject*PyNumber_Absolute(PyObject *o)¶

Return value: New reference.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

New in version 3.5.

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

Return value: New reference.

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.

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.

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

Return value: New reference.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

PyObject*PyNumber_ToBase(PyObject *n, int base)¶

Return value: New reference.

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

Returnso converted to a Py_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 a Py_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)¶

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