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 11The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric 12:term:`abstract base classes <abstract base class>` which progressively define 13more operations. None of the types defined in this module are intended to 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 22The 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 31 ``!=``. All 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 :func:`pow` with 80 modulus and bit-string operations: ``<<``, ``>>``, ``&``, ``^``, ``|``, 81 ``~``. 82 83 84Notes for type implementors 85--------------------------- 86 87Implementors should be careful to make equal numbers equal and hash 88them to the same values. This may be subtle if there are two different 89extensions of the real numbers. For example, :class:`fractions.Fraction` 90implements :func:`hash` as follows:: 91 92 def __hash__(self): 93 if self.denominator == 1: 94 # Get integers right. 95 return hash(self.numerator) 96 # Expensive check, but definitely correct. 97 if self == float(self): 98 return hash(float(self)) 99 else: 100 # Use tuple's hash to avoid a high collision rate on 101 # simple fractions. 102 return hash((self.numerator, self.denominator)) 103 104 105Adding More Numeric ABCs 106~~~~~~~~~~~~~~~~~~~~~~~~ 107 108There are, of course, more possible ABCs for numbers, and this would 109be a poor hierarchy if it precluded the possibility of adding 110those. You can add ``MyFoo`` between :class:`Complex` and 111:class:`Real` with:: 112 113 class MyFoo(Complex): ... 114 MyFoo.register(Real) 115 116 117.. _implementing-the-arithmetic-operations: 118 119Implementing the arithmetic operations 120~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 121 122We want to implement the arithmetic operations so that mixed-mode 123operations either call an implementation whose author knew about the 124types of both arguments, or convert both to the nearest built in type 125and do the operation there. For subtypes of :class:`Integral`, this 126means that :meth:`__add__` and :meth:`__radd__` should be defined as:: 127 128 class MyIntegral(Integral): 129 130 def __add__(self, other): 131 if isinstance(other, MyIntegral): 132 return do_my_adding_stuff(self, other) 133 elif isinstance(other, OtherTypeIKnowAbout): 134 return do_my_other_adding_stuff(self, other) 135 else: 136 return NotImplemented 137 138 def __radd__(self, other): 139 if isinstance(other, MyIntegral): 140 return do_my_adding_stuff(other, self) 141 elif isinstance(other, OtherTypeIKnowAbout): 142 return do_my_other_adding_stuff(other, self) 143 elif isinstance(other, Integral): 144 return int(other) + int(self) 145 elif isinstance(other, Real): 146 return float(other) + float(self) 147 elif isinstance(other, Complex): 148 return complex(other) + complex(self) 149 else: 150 return NotImplemented 151 152 153There are 5 different cases for a mixed-type operation on subclasses 154of :class:`Complex`. I'll refer to all of the above code that doesn't 155refer to ``MyIntegral`` and ``OtherTypeIKnowAbout`` as 156"boilerplate". ``a`` will be an instance of ``A``, which is a subtype 157of :class:`Complex` (``a : A <: Complex``), and ``b : B <: 158Complex``. I'll consider ``a + b``: 159 160 1. If ``A`` defines an :meth:`__add__` which accepts ``b``, all is 161 well. 162 2. If ``A`` falls back to the boilerplate code, and it were to 163 return a value from :meth:`__add__`, we'd miss the possibility 164 that ``B`` defines a more intelligent :meth:`__radd__`, so the 165 boilerplate should return :const:`NotImplemented` from 166 :meth:`__add__`. (Or ``A`` may not implement :meth:`__add__` at 167 all.) 168 3. Then ``B``'s :meth:`__radd__` gets a chance. If it accepts 169 ``a``, all is well. 170 4. If it falls back to the boilerplate, there are no more possible 171 methods to try, so this is where the default implementation 172 should live. 173 5. If ``B <: A``, Python tries ``B.__radd__`` before 174 ``A.__add__``. This is ok, because it was implemented with 175 knowledge of ``A``, so it can handle those instances before 176 delegating to :class:`Complex`. 177 178If ``A <: Complex`` and ``B <: Real`` without sharing any other knowledge, 179then the appropriate shared operation is the one involving the built 180in :class:`complex`, and both :meth:`__radd__` s land there, so ``a+b 181== b+a``. 182 183Because most of the operations on any given type will be very similar, 184it can be useful to define a helper function which generates the 185forward and reverse instances of any given operator. For example, 186:class:`fractions.Fraction` uses:: 187 188 def _operator_fallbacks(monomorphic_operator, fallback_operator): 189 def forward(a, b): 190 if isinstance(b, (int, Fraction)): 191 return monomorphic_operator(a, b) 192 elif isinstance(b, float): 193 return fallback_operator(float(a), b) 194 elif isinstance(b, complex): 195 return fallback_operator(complex(a), b) 196 else: 197 return NotImplemented 198 forward.__name__ = '__' + fallback_operator.__name__ + '__' 199 forward.__doc__ = monomorphic_operator.__doc__ 200 201 def reverse(b, a): 202 if isinstance(a, Rational): 203 # Includes ints. 204 return monomorphic_operator(a, b) 205 elif isinstance(a, numbers.Real): 206 return fallback_operator(float(a), float(b)) 207 elif isinstance(a, numbers.Complex): 208 return fallback_operator(complex(a), complex(b)) 209 else: 210 return NotImplemented 211 reverse.__name__ = '__r' + fallback_operator.__name__ + '__' 212 reverse.__doc__ = monomorphic_operator.__doc__ 213 214 return forward, reverse 215 216 def _add(a, b): 217 """a + b""" 218 return Fraction(a.numerator * b.denominator + 219 b.numerator * a.denominator, 220 a.denominator * b.denominator) 221 222 __add__, __radd__ = _operator_fallbacks(_add, operator.add) 223 224 # ... 225