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