Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 1 | :mod:`fractions` --- Rational numbers |
Christian Heimes | 0bd4e11 | 2008-02-12 22:59:25 +0000 | [diff] [blame] | 2 | ===================================== |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 3 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 4 | .. module:: fractions |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 5 | :synopsis: Rational numbers. |
| 6 | .. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com> |
| 7 | .. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com> |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 8 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 9 | **Source code:** :source:`Lib/fractions.py` |
| 10 | |
| 11 | -------------- |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 12 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 13 | The :mod:`fractions` module provides support for rational number arithmetic. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 14 | |
| 15 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 16 | A Fraction instance can be constructed from a pair of integers, from |
| 17 | another rational number, or from a string. |
| 18 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 19 | .. class:: Fraction(numerator=0, denominator=1) |
| 20 | Fraction(other_fraction) |
Mark Dickinson | 98127c3 | 2010-04-03 11:18:52 +0000 | [diff] [blame] | 21 | Fraction(float) |
| 22 | Fraction(decimal) |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 23 | Fraction(string) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 24 | |
Mark Dickinson | 98127c3 | 2010-04-03 11:18:52 +0000 | [diff] [blame] | 25 | The first version requires that *numerator* and *denominator* are instances |
| 26 | of :class:`numbers.Rational` and returns a new :class:`Fraction` instance |
| 27 | with value ``numerator/denominator``. If *denominator* is :const:`0`, it |
| 28 | raises a :exc:`ZeroDivisionError`. The second version requires that |
| 29 | *other_fraction* is an instance of :class:`numbers.Rational` and returns a |
| 30 | :class:`Fraction` instance with the same value. The next two versions accept |
| 31 | either a :class:`float` or a :class:`decimal.Decimal` instance, and return a |
| 32 | :class:`Fraction` instance with exactly the same value. Note that due to the |
| 33 | usual issues with binary floating-point (see :ref:`tut-fp-issues`), the |
| 34 | argument to ``Fraction(1.1)`` is not exactly equal to 11/10, and so |
| 35 | ``Fraction(1.1)`` does *not* return ``Fraction(11, 10)`` as one might expect. |
| 36 | (But see the documentation for the :meth:`limit_denominator` method below.) |
| 37 | The last version of the constructor expects a string or unicode instance. |
| 38 | The usual form for this instance is:: |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 39 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 40 | [sign] numerator ['/' denominator] |
| 41 | |
| 42 | where the optional ``sign`` may be either '+' or '-' and |
| 43 | ``numerator`` and ``denominator`` (if present) are strings of |
Mark Dickinson | cf63f2f | 2009-04-22 17:50:21 +0000 | [diff] [blame] | 44 | decimal digits. In addition, any string that represents a finite |
| 45 | value and is accepted by the :class:`float` constructor is also |
| 46 | accepted by the :class:`Fraction` constructor. In either form the |
| 47 | input string may also have leading and/or trailing whitespace. |
| 48 | Here are some examples:: |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 49 | |
| 50 | >>> from fractions import Fraction |
| 51 | >>> Fraction(16, -10) |
| 52 | Fraction(-8, 5) |
| 53 | >>> Fraction(123) |
| 54 | Fraction(123, 1) |
| 55 | >>> Fraction() |
| 56 | Fraction(0, 1) |
| 57 | >>> Fraction('3/7') |
| 58 | Fraction(3, 7) |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 59 | >>> Fraction(' -3/7 ') |
| 60 | Fraction(-3, 7) |
| 61 | >>> Fraction('1.414213 \t\n') |
| 62 | Fraction(1414213, 1000000) |
| 63 | >>> Fraction('-.125') |
| 64 | Fraction(-1, 8) |
Mark Dickinson | cf63f2f | 2009-04-22 17:50:21 +0000 | [diff] [blame] | 65 | >>> Fraction('7e-6') |
| 66 | Fraction(7, 1000000) |
Mark Dickinson | 98127c3 | 2010-04-03 11:18:52 +0000 | [diff] [blame] | 67 | >>> Fraction(2.25) |
| 68 | Fraction(9, 4) |
| 69 | >>> Fraction(1.1) |
| 70 | Fraction(2476979795053773, 2251799813685248) |
| 71 | >>> from decimal import Decimal |
| 72 | >>> Fraction(Decimal('1.1')) |
| 73 | Fraction(11, 10) |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 74 | |
| 75 | |
| 76 | The :class:`Fraction` class inherits from the abstract base class |
| 77 | :class:`numbers.Rational`, and implements all of the methods and |
| 78 | operations from that class. :class:`Fraction` instances are hashable, |
| 79 | and should be treated as immutable. In addition, |
| 80 | :class:`Fraction` has the following methods: |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 81 | |
Mark Dickinson | 98127c3 | 2010-04-03 11:18:52 +0000 | [diff] [blame] | 82 | .. versionchanged:: 3.2 |
| 83 | The :class:`Fraction` constructor now accepts :class:`float` and |
| 84 | :class:`decimal.Decimal` instances. |
| 85 | |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 86 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 87 | .. method:: from_float(flt) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 88 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 89 | This class method constructs a :class:`Fraction` representing the exact |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 90 | value of *flt*, which must be a :class:`float`. Beware that |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 91 | ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)`` |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 92 | |
Mark Dickinson | 98127c3 | 2010-04-03 11:18:52 +0000 | [diff] [blame] | 93 | .. note:: From Python 3.2 onwards, you can also construct a |
| 94 | :class:`Fraction` instance directly from a :class:`float`. |
| 95 | |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 96 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 97 | .. method:: from_decimal(dec) |
Christian Heimes | 587c2bf | 2008-01-19 16:21:02 +0000 | [diff] [blame] | 98 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 99 | This class method constructs a :class:`Fraction` representing the exact |
Mark Dickinson | 268bf4a | 2008-06-24 15:32:27 +0000 | [diff] [blame] | 100 | value of *dec*, which must be a :class:`decimal.Decimal` instance. |
Christian Heimes | 587c2bf | 2008-01-19 16:21:02 +0000 | [diff] [blame] | 101 | |
Mark Dickinson | 98127c3 | 2010-04-03 11:18:52 +0000 | [diff] [blame] | 102 | .. note:: From Python 3.2 onwards, you can also construct a |
| 103 | :class:`Fraction` instance directly from a :class:`decimal.Decimal` |
| 104 | instance. |
| 105 | |
Christian Heimes | 587c2bf | 2008-01-19 16:21:02 +0000 | [diff] [blame] | 106 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 107 | .. method:: limit_denominator(max_denominator=1000000) |
Christian Heimes | 68f5fbe | 2008-02-14 08:27:37 +0000 | [diff] [blame] | 108 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 109 | Finds and returns the closest :class:`Fraction` to ``self`` that has |
| 110 | denominator at most max_denominator. This method is useful for finding |
| 111 | rational approximations to a given floating-point number: |
Christian Heimes | 68f5fbe | 2008-02-14 08:27:37 +0000 | [diff] [blame] | 112 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 113 | >>> from fractions import Fraction |
| 114 | >>> Fraction('3.1415926535897932').limit_denominator(1000) |
Mark Dickinson | 79edbd5 | 2008-06-24 14:26:24 +0000 | [diff] [blame] | 115 | Fraction(355, 113) |
Christian Heimes | 68f5fbe | 2008-02-14 08:27:37 +0000 | [diff] [blame] | 116 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 117 | or for recovering a rational number that's represented as a float: |
Christian Heimes | 68f5fbe | 2008-02-14 08:27:37 +0000 | [diff] [blame] | 118 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 119 | >>> from math import pi, cos |
Mark Dickinson | 98127c3 | 2010-04-03 11:18:52 +0000 | [diff] [blame] | 120 | >>> Fraction(cos(pi/3)) |
Mark Dickinson | 79edbd5 | 2008-06-24 14:26:24 +0000 | [diff] [blame] | 121 | Fraction(4503599627370497, 9007199254740992) |
Mark Dickinson | 98127c3 | 2010-04-03 11:18:52 +0000 | [diff] [blame] | 122 | >>> Fraction(cos(pi/3)).limit_denominator() |
Mark Dickinson | 79edbd5 | 2008-06-24 14:26:24 +0000 | [diff] [blame] | 123 | Fraction(1, 2) |
Mark Dickinson | 98127c3 | 2010-04-03 11:18:52 +0000 | [diff] [blame] | 124 | >>> Fraction(1.1).limit_denominator() |
| 125 | Fraction(11, 10) |
Christian Heimes | 68f5fbe | 2008-02-14 08:27:37 +0000 | [diff] [blame] | 126 | |
| 127 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 128 | .. method:: __floor__() |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 129 | |
Mark Dickinson | 268bf4a | 2008-06-24 15:32:27 +0000 | [diff] [blame] | 130 | Returns the greatest :class:`int` ``<= self``. This method can |
| 131 | also be accessed through the :func:`math.floor` function: |
| 132 | |
| 133 | >>> from math import floor |
| 134 | >>> floor(Fraction(355, 113)) |
| 135 | 3 |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 136 | |
| 137 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 138 | .. method:: __ceil__() |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 139 | |
Mark Dickinson | 268bf4a | 2008-06-24 15:32:27 +0000 | [diff] [blame] | 140 | Returns the least :class:`int` ``>= self``. This method can |
| 141 | also be accessed through the :func:`math.ceil` function. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 142 | |
| 143 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 144 | .. method:: __round__() |
| 145 | __round__(ndigits) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 146 | |
Mark Dickinson | 268bf4a | 2008-06-24 15:32:27 +0000 | [diff] [blame] | 147 | The first version returns the nearest :class:`int` to ``self``, |
| 148 | rounding half to even. The second version rounds ``self`` to the |
| 149 | nearest multiple of ``Fraction(1, 10**ndigits)`` (logically, if |
| 150 | ``ndigits`` is negative), again rounding half toward even. This |
| 151 | method can also be accessed through the :func:`round` function. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 152 | |
| 153 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 154 | .. function:: gcd(a, b) |
| 155 | |
Georg Brandl | 36ab1ef | 2009-01-03 21:17:04 +0000 | [diff] [blame] | 156 | Return the greatest common divisor of the integers *a* and *b*. If either |
| 157 | *a* or *b* is nonzero, then the absolute value of ``gcd(a, b)`` is the |
| 158 | largest integer that divides both *a* and *b*. ``gcd(a,b)`` has the same |
| 159 | sign as *b* if *b* is nonzero; otherwise it takes the sign of *a*. ``gcd(0, |
| 160 | 0)`` returns ``0``. |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 161 | |
| 162 | |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 163 | .. seealso:: |
| 164 | |
| 165 | Module :mod:`numbers` |
| 166 | The abstract base classes making up the numeric tower. |