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 14The :mod:`fractions` module provides support for rational number arithmetic. 15 16 17A Fraction instance can be constructed from a pair of integers, from 18another 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 .. versionchanged:: 3.9 88 The :func:`math.gcd` function is now used to normalize the *numerator* 89 and *denominator*. :func:`math.gcd` always return a :class:`int` type. 90 Previously, the GCD type depended on *numerator* and *denominator*. 91 92 .. attribute:: numerator 93 94 Numerator of the Fraction in lowest term. 95 96 .. attribute:: denominator 97 98 Denominator of the Fraction in lowest term. 99 100 101 .. method:: as_integer_ratio() 102 103 Return a tuple of two integers, whose ratio is equal 104 to the Fraction and with a positive denominator. 105 106 .. versionadded:: 3.8 107 108 .. method:: from_float(flt) 109 110 This class method constructs a :class:`Fraction` representing the exact 111 value of *flt*, which must be a :class:`float`. Beware that 112 ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``. 113 114 .. note:: 115 116 From Python 3.2 onwards, you can also construct a 117 :class:`Fraction` instance directly from a :class:`float`. 118 119 120 .. method:: from_decimal(dec) 121 122 This class method constructs a :class:`Fraction` representing the exact 123 value of *dec*, which must be a :class:`decimal.Decimal` instance. 124 125 .. note:: 126 127 From Python 3.2 onwards, you can also construct a 128 :class:`Fraction` instance directly from a :class:`decimal.Decimal` 129 instance. 130 131 132 .. method:: limit_denominator(max_denominator=1000000) 133 134 Finds and returns the closest :class:`Fraction` to ``self`` that has 135 denominator at most max_denominator. This method is useful for finding 136 rational approximations to a given floating-point number: 137 138 >>> from fractions import Fraction 139 >>> Fraction('3.1415926535897932').limit_denominator(1000) 140 Fraction(355, 113) 141 142 or for recovering a rational number that's represented as a float: 143 144 >>> from math import pi, cos 145 >>> Fraction(cos(pi/3)) 146 Fraction(4503599627370497, 9007199254740992) 147 >>> Fraction(cos(pi/3)).limit_denominator() 148 Fraction(1, 2) 149 >>> Fraction(1.1).limit_denominator() 150 Fraction(11, 10) 151 152 153 .. method:: __floor__() 154 155 Returns the greatest :class:`int` ``<= self``. This method can 156 also be accessed through the :func:`math.floor` function: 157 158 >>> from math import floor 159 >>> floor(Fraction(355, 113)) 160 3 161 162 163 .. method:: __ceil__() 164 165 Returns the least :class:`int` ``>= self``. This method can 166 also be accessed through the :func:`math.ceil` function. 167 168 169 .. method:: __round__() 170 __round__(ndigits) 171 172 The first version returns the nearest :class:`int` to ``self``, 173 rounding half to even. The second version rounds ``self`` to the 174 nearest multiple of ``Fraction(1, 10**ndigits)`` (logically, if 175 ``ndigits`` is negative), again rounding half toward even. This 176 method can also be accessed through the :func:`round` function. 177 178 179.. seealso:: 180 181 Module :mod:`numbers` 182 The abstract base classes making up the numeric tower. 183