2 :mod:`fractions` --- Rational numbers
3 =====================================
6 :synopsis: Rational numbers.
7 .. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
8 .. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
12 The :mod:`fractions` module provides support for rational number arithmetic.
15 A Fraction instance can be constructed from a pair of integers, from
16 another rational number, or from a string.
18 .. class:: Fraction(numerator=0, denominator=1)
19 Fraction(other_fraction)
22 The first version requires that *numerator* and *denominator* are
23 instances of :class:`numbers.Integral` and returns a new
24 :class:`Fraction` instance with value ``numerator/denominator``. If
25 *denominator* is :const:`0`, it raises a
26 :exc:`ZeroDivisionError`. The second version requires that
27 *other_fraction* is an instance of :class:`numbers.Rational` and
28 returns an :class:`Fraction` instance with the same value. The
29 last version of the constructor expects a string or unicode
30 instance in one of two possible forms. The first form is::
32 [sign] numerator ['/' denominator]
34 where the optional ``sign`` may be either '+' or '-' and
35 ``numerator`` and ``denominator`` (if present) are strings of
36 decimal digits. The second permitted form is that of a number
37 containing a decimal point::
39 [sign] integer '.' [fraction] | [sign] '.' fraction
41 where ``integer`` and ``fraction`` are strings of digits. In
42 either form the input string may also have leading and/or trailing
43 whitespace. Here are some examples::
45 >>> from fractions import Fraction
55 >>> Fraction(' -3/7 ')
57 >>> Fraction('1.414213 \t\n')
58 Fraction(1414213, 1000000)
63 The :class:`Fraction` class inherits from the abstract base class
64 :class:`numbers.Rational`, and implements all of the methods and
65 operations from that class. :class:`Fraction` instances are hashable,
66 and should be treated as immutable. In addition,
67 :class:`Fraction` has the following methods:
70 .. method:: from_float(flt)
72 This class method constructs a :class:`Fraction` representing the exact
73 value of *flt*, which must be a :class:`float`. Beware that
74 ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``
77 .. method:: from_decimal(dec)
79 This class method constructs a :class:`Fraction` representing the exact
80 value of *dec*, which must be a :class:`decimal.Decimal`.
83 .. method:: limit_denominator(max_denominator=1000000)
85 Finds and returns the closest :class:`Fraction` to ``self`` that has
86 denominator at most max_denominator. This method is useful for finding
87 rational approximations to a given floating-point number:
89 >>> from fractions import Fraction
90 >>> Fraction('3.1415926535897932').limit_denominator(1000)
93 or for recovering a rational number that's represented as a float:
95 >>> from math import pi, cos
96 >>> Fraction.from_float(cos(pi/3))
97 Fraction(4503599627370497, 9007199254740992)
98 >>> Fraction.from_float(cos(pi/3)).limit_denominator()
102 .. function:: gcd(a, b)
104 Return the greatest common divisor of the integers *a* and *b*. If either
105 *a* or *b* is nonzero, then the absolute value of ``gcd(a, b)`` is the
106 largest integer that divides both *a* and *b*. ``gcd(a,b)`` has the same
107 sign as *b* if *b* is nonzero; otherwise it takes the sign of *a*. ``gcd(0,
113 Module :mod:`numbers`
114 The abstract base classes making up the numeric tower.