3.3.6 Emulating numeric types
Keywords: ref

##
3.3.6 Emulating numeric types

The following methods can be defined to emulate numeric objects. Methods corresponding to operations that are not supported by the particular kind of number implemented (e.g., bitwise operations for non-integral numbers) should be left undefined.

`__add__` (self, other)
`__sub__` (self, other)
`__mul__` (self, other)
`__div__` (self, other)
`__mod__` (self, other)
`__divmod__` (self, other)
`__pow__` (self, other[, modulo])
`__lshift__` (self, other)
`__rshift__` (self, other)
`__and__` (self, other)
`__xor__` (self, other)
`__or__` (self, other)
  These functions are called to implement the binary arithmetic operations (`+`, `-`, `*`, `/`, `%`, `divmod()`, `pow()`, `**`, `«`, `»`, `&`, `^`, `|`). For instance, to evaluate the expression x`+`y, where x is an instance of a class that has an `__add__()` method, `x.__add__(y)` is called. Note that `__pow__()` should be defined to accept an optional third argument if the ternary version of the built-in `pow()` function is to be supported.

`__radd__` (self, other)
`__rsub__` (self, other)
`__rmul__` (self, other)
`__rdiv__` (self, other)
`__rmod__` (self, other)
`__rdivmod__` (self, other)
`__rpow__` (self, other)
`__rlshift__` (self, other)
`__rrshift__` (self, other)
`__rand__` (self, other)
`__rxor__` (self, other)
`__ror__` (self, other)
  These functions are called to implement the binary arithmetic operations (`+`, `-`, `*`, `/`, `%`, `divmod()`, `pow()`, `**`, `«`, `»`, `&`, `^`, `|`) with reversed operands. These functions are only called if the left operand does not support the corresponding operation. For instance, to evaluate the expression x`-`y, where y is an instance of a class that has an `__rsub__()` method, `y.__rsub__(x)` is called. Note that ternary `pow()` will not try calling `__rpow__()` (the coercion rules would become too complicated).

`__neg__` (self)
`__pos__` (self)
`__abs__` (self)
`__invert__` (self)
  Called to implement the unary arithmetic operations (`-`, `+`, `abs()` and `~`).

`__complex__` (self)
`__int__` (self)
`__long__` (self)
`__float__` (self)
  Called to implement the built-in functions `complex()`, `int()`, `long()`, and `float()`. Should return a value of the appropriate type.

`__oct__` (self)
`__hex__` (self)
  Called to implement the built-in functions `oct()` and `hex()`. Should return a string value.

`__coerce__` (self, other)
  Called to implement ``mixed-mode'' numeric arithmetic. Should either return a 2-tuple containing self and other converted to a common numeric type, or `None` if conversion is impossible. When the common type would be the type of `other`, it is sufficient to return `None`, since the interpreter will also ask the other object to attempt a coercion (but sometimes, if the implementation of the other type cannot be changed, it is useful to do the conversion to the other type here).

Coercion rules: to evaluate x op y, the following steps are taken (where `__op__()` and `__rop__()` are the method names corresponding to op, e.g., if varop is ``+`', `__add__()` and `__radd__()` are used). If an exception occurs at any point, the evaluation is abandoned and exception handling takes over.

0.
  If x is a string object and op is the modulo operator (%), the string formatting operation is invoked and the remaining steps are skipped.

1.
  If x is a class instance:

  1a.
    If x has a `__coerce__()` method: replace x and y with the 2-tuple returned by `x.__coerce__(y)`; skip to step 2 if the coercion returns `None`.

  1b.
    If neither x nor y is a class instance after coercion, go to step 3.

  1c.
    If x has a method `__op__()`, return `x.__op__(y)`; otherwise, restore x and y to their value before step 1a.

2.
  If y is a class instance:

  2a.
    If y has a `__coerce__()` method: replace y and x with the 2-tuple returned by `y.__coerce__(x)`; skip to step 3 if the coercion returns `None`.

  2b.
    If neither x nor y is a class instance after coercion, go to step 3.

  2b.
    If y has a method `__rop__()`, return `y.__rop__(x)`; otherwise, restore x and y to their value before step 2a.

3.
  We only get here if neither x nor y is a class instance.

  3a.
    If op is ``+`' and x is a sequence, sequence concatenation is invoked.

  3b.
    If op is ``*`' and one operand is a sequence and the other an integer, sequence repetition is invoked.

  3c.
    Otherwise, both operands must be numbers; they are coerced to a common type if possible, and the numeric operation is invoked for that type.