Home | History | Annotate | Download | only in library 
      1 :mod:`fractions` --- Rational numbers
      2 =====================================
      3 
      4 .. module:: fractions
      5    :synopsis: Rational numbers.
      6 
      7 .. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
      8 .. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
      9 
     10 **Source code:** :source:`Lib/fractions.py`
     11 
     12 --------------
     13 
     14 The :mod:`fractions` module provides support for rational number arithmetic.
     15 
     16 
     17 A Fraction instance can be constructed from a pair of integers, from
     18 another 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 properties and methods:
     82 
     83    .. versionchanged:: 3.2
     84       The :class:`Fraction` constructor now accepts :class:`float` and
     85       :class:`decimal.Decimal` instances.
     86 
     87 
     88    .. attribute:: numerator
     89 
     90       Numerator of the Fraction in lowest term.
     91 
     92    .. attribute:: denominator
     93 
     94       Denominator of the Fraction in lowest term.
     95 
     96 
     97    .. method:: from_float(flt)
     98 
     99       This class method constructs a :class:`Fraction` representing the exact
    100       value of *flt*, which must be a :class:`float`. Beware that
    101       ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``.
    102 
    103       .. note::
    104 
    105          From Python 3.2 onwards, you can also construct a
    106          :class:`Fraction` instance directly from a :class:`float`.
    107 
    108 
    109    .. method:: from_decimal(dec)
    110 
    111       This class method constructs a :class:`Fraction` representing the exact
    112       value of *dec*, which must be a :class:`decimal.Decimal` instance.
    113 
    114       .. note::
    115 
    116          From Python 3.2 onwards, you can also construct a
    117          :class:`Fraction` instance directly from a :class:`decimal.Decimal`
    118          instance.
    119 
    120 
    121    .. method:: limit_denominator(max_denominator=1000000)
    122 
    123       Finds and returns the closest :class:`Fraction` to ``self`` that has
    124       denominator at most max_denominator.  This method is useful for finding
    125       rational approximations to a given floating-point number:
    126 
    127          >>> from fractions import Fraction
    128          >>> Fraction('3.1415926535897932').limit_denominator(1000)
    129          Fraction(355, 113)
    130 
    131       or for recovering a rational number that's represented as a float:
    132 
    133          >>> from math import pi, cos
    134          >>> Fraction(cos(pi/3))
    135          Fraction(4503599627370497, 9007199254740992)
    136          >>> Fraction(cos(pi/3)).limit_denominator()
    137          Fraction(1, 2)
    138          >>> Fraction(1.1).limit_denominator()
    139          Fraction(11, 10)
    140 
    141 
    142    .. method:: __floor__()
    143 
    144       Returns the greatest :class:`int` ``<= self``.  This method can
    145       also be accessed through the :func:`math.floor` function:
    146 
    147         >>> from math import floor
    148         >>> floor(Fraction(355, 113))
    149         3
    150 
    151 
    152    .. method:: __ceil__()
    153 
    154       Returns the least :class:`int` ``>= self``.  This method can
    155       also be accessed through the :func:`math.ceil` function.
    156 
    157 
    158    .. method:: __round__()
    159                __round__(ndigits)
    160 
    161       The first version returns the nearest :class:`int` to ``self``,
    162       rounding half to even. The second version rounds ``self`` to the
    163       nearest multiple of ``Fraction(1, 10**ndigits)`` (logically, if
    164       ``ndigits`` is negative), again rounding half toward even.  This
    165       method can also be accessed through the :func:`round` function.
    166 
    167 
    168 .. function:: gcd(a, b)
    169 
    170    Return the greatest common divisor of the integers *a* and *b*.  If either
    171    *a* or *b* is nonzero, then the absolute value of ``gcd(a, b)`` is the
    172    largest integer that divides both *a* and *b*.  ``gcd(a,b)`` has the same
    173    sign as *b* if *b* is nonzero; otherwise it takes the sign of *a*.  ``gcd(0,
    174    0)`` returns ``0``.
    175 
    176    .. deprecated:: 3.5
    177       Use :func:`math.gcd` instead.
    178 
    179 
    180 .. seealso::
    181 
    182    Module :mod:`numbers`
    183       The abstract base classes making up the numeric tower.
    184