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