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 | |
| 9 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 10 | The :mod:`fractions` module provides support for rational number arithmetic. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 11 | |
| 12 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 13 | A Fraction instance can be constructed from a pair of integers, from |
| 14 | another rational number, or from a string. |
| 15 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 16 | .. class:: Fraction(numerator=0, denominator=1) |
| 17 | Fraction(other_fraction) |
| 18 | Fraction(string) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 19 | |
| 20 | The first version requires that *numerator* and *denominator* are |
| 21 | instances of :class:`numbers.Integral` and returns a new |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 22 | :class:`Fraction` instance with value ``numerator/denominator``. If |
| 23 | *denominator* is :const:`0`, it raises a |
| 24 | :exc:`ZeroDivisionError`. The second version requires that |
| 25 | *other_fraction* is an instance of :class:`numbers.Rational` and |
| 26 | returns an :class:`Fraction` instance with the same value. The |
Mark Dickinson | cf63f2f | 2009-04-22 17:50:21 +0000 | [diff] [blame] | 27 | last version of the constructor expects a string instance. The |
| 28 | usual form for this string is:: |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 29 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 30 | [sign] numerator ['/' denominator] |
| 31 | |
| 32 | where the optional ``sign`` may be either '+' or '-' and |
| 33 | ``numerator`` and ``denominator`` (if present) are strings of |
Mark Dickinson | cf63f2f | 2009-04-22 17:50:21 +0000 | [diff] [blame] | 34 | decimal digits. In addition, any string that represents a finite |
| 35 | value and is accepted by the :class:`float` constructor is also |
| 36 | accepted by the :class:`Fraction` constructor. In either form the |
| 37 | input string may also have leading and/or trailing whitespace. |
| 38 | Here are some examples:: |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 39 | |
| 40 | >>> from fractions import Fraction |
| 41 | >>> Fraction(16, -10) |
| 42 | Fraction(-8, 5) |
| 43 | >>> Fraction(123) |
| 44 | Fraction(123, 1) |
| 45 | >>> Fraction() |
| 46 | Fraction(0, 1) |
| 47 | >>> Fraction('3/7') |
| 48 | Fraction(3, 7) |
| 49 | [40794 refs] |
| 50 | >>> Fraction(' -3/7 ') |
| 51 | Fraction(-3, 7) |
| 52 | >>> Fraction('1.414213 \t\n') |
| 53 | Fraction(1414213, 1000000) |
| 54 | >>> Fraction('-.125') |
| 55 | Fraction(-1, 8) |
Mark Dickinson | cf63f2f | 2009-04-22 17:50:21 +0000 | [diff] [blame] | 56 | >>> Fraction('7e-6') |
| 57 | Fraction(7, 1000000) |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 58 | |
| 59 | |
| 60 | The :class:`Fraction` class inherits from the abstract base class |
| 61 | :class:`numbers.Rational`, and implements all of the methods and |
| 62 | operations from that class. :class:`Fraction` instances are hashable, |
| 63 | and should be treated as immutable. In addition, |
| 64 | :class:`Fraction` has the following methods: |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 65 | |
| 66 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 67 | .. method:: from_float(flt) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 68 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 69 | This class method constructs a :class:`Fraction` representing the exact |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 70 | value of *flt*, which must be a :class:`float`. Beware that |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 71 | ``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] | 72 | |
| 73 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 74 | .. method:: from_decimal(dec) |
Christian Heimes | 587c2bf | 2008-01-19 16:21:02 +0000 | [diff] [blame] | 75 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 76 | This class method constructs a :class:`Fraction` representing the exact |
Mark Dickinson | 268bf4a | 2008-06-24 15:32:27 +0000 | [diff] [blame] | 77 | value of *dec*, which must be a :class:`decimal.Decimal` instance. |
Christian Heimes | 587c2bf | 2008-01-19 16:21:02 +0000 | [diff] [blame] | 78 | |
| 79 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 80 | .. method:: limit_denominator(max_denominator=1000000) |
Christian Heimes | 68f5fbe | 2008-02-14 08:27:37 +0000 | [diff] [blame] | 81 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 82 | Finds and returns the closest :class:`Fraction` to ``self`` that has |
| 83 | denominator at most max_denominator. This method is useful for finding |
| 84 | rational approximations to a given floating-point number: |
Christian Heimes | 68f5fbe | 2008-02-14 08:27:37 +0000 | [diff] [blame] | 85 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 86 | >>> from fractions import Fraction |
| 87 | >>> Fraction('3.1415926535897932').limit_denominator(1000) |
Mark Dickinson | 79edbd5 | 2008-06-24 14:26:24 +0000 | [diff] [blame] | 88 | Fraction(355, 113) |
Christian Heimes | 68f5fbe | 2008-02-14 08:27:37 +0000 | [diff] [blame] | 89 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 90 | or for recovering a rational number that's represented as a float: |
Christian Heimes | 68f5fbe | 2008-02-14 08:27:37 +0000 | [diff] [blame] | 91 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 92 | >>> from math import pi, cos |
| 93 | >>> Fraction.from_float(cos(pi/3)) |
Mark Dickinson | 79edbd5 | 2008-06-24 14:26:24 +0000 | [diff] [blame] | 94 | Fraction(4503599627370497, 9007199254740992) |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 95 | >>> Fraction.from_float(cos(pi/3)).limit_denominator() |
Mark Dickinson | 79edbd5 | 2008-06-24 14:26:24 +0000 | [diff] [blame] | 96 | Fraction(1, 2) |
Christian Heimes | 68f5fbe | 2008-02-14 08:27:37 +0000 | [diff] [blame] | 97 | |
| 98 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 99 | .. method:: __floor__() |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 100 | |
Mark Dickinson | 268bf4a | 2008-06-24 15:32:27 +0000 | [diff] [blame] | 101 | Returns the greatest :class:`int` ``<= self``. This method can |
| 102 | also be accessed through the :func:`math.floor` function: |
| 103 | |
| 104 | >>> from math import floor |
| 105 | >>> floor(Fraction(355, 113)) |
| 106 | 3 |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 107 | |
| 108 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 109 | .. method:: __ceil__() |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 110 | |
Mark Dickinson | 268bf4a | 2008-06-24 15:32:27 +0000 | [diff] [blame] | 111 | Returns the least :class:`int` ``>= self``. This method can |
| 112 | also be accessed through the :func:`math.ceil` function. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 113 | |
| 114 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 115 | .. method:: __round__() |
| 116 | __round__(ndigits) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 117 | |
Mark Dickinson | 268bf4a | 2008-06-24 15:32:27 +0000 | [diff] [blame] | 118 | The first version returns the nearest :class:`int` to ``self``, |
| 119 | rounding half to even. The second version rounds ``self`` to the |
| 120 | nearest multiple of ``Fraction(1, 10**ndigits)`` (logically, if |
| 121 | ``ndigits`` is negative), again rounding half toward even. This |
| 122 | method can also be accessed through the :func:`round` function. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 123 | |
| 124 | |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 125 | .. function:: gcd(a, b) |
| 126 | |
Georg Brandl | 36ab1ef | 2009-01-03 21:17:04 +0000 | [diff] [blame] | 127 | Return the greatest common divisor of the integers *a* and *b*. If either |
| 128 | *a* or *b* is nonzero, then the absolute value of ``gcd(a, b)`` is the |
| 129 | largest integer that divides both *a* and *b*. ``gcd(a,b)`` has the same |
| 130 | sign as *b* if *b* is nonzero; otherwise it takes the sign of *a*. ``gcd(0, |
| 131 | 0)`` returns ``0``. |
Mark Dickinson | ce279a7 | 2008-06-27 17:01:17 +0000 | [diff] [blame] | 132 | |
| 133 | |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 134 | .. seealso:: |
| 135 | |
| 136 | Module :mod:`numbers` |
| 137 | The abstract base classes making up the numeric tower. |