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.Rational` 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.  The usual form for this instance 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.  In addition, any string that represents a finite
  37    value and is accepted by the :class:`float` constructor is also
  38    accepted by the :class:`Fraction` constructor.  In either form the
  39    input string may also have leading and/or trailing whitespace.
  40    Here are some examples::
  41
  42       >>> from fractions import Fraction
  43       >>> Fraction(16, -10)
  44       Fraction(-8, 5)
  45       >>> Fraction(123)
  46       Fraction(123, 1)
  47       >>> Fraction()
  48       Fraction(0, 1)
  49       >>> Fraction('3/7')
  50       Fraction(3, 7)
  51       [40794 refs]
  52       >>> Fraction(' -3/7 ')
  53       Fraction(-3, 7)
  54       >>> Fraction('1.414213 \t\n')
  55       Fraction(1414213, 1000000)
  56       >>> Fraction('-.125')
  57       Fraction(-1, 8)
  58       >>> Fraction('7e-6')
  59       Fraction(7, 1000000)
  60
  61
  62    The :class:`Fraction` class inherits from the abstract base class
  63    :class:`numbers.Rational`, and implements all of the methods and
  64    operations from that class.  :class:`Fraction` instances are hashable,
  65    and should be treated as immutable.  In addition,
  66    :class:`Fraction` has the following methods:
  67
  68
  69    .. method:: from_float(flt)
  70
  71       This class method constructs a :class:`Fraction` representing the exact
  72       value of *flt*, which must be a :class:`float`. Beware that
  73       ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``
  74
  75
  76    .. method:: from_decimal(dec)
  77
  78       This class method constructs a :class:`Fraction` representing the exact
  79       value of *dec*, which must be a :class:`decimal.Decimal`.
  80
  81
  82    .. method:: limit_denominator(max_denominator=1000000)
  83
  84       Finds and returns the closest :class:`Fraction` to ``self`` that has
  85       denominator at most max_denominator.  This method is useful for finding
  86       rational approximations to a given floating-point number:
  87
  88          >>> from fractions import Fraction
  89          >>> Fraction('3.1415926535897932').limit_denominator(1000)
  90          Fraction(355, 113)
  91
  92       or for recovering a rational number that's represented as a float:
  93
  94          >>> from math import pi, cos
  95          >>> Fraction.from_float(cos(pi/3))
  96          Fraction(4503599627370497, 9007199254740992)
  97          >>> Fraction.from_float(cos(pi/3)).limit_denominator()
  98          Fraction(1, 2)
  99
 100
 101 .. function:: gcd(a, b)
 102
 103    Return the greatest common divisor of the integers *a* and *b*.  If either
 104    *a* or *b* is nonzero, then the absolute value of ``gcd(a, b)`` is the
 105    largest integer that divides both *a* and *b*.  ``gcd(a,b)`` has the same
 106    sign as *b* if *b* is nonzero; otherwise it takes the sign of *a*.  ``gcd(0,
 107    0)`` returns ``0``.
 108
 109
 110 .. seealso::
 111
 112    Module :mod:`numbers`
 113       The abstract base classes making up the numeric tower.