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
  12 The :mod:`fractions` module provides support for rational number arithmetic.
  13
  14
  15 A Fraction instance can be constructed from a pair of integers, from
  16 another 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.