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