Issue #7117, continued: Change round implementation to use the correctly-rounded
[python.git] / Doc / library / numbers.rst
blob580127c095db421656efc176be33e99c5ab70525
1 :mod:`numbers` --- Numeric abstract base classes
2 ================================================
4 .. module:: numbers
5    :synopsis: Numeric abstract base classes (Complex, Real, Integral, etc.).
7 .. versionadded:: 2.6
10 The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric abstract
11 base classes which progressively define more operations.  None of the types
12 defined in this module can be instantiated.
15 .. class:: Number
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)``.
21 The numeric tower
22 -----------------
24 .. class:: Complex
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.
32    .. attribute:: real
34       Abstract. Retrieves the :class:`Real` component of this number.
36    .. attribute:: imag
38       Abstract. Retrieves the :class:`Real` component of this number.
40    .. method:: conjugate()
42       Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate()
43       == (1-3j)``.
45 .. class:: Real
47    To :class:`Complex`, :class:`Real` adds the operations that work on real
48    numbers.
50    In short, those are: a conversion to :class:`float`, :func:`trunc`,
51    :func:`round`, :func:`math.floor`, :func:`math.ceil`, :func:`divmod`, ``//``,
52    ``%``, ``<``, ``<=``, ``>``, and ``>=``.
54    Real also provides defaults for :func:`complex`, :attr:`~Complex.real`,
55    :attr:`~Complex.imag`, and :meth:`~Complex.conjugate`.
58 .. class:: Rational
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`.
65    .. attribute:: numerator
67       Abstract.
69    .. attribute:: denominator
71       Abstract.
74 .. class:: Integral
76    Subtypes :class:`Rational` and adds a conversion to :class:`int`.
77    Provides defaults for :func:`float`, :attr:`~Rational.numerator`, and
78    :attr:`~Rational.denominator`, and bit-string operations: ``<<``,
79    ``>>``, ``&``, ``^``, ``|``, ``~``.
82 Notes for type implementors
83 ---------------------------
85 Implementors should be careful to make equal numbers equal and hash
86 them to the same values. This may be subtle if there are two different
87 extensions of the real numbers. For example, :class:`fractions.Fraction`
88 implements :func:`hash` as follows::
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))
103 Adding More Numeric ABCs
104 ~~~~~~~~~~~~~~~~~~~~~~~~
106 There are, of course, more possible ABCs for numbers, and this would
107 be a poor hierarchy if it precluded the possibility of adding
108 those. You can add ``MyFoo`` between :class:`Complex` and
109 :class:`Real` with::
111     class MyFoo(Complex): ...
112     MyFoo.register(Real)
115 Implementing the arithmetic operations
116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
118 We want to implement the arithmetic operations so that mixed-mode
119 operations either call an implementation whose author knew about the
120 types of both arguments, or convert both to the nearest built in type
121 and do the operation there. For subtypes of :class:`Integral`, this
122 means that :meth:`__add__` and :meth:`__radd__` should be defined as::
124     class MyIntegral(Integral):
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
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
149 There are 5 different cases for a mixed-type operation on subclasses
150 of :class:`Complex`. I'll refer to all of the above code that doesn't
151 refer to ``MyIntegral`` and ``OtherTypeIKnowAbout`` as
152 "boilerplate". ``a`` will be an instance of ``A``, which is a subtype
153 of :class:`Complex` (``a : A <: Complex``), and ``b : B <:
154 Complex``. I'll consider ``a + b``:
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`.
174 If ``A <: Complex`` and ``B <: Real`` without sharing any other knowledge,
175 then the appropriate shared operation is the one involving the built
176 in :class:`complex`, and both :meth:`__radd__` s land there, so ``a+b
177 == b+a``.
179 Because most of the operations on any given type will be very similar,
180 it can be useful to define a helper function which generates the
181 forward and reverse instances of any given operator. For example,
182 :class:`fractions.Fraction` uses::
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__
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__
210         return forward, reverse
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)
218     __add__, __radd__ = _operator_fallbacks(_add, operator.add)
220     # ...