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

   105    either `a` or `b` is nonzero, then the absolute value of `gcd(a,

   106    b)` is the largest integer that divides both `a` and `b`.  `gcd(a,b)`

   107    has the same sign as `b` if `b` is nonzero; otherwise it takes the sign

   108    of `a`.  `gcd(0, 0)` returns `0`.

   109 

   110 

   111 .. seealso::

   112 

   113    Module :mod:`numbers`

   114       The abstract base classes making up the numeric tower.