2 :mod:`fractions` --- Rational numbers
3 =====================================
6 :synopsis: Rational numbers.
7 .. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
8 .. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
12 The :mod:`fractions` module defines an immutable, infinite-precision
13 Fraction number class.
16 .. class:: Fraction(numerator=0, denominator=1)
17 Fraction(other_fraction)
20 The first version requires that *numerator* and *denominator* are
21 instances of :class:`numbers.Integral` and returns a new
22 ``Fraction`` representing ``numerator/denominator``. If
23 *denominator* is :const:`0`, raises a :exc:`ZeroDivisionError`. The
24 second version requires that *other_fraction* is an instance of
25 :class:`numbers.Rational` and returns an instance of
26 :class:`Fraction` with the same value. The third version expects a
27 string of the form ``[-+]?[0-9]+(/[0-9]+)?``, optionally surrounded
30 Implements all of the methods and operations from
31 :class:`numbers.Rational` and is immutable and hashable.
34 .. method:: from_float(flt)
36 This classmethod constructs a :class:`Fraction` representing the exact
37 value of *flt*, which must be a :class:`float`. Beware that
38 ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``
41 .. method:: from_decimal(dec)
43 This classmethod constructs a :class:`Fraction` representing the exact
44 value of *dec*, which must be a :class:`decimal.Decimal`.
47 .. method:: limit_denominator(max_denominator=1000000)
49 Finds and returns the closest :class:`Fraction` to ``self`` that has
50 denominator at most max_denominator. This method is useful for finding
51 rational approximations to a given floating-point number:
53 >>> from fractions import Fraction
54 >>> Fraction('3.1415926535897932').limit_denominator(1000)
57 or for recovering a rational number that's represented as a float:
59 >>> from math import pi, cos
60 >>> Fraction.from_float(cos(pi/3))
61 Fraction(4503599627370497L, 9007199254740992L)
62 >>> Fraction.from_float(cos(pi/3)).limit_denominator()
66 .. method:: __floor__()
68 Returns the greatest :class:`int` ``<= self``. Will be accessible through
69 :func:`math.floor` in Py3k.
72 .. method:: __ceil__()
74 Returns the least :class:`int` ``>= self``. Will be accessible through
75 :func:`math.ceil` in Py3k.
78 .. method:: __round__()
81 The first version returns the nearest :class:`int` to ``self``, rounding
82 half to even. The second version rounds ``self`` to the nearest multiple
83 of ``Fraction(1, 10**ndigits)`` (logically, if ``ndigits`` is negative),
84 again rounding half toward even. Will be accessible through :func:`round`
91 The abstract base classes making up the numeric tower.