/Doc/library/fractions.rst

  1
  2:mod:`fractions` --- Rational numbers
  3=====================================
  4
  5.. module:: fractions
  6   :synopsis: Rational numbers.
  7.. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
  8.. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
  9.. versionadded:: 2.6
 10
 11
 12The :mod:`fractions` module provides support for rational number arithmetic.
 13
 14
 15A Fraction instance can be constructed from a pair of integers, from
 16another rational number, or from a string.
 17
 18.. class:: Fraction(numerator=0, denominator=1)
 19           Fraction(other_fraction)
 20           Fraction(string)
 21
 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::
 31
 32      [sign] numerator ['/' denominator]
 33
 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::
 38
 39      [sign] integer '.' [fraction] | [sign] '.' fraction
 40
 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::
 44
 45      >>> from fractions import Fraction
 46      >>> Fraction(16, -10)
 47      Fraction(-8, 5)
 48      >>> Fraction(123)
 49      Fraction(123, 1)
 50      >>> Fraction()
 51      Fraction(0, 1)
 52      >>> Fraction('3/7')
 53      Fraction(3, 7)
 54      [40794 refs]
 55      >>> Fraction(' -3/7 ')
 56      Fraction(-3, 7)
 57      >>> Fraction('1.414213 \t\n')
 58      Fraction(1414213, 1000000)
 59      >>> Fraction('-.125')
 60      Fraction(-1, 8)
 61
 62
 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:
 68
 69
 70   .. method:: from_float(flt)
 71
 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)``
 75
 76
 77   .. method:: from_decimal(dec)
 78
 79      This class method constructs a :class:`Fraction` representing the exact
 80      value of *dec*, which must be a :class:`decimal.Decimal`.
 81
 82
 83   .. method:: limit_denominator(max_denominator=1000000)
 84
 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:
 88
 89         >>> from fractions import Fraction
 90         >>> Fraction('3.1415926535897932').limit_denominator(1000)
 91         Fraction(355, 113)
 92
 93      or for recovering a rational number that's represented as a float:
 94
 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()
 99         Fraction(1, 2)
100
101
102.. function:: gcd(a, b)
103
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,
108   0)`` returns ``0``.
109
110
111.. seealso::
112
113   Module :mod:`numbers`
114      The abstract base classes making up the numeric tower.