1 :mod:`numbers` --- Numeric abstract base classes 2 ================================================ 3 4 .. module:: numbers 5 :synopsis: Numeric abstract base classes (Complex, Real, Integral, etc.). 6 7 **Source code:** :source:`Lib/numbers.py` 8 9 -------------- 10 11 The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric 12 :term:`abstract base classes <abstract base class>` which progressively define 13 more operations. None of the types defined in this module can be instantiated. 14 15 16 .. class:: Number 17 18 The root of the numeric hierarchy. If you just want to check if an argument 19 *x* is a number, without caring what kind, use ``isinstance(x, Number)``. 20 21 22 The numeric tower 23 ----------------- 24 25 .. class:: Complex 26 27 Subclasses of this type describe complex numbers and include the operations 28 that work on the built-in :class:`complex` type. These are: conversions to 29 :class:`complex` and :class:`bool`, :attr:`.real`, :attr:`.imag`, ``+``, 30 ``-``, ``*``, ``/``, :func:`abs`, :meth:`conjugate`, ``==``, and ``!=``. All 31 except ``-`` and ``!=`` are abstract. 32 33 .. attribute:: real 34 35 Abstract. Retrieves the real component of this number. 36 37 .. attribute:: imag 38 39 Abstract. Retrieves the imaginary component of this number. 40 41 .. abstractmethod:: conjugate() 42 43 Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate() 44 == (1-3j)``. 45 46 .. class:: Real 47 48 To :class:`Complex`, :class:`Real` adds the operations that work on real 49 numbers. 50 51 In short, those are: a conversion to :class:`float`, :func:`math.trunc`, 52 :func:`round`, :func:`math.floor`, :func:`math.ceil`, :func:`divmod`, ``//``, 53 ``%``, ``<``, ``<=``, ``>``, and ``>=``. 54 55 Real also provides defaults for :func:`complex`, :attr:`~Complex.real`, 56 :attr:`~Complex.imag`, and :meth:`~Complex.conjugate`. 57 58 59 .. class:: Rational 60 61 Subtypes :class:`Real` and adds 62 :attr:`~Rational.numerator` and :attr:`~Rational.denominator` properties, which 63 should be in lowest terms. With these, it provides a default for 64 :func:`float`. 65 66 .. attribute:: numerator 67 68 Abstract. 69 70 .. attribute:: denominator 71 72 Abstract. 73 74 75 .. class:: Integral 76 77 Subtypes :class:`Rational` and adds a conversion to :class:`int`. Provides 78 defaults for :func:`float`, :attr:`~Rational.numerator`, and 79 :attr:`~Rational.denominator`. Adds abstract methods for ``**`` and 80 bit-string operations: ``<<``, ``>>``, ``&``, ``^``, ``|``, ``~``. 81 82 83 Notes for type implementors 84 --------------------------- 85 86 Implementors should be careful to make equal numbers equal and hash 87 them to the same values. This may be subtle if there are two different 88 extensions of the real numbers. For example, :class:`fractions.Fraction` 89 implements :func:`hash` as follows:: 90 91 def __hash__(self): 92 if self.denominator == 1: 93 # Get integers right. 94 return hash(self.numerator) 95 # Expensive check, but definitely correct. 96 if self == float(self): 97 return hash(float(self)) 98 else: 99 # Use tuple's hash to avoid a high collision rate on 100 # simple fractions. 101 return hash((self.numerator, self.denominator)) 102 103 104 Adding More Numeric ABCs 105 ~~~~~~~~~~~~~~~~~~~~~~~~ 106 107 There are, of course, more possible ABCs for numbers, and this would 108 be a poor hierarchy if it precluded the possibility of adding 109 those. You can add ``MyFoo`` between :class:`Complex` and 110 :class:`Real` with:: 111 112 class MyFoo(Complex): ... 113 MyFoo.register(Real) 114 115 116 .. _implementing-the-arithmetic-operations: 117 118 Implementing the arithmetic operations 119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 120 121 We want to implement the arithmetic operations so that mixed-mode 122 operations either call an implementation whose author knew about the 123 types of both arguments, or convert both to the nearest built in type 124 and do the operation there. For subtypes of :class:`Integral`, this 125 means that :meth:`__add__` and :meth:`__radd__` should be defined as:: 126 127 class MyIntegral(Integral): 128 129 def __add__(self, other): 130 if isinstance(other, MyIntegral): 131 return do_my_adding_stuff(self, other) 132 elif isinstance(other, OtherTypeIKnowAbout): 133 return do_my_other_adding_stuff(self, other) 134 else: 135 return NotImplemented 136 137 def __radd__(self, other): 138 if isinstance(other, MyIntegral): 139 return do_my_adding_stuff(other, self) 140 elif isinstance(other, OtherTypeIKnowAbout): 141 return do_my_other_adding_stuff(other, self) 142 elif isinstance(other, Integral): 143 return int(other) + int(self) 144 elif isinstance(other, Real): 145 return float(other) + float(self) 146 elif isinstance(other, Complex): 147 return complex(other) + complex(self) 148 else: 149 return NotImplemented 150 151 152 There are 5 different cases for a mixed-type operation on subclasses 153 of :class:`Complex`. I'll refer to all of the above code that doesn't 154 refer to ``MyIntegral`` and ``OtherTypeIKnowAbout`` as 155 "boilerplate". ``a`` will be an instance of ``A``, which is a subtype 156 of :class:`Complex` (``a : A <: Complex``), and ``b : B <: 157 Complex``. I'll consider ``a + b``: 158 159 1. If ``A`` defines an :meth:`__add__` which accepts ``b``, all is 160 well. 161 2. If ``A`` falls back to the boilerplate code, and it were to 162 return a value from :meth:`__add__`, we'd miss the possibility 163 that ``B`` defines a more intelligent :meth:`__radd__`, so the 164 boilerplate should return :const:`NotImplemented` from 165 :meth:`__add__`. (Or ``A`` may not implement :meth:`__add__` at 166 all.) 167 3. Then ``B``'s :meth:`__radd__` gets a chance. If it accepts 168 ``a``, all is well. 169 4. If it falls back to the boilerplate, there are no more possible 170 methods to try, so this is where the default implementation 171 should live. 172 5. If ``B <: A``, Python tries ``B.__radd__`` before 173 ``A.__add__``. This is ok, because it was implemented with 174 knowledge of ``A``, so it can handle those instances before 175 delegating to :class:`Complex`. 176 177 If ``A <: Complex`` and ``B <: Real`` without sharing any other knowledge, 178 then the appropriate shared operation is the one involving the built 179 in :class:`complex`, and both :meth:`__radd__` s land there, so ``a+b 180 == b+a``. 181 182 Because most of the operations on any given type will be very similar, 183 it can be useful to define a helper function which generates the 184 forward and reverse instances of any given operator. For example, 185 :class:`fractions.Fraction` uses:: 186 187 def _operator_fallbacks(monomorphic_operator, fallback_operator): 188 def forward(a, b): 189 if isinstance(b, (int, Fraction)): 190 return monomorphic_operator(a, b) 191 elif isinstance(b, float): 192 return fallback_operator(float(a), b) 193 elif isinstance(b, complex): 194 return fallback_operator(complex(a), b) 195 else: 196 return NotImplemented 197 forward.__name__ = '__' + fallback_operator.__name__ + '__' 198 forward.__doc__ = monomorphic_operator.__doc__ 199 200 def reverse(b, a): 201 if isinstance(a, Rational): 202 # Includes ints. 203 return monomorphic_operator(a, b) 204 elif isinstance(a, numbers.Real): 205 return fallback_operator(float(a), float(b)) 206 elif isinstance(a, numbers.Complex): 207 return fallback_operator(complex(a), complex(b)) 208 else: 209 return NotImplemented 210 reverse.__name__ = '__r' + fallback_operator.__name__ + '__' 211 reverse.__doc__ = monomorphic_operator.__doc__ 212 213 return forward, reverse 214 215 def _add(a, b): 216 """a + b""" 217 return Fraction(a.numerator * b.denominator + 218 b.numerator * a.denominator, 219 a.denominator * b.denominator) 220 221 __add__, __radd__ = _operator_fallbacks(_add, operator.add) 222 223 # ... 224
