• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1:mod:`fractions` --- Rational numbers
2=====================================
3
4.. module:: fractions
5   :synopsis: Rational numbers.
6.. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
7.. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
8.. versionadded:: 2.6
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.  In addition, any string that represents a finite
46   value and is accepted by the :class:`float` constructor is also
47   accepted by the :class:`Fraction` constructor.  In either form the
48   input string may also have leading and/or trailing whitespace.
49   Here are some examples::
50
51      >>> from fractions import Fraction
52      >>> Fraction(16, -10)
53      Fraction(-8, 5)
54      >>> Fraction(123)
55      Fraction(123, 1)
56      >>> Fraction()
57      Fraction(0, 1)
58      >>> Fraction('3/7')
59      Fraction(3, 7)
60      >>> Fraction(' -3/7 ')
61      Fraction(-3, 7)
62      >>> Fraction('1.414213 \t\n')
63      Fraction(1414213, 1000000)
64      >>> Fraction('-.125')
65      Fraction(-1, 8)
66      >>> Fraction('7e-6')
67      Fraction(7, 1000000)
68      >>> Fraction(2.25)
69      Fraction(9, 4)
70      >>> Fraction(1.1)
71      Fraction(2476979795053773, 2251799813685248)
72      >>> from decimal import Decimal
73      >>> Fraction(Decimal('1.1'))
74      Fraction(11, 10)
75
76
77   The :class:`Fraction` class inherits from the abstract base class
78   :class:`numbers.Rational`, and implements all of the methods and
79   operations from that class.  :class:`Fraction` instances are hashable,
80   and should be treated as immutable.  In addition,
81   :class:`Fraction` has the following methods:
82
83   .. versionchanged:: 2.7
84      The :class:`Fraction` constructor now accepts :class:`float` and
85      :class:`decimal.Decimal` instances.
86
87
88   .. method:: from_float(flt)
89
90      This class method constructs a :class:`Fraction` representing the exact
91      value of *flt*, which must be a :class:`float`. Beware that
92      ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``.
93
94      .. note:: From Python 2.7 onwards, you can also construct a
95         :class:`Fraction` instance directly from a :class:`float`.
96
97
98   .. method:: from_decimal(dec)
99
100      This class method constructs a :class:`Fraction` representing the exact
101      value of *dec*, which must be a :class:`decimal.Decimal`.
102
103      .. note:: From Python 2.7 onwards, you can also construct a
104         :class:`Fraction` instance directly from a :class:`decimal.Decimal`
105         instance.
106
107
108   .. method:: limit_denominator(max_denominator=1000000)
109
110      Finds and returns the closest :class:`Fraction` to ``self`` that has
111      denominator at most max_denominator.  This method is useful for finding
112      rational approximations to a given floating-point number:
113
114         >>> from fractions import Fraction
115         >>> Fraction('3.1415926535897932').limit_denominator(1000)
116         Fraction(355, 113)
117
118      or for recovering a rational number that's represented as a float:
119
120         >>> from math import pi, cos
121         >>> Fraction(cos(pi/3))
122         Fraction(4503599627370497, 9007199254740992)
123         >>> Fraction(cos(pi/3)).limit_denominator()
124         Fraction(1, 2)
125         >>> Fraction(1.1).limit_denominator()
126         Fraction(11, 10)
127
128
129.. function:: gcd(a, b)
130
131   Return the greatest common divisor of the integers *a* and *b*.  If either
132   *a* or *b* is nonzero, then the absolute value of ``gcd(a, b)`` is the
133   largest integer that divides both *a* and *b*.  ``gcd(a,b)`` has the same
134   sign as *b* if *b* is nonzero; otherwise it takes the sign of *a*.  ``gcd(0,
135   0)`` returns ``0``.
136
137
138.. seealso::
139
140   Module :mod:`numbers`
141      The abstract base classes making up the numeric tower.
142