Number Protocol

intPyNumber_Check(PyObject*o)

Part of theStable ABI.

Returns1if the objectoprovides numeric protocols, and false otherwise. This function always succeeds.

Changed in version 3.8:Returns1ifois an index integer.

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

Return value: New reference.Part of theStable ABI.

Returns the result of addingo1ando2,orNULLon failure. This is the equivalent of the Python expressiono1+o2.

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

Return value: New reference.Part of theStable ABI.

Returns the result of subtractingo2fromo1,orNULLon failure. This is the 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 multiplyingo1ando2,orNULLon failure. This is the equivalent of the Python expressiono1*o2.

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

Return value: New reference.Part of theStable ABIsince version 3.7.

Returns the result of matrix multiplication ono1ando2,orNULLon failure. 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 ofo1divided byo2,orNULLon failure. This is the 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 ofo1divided by o2,orNULLon failure. The return value is “approximate” because binary floating-point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating-point value when passed 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 dividingo1byo2,orNULLon failure. This is the 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().ReturnsNULLon failure. This is the 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().ReturnsNULLon failure. This is the equivalent of the Python expressionpow(o1,o2,o3),whereo3is optional. Ifo3is to be ignored, passPy_Nonein its place (passingNULLfor o3would cause an illegal memory access).

PyObject*PyNumber_Negative(PyObject*o)

Return value: New reference.Part of theStable ABI.

Returns the negation ofoon success, orNULLon failure. This is the equivalent of the Python expression-o.

PyObject*PyNumber_Positive(PyObject*o)

Return value: New reference.Part of theStable ABI.

Returnsoon success, orNULLon failure. This is the equivalent of the Python expression+o.

PyObject*PyNumber_Absolute(PyObject*o)

Return value: New reference.Part of theStable ABI.

Returns the absolute value ofo,orNULLon failure. This is the equivalent of the Python expressionabs(o).

PyObject*PyNumber_Invert(PyObject*o)

Return value: New reference.Part of theStable ABI.

Returns the bitwise negation ofoon success, orNULLon failure. This is the 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 shiftingo1byo2on success, orNULLon failure. 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 shiftingo1byo2on success, orNULLon failure. 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” ofo1ando2on success andNULLon 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” ofo1byo2on success, orNULLon failure. 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” ofo1ando2on success, orNULLon 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 addingo1ando2,orNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent of the Python statemento1+=o2.

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

Return value: New reference.Part of theStable ABI.

Returns the result of subtractingo2fromo1,orNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent of the Python statemento1-=o2.

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

Return value: New reference.Part of theStable ABI.

Returns the result of multiplyingo1ando2,orNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent of the Python statemento1*=o2.

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

Return value: New reference.Part of theStable ABIsince version 3.7.

Returns the result of matrix multiplication ono1ando2,orNULLon failure. The operation is donein-placewheno1supports it. This is the 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 dividingo1byo2,orNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent of 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 ofo1divided by o2,orNULLon failure. The return value is “approximate” because binary floating-point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating-point value when passed two integers. The operation is donein-placewheno1supports 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 dividingo1byo2,orNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent of the 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().ReturnsNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent of the Python statemento1**=o2when o3 isPy_None,or an in-place variant of pow(o1,o2,o3)otherwise. Ifo3is to be ignored, passPy_None in its place (passingNULLforo3would 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 shiftingo1byo2on success, orNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent 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 shiftingo1byo2on success, orNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent of the Python statemento1>>=o2.

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

Return value: New reference.Part of theStable ABI.

Returns the “bitwise and” ofo1ando2on success andNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent of the Python statemento1&=o2.

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

Return value: New reference.Part of theStable ABI.

Returns the “bitwise exclusive or” ofo1byo2on success, orNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent of the Python statemento1^=o2.

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

Return value: New reference.Part of theStable ABI.

Returns the “bitwise or” ofo1ando2on success, orNULLon failure. The operation is donein-placewheno1supports it. This is the equivalent of the Python statemento1|=o2.

PyObject*PyNumber_Long(PyObject*o)

Return value: New reference.Part of theStable ABI.

Returns theoconverted to an integer object on success, orNULLon failure. This is the equivalent of the Python expressionint(o).

PyObject*PyNumber_Float(PyObject*o)

Return value: New reference.Part of theStable ABI.

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

PyObject*PyNumber_Index(PyObject*o)

Return value: New reference.Part of theStable ABI.

Returns theoconverted to a Python int on success orNULLwith a TypeErrorexception raised on failure.

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

PyObject*PyNumber_ToBase(PyObject*n,intbase)

Return value: New reference.Part of theStable ABI.

Returns the integernconverted to basebaseas a string. Thebase argument must be one of 2, 8, 10, or 16. For base 2, 8, or 16, the returned string is prefixed with a base marker of'0b','0o',or '0x',respectively. Ifnis not a Python int, it is converted with PyNumber_Index()first.

Py_ssize_tPyNumber_AsSsize_t(PyObject*o,PyObject*exc)

Part of theStable ABI.

Returnsoconverted to aPy_ssize_tvalue ifocan be interpreted as an integer. If the call fails, an exception is raised and-1is returned.

Ifocan be converted to a Python int but the attempt to convert to aPy_ssize_tvalue would raise anOverflowError,then the excargument is the type of exception that will be raised (usually IndexErrororOverflowError). IfexcisNULL,then the exception is cleared and the value is clipped toPY_SSIZE_T_MINfor a negative integer orPY_SSIZE_T_MAXfor a positive integer.

intPyIndex_Check(PyObject*o)

Part of theStable ABIsince version 3.8.

Returns1ifois an index integer (has thenb_indexslot of the tp_as_numberstructure filled in), and0otherwise. This function always succeeds.