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.
See About this document... for information on suggesting changes.
