1:mod:`fractions` --- Rational numbers
2=====================================
3
4.. module:: fractions
5   :synopsis: Rational numbers.
6
7.. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
8.. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
9
10**Source code:** :source:`Lib/fractions.py`
11
12--------------
13
14The :mod:`fractions` module provides support for rational number arithmetic.
15
16
17A Fraction instance can be constructed from a pair of integers, from
18another rational number, or from a string.
19
20.. class:: Fraction(numerator=0, denominator=1)
21           Fraction(other_fraction)
22           Fraction(float)
23           Fraction(decimal)
24           Fraction(string)
25
26   The first version requires that *numerator* and *denominator* are instances
27   of :class:`numbers.Rational` and returns a new :class:`Fraction` instance
28   with value ``numerator/denominator``. If *denominator* is :const:`0`, it
29   raises a :exc:`ZeroDivisionError`. The second version requires that
30   *other_fraction* is an instance of :class:`numbers.Rational` and returns a
31   :class:`Fraction` instance with the same value.  The next two versions accept
32   either a :class:`float` or a :class:`decimal.Decimal` instance, and return a
33   :class:`Fraction` instance with exactly the same value.  Note that due to the
34   usual issues with binary floating-point (see :ref:`tut-fp-issues`), the
35   argument to ``Fraction(1.1)`` is not exactly equal to 11/10, and so
36   ``Fraction(1.1)`` does *not* return ``Fraction(11, 10)`` as one might expect.
37   (But see the documentation for the :meth:`limit_denominator` method below.)
38   The last version of the constructor expects a string or unicode instance.
39   The usual form for this instance is::
40
41      [sign] numerator ['/' denominator]
42
43   where the optional ``sign`` may be either '+' or '-' and
44   ``numerator`` and ``denominator`` (if present) are strings of
45   decimal digits (underscores may be used to delimit digits as with
46   integral literals in code).  In addition, any string that represents a finite
47   value and is accepted by the :class:`float` constructor is also
48   accepted by the :class:`Fraction` constructor.  In either form the
49   input string may also have leading and/or trailing whitespace.
50   Here are some examples::
51
52      >>> from fractions import Fraction
53      >>> Fraction(16, -10)
54      Fraction(-8, 5)
55      >>> Fraction(123)
56      Fraction(123, 1)
57      >>> Fraction()
58      Fraction(0, 1)
59      >>> Fraction('3/7')
60      Fraction(3, 7)
61      >>> Fraction(' -3/7 ')
62      Fraction(-3, 7)
63      >>> Fraction('1.414213 \t\n')
64      Fraction(1414213, 1000000)
65      >>> Fraction('-.125')
66      Fraction(-1, 8)
67      >>> Fraction('7e-6')
68      Fraction(7, 1000000)
69      >>> Fraction(2.25)
70      Fraction(9, 4)
71      >>> Fraction(1.1)
72      Fraction(2476979795053773, 2251799813685248)
73      >>> from decimal import Decimal
74      >>> Fraction(Decimal('1.1'))
75      Fraction(11, 10)
76
77
78   The :class:`Fraction` class inherits from the abstract base class
79   :class:`numbers.Rational`, and implements all of the methods and
80   operations from that class.  :class:`Fraction` instances are :term:`hashable`,
81   and should be treated as immutable.  In addition,
82   :class:`Fraction` has the following properties and methods:
83
84   .. versionchanged:: 3.2
85      The :class:`Fraction` constructor now accepts :class:`float` and
86      :class:`decimal.Decimal` instances.
87
88   .. versionchanged:: 3.9
89      The :func:`math.gcd` function is now used to normalize the *numerator*
90      and *denominator*. :func:`math.gcd` always return a :class:`int` type.
91      Previously, the GCD type depended on *numerator* and *denominator*.
92
93   .. versionchanged:: 3.11
94      Underscores are now permitted when creating a :class:`Fraction` instance
95      from a string, following :PEP:`515` rules.
96
97   .. versionchanged:: 3.11
98      :class:`Fraction` implements ``__int__`` now to satisfy
99      ``typing.SupportsInt`` instance checks.
100
101   .. attribute:: numerator
102
103      Numerator of the Fraction in lowest term.
104
105   .. attribute:: denominator
106
107      Denominator of the Fraction in lowest term.
108
109
110   .. method:: as_integer_ratio()
111
112      Return a tuple of two integers, whose ratio is equal
113      to the Fraction and with a positive denominator.
114
115      .. versionadded:: 3.8
116
117   .. classmethod:: from_float(flt)
118
119      Alternative constructor which only accepts instances of
120      :class:`float` or :class:`numbers.Integral`. Beware that
121      ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``.
122
123      .. note::
124
125         From Python 3.2 onwards, you can also construct a
126         :class:`Fraction` instance directly from a :class:`float`.
127
128
129   .. classmethod:: from_decimal(dec)
130
131      Alternative constructor which only accepts instances of
132      :class:`decimal.Decimal` or :class:`numbers.Integral`.
133
134      .. note::
135
136         From Python 3.2 onwards, you can also construct a
137         :class:`Fraction` instance directly from a :class:`decimal.Decimal`
138         instance.
139
140
141   .. method:: limit_denominator(max_denominator=1000000)
142
143      Finds and returns the closest :class:`Fraction` to ``self`` that has
144      denominator at most max_denominator.  This method is useful for finding
145      rational approximations to a given floating-point number:
146
147         >>> from fractions import Fraction
148         >>> Fraction('3.1415926535897932').limit_denominator(1000)
149         Fraction(355, 113)
150
151      or for recovering a rational number that's represented as a float:
152
153         >>> from math import pi, cos
154         >>> Fraction(cos(pi/3))
155         Fraction(4503599627370497, 9007199254740992)
156         >>> Fraction(cos(pi/3)).limit_denominator()
157         Fraction(1, 2)
158         >>> Fraction(1.1).limit_denominator()
159         Fraction(11, 10)
160
161
162   .. method:: __floor__()
163
164      Returns the greatest :class:`int` ``<= self``.  This method can
165      also be accessed through the :func:`math.floor` function:
166
167        >>> from math import floor
168        >>> floor(Fraction(355, 113))
169        3
170
171
172   .. method:: __ceil__()
173
174      Returns the least :class:`int` ``>= self``.  This method can
175      also be accessed through the :func:`math.ceil` function.
176
177
178   .. method:: __round__()
179               __round__(ndigits)
180
181      The first version returns the nearest :class:`int` to ``self``,
182      rounding half to even. The second version rounds ``self`` to the
183      nearest multiple of ``Fraction(1, 10**ndigits)`` (logically, if
184      ``ndigits`` is negative), again rounding half toward even.  This
185      method can also be accessed through the :func:`round` function.
186
187
188.. seealso::
189
190   Module :mod:`numbers`
191      The abstract base classes making up the numeric tower.
192