1 :mod:`fractions` --- Rational numbers 2 ===================================== 3 4 .. module:: fractions 5 :synopsis: Rational numbers. 6 .. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com> 7 .. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com> 8 .. versionadded:: 2.6 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 methods: 82 83 .. versionchanged:: 2.7 84 The :class:`Fraction` constructor now accepts :class:`float` and 85 :class:`decimal.Decimal` instances. 86 87 88 .. method:: from_float(flt) 89 90 This class method constructs a :class:`Fraction` representing the exact 91 value of *flt*, which must be a :class:`float`. Beware that 92 ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``. 93 94 .. note:: From Python 2.7 onwards, you can also construct a 95 :class:`Fraction` instance directly from a :class:`float`. 96 97 98 .. method:: from_decimal(dec) 99 100 This class method constructs a :class:`Fraction` representing the exact 101 value of *dec*, which must be a :class:`decimal.Decimal`. 102 103 .. note:: From Python 2.7 onwards, you can also construct a 104 :class:`Fraction` instance directly from a :class:`decimal.Decimal` 105 instance. 106 107 108 .. method:: limit_denominator(max_denominator=1000000) 109 110 Finds and returns the closest :class:`Fraction` to ``self`` that has 111 denominator at most max_denominator. This method is useful for finding 112 rational approximations to a given floating-point number: 113 114 >>> from fractions import Fraction 115 >>> Fraction('3.1415926535897932').limit_denominator(1000) 116 Fraction(355, 113) 117 118 or for recovering a rational number that's represented as a float: 119 120 >>> from math import pi, cos 121 >>> Fraction(cos(pi/3)) 122 Fraction(4503599627370497, 9007199254740992) 123 >>> Fraction(cos(pi/3)).limit_denominator() 124 Fraction(1, 2) 125 >>> Fraction(1.1).limit_denominator() 126 Fraction(11, 10) 127 128 129 .. function:: gcd(a, b) 130 131 Return the greatest common divisor of the integers *a* and *b*. If either 132 *a* or *b* is nonzero, then the absolute value of ``gcd(a, b)`` is the 133 largest integer that divides both *a* and *b*. ``gcd(a,b)`` has the same 134 sign as *b* if *b* is nonzero; otherwise it takes the sign of *a*. ``gcd(0, 135 0)`` returns ``0``. 136 137 138 .. seealso:: 139 140 Module :mod:`numbers` 141 The abstract base classes making up the numeric tower. 142
