| |
| :mod:`fractions` --- Rational numbers |
| ===================================== |
| |
| .. module:: fractions |
| :synopsis: Rational numbers. |
| .. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com> |
| .. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com> |
| |
| |
| The :mod:`fractions` module provides support for rational number arithmetic. |
| |
| |
| A Fraction instance can be constructed from a pair of integers, from |
| another rational number, or from a string. |
| |
| .. class:: Fraction(numerator=0, denominator=1) |
| Fraction(other_fraction) |
| Fraction(string) |
| |
| The first version requires that *numerator* and *denominator* are |
| instances of :class:`numbers.Integral` and returns a new |
| :class:`Fraction` instance with value ``numerator/denominator``. If |
| *denominator* is :const:`0`, it raises a |
| :exc:`ZeroDivisionError`. The second version requires that |
| *other_fraction* is an instance of :class:`numbers.Rational` and |
| returns an :class:`Fraction` instance with the same value. The |
| last version of the constructor expects a string or unicode |
| instance in one of two possible forms. The first form is:: |
| |
| [sign] numerator ['/' denominator] |
| |
| where the optional ``sign`` may be either '+' or '-' and |
| ``numerator`` and ``denominator`` (if present) are strings of |
| decimal digits. The second permitted form is that of a number |
| containing a decimal point:: |
| |
| [sign] integer '.' [fraction] | [sign] '.' fraction |
| |
| where ``integer`` and ``fraction`` are strings of digits. In |
| either form the input string may also have leading and/or trailing |
| whitespace. Here are some examples:: |
| |
| >>> from fractions import Fraction |
| >>> Fraction(16, -10) |
| Fraction(-8, 5) |
| >>> Fraction(123) |
| Fraction(123, 1) |
| >>> Fraction() |
| Fraction(0, 1) |
| >>> Fraction('3/7') |
| Fraction(3, 7) |
| [40794 refs] |
| >>> Fraction(' -3/7 ') |
| Fraction(-3, 7) |
| >>> Fraction('1.414213 \t\n') |
| Fraction(1414213, 1000000) |
| >>> Fraction('-.125') |
| Fraction(-1, 8) |
| |
| |
| The :class:`Fraction` class inherits from the abstract base class |
| :class:`numbers.Rational`, and implements all of the methods and |
| operations from that class. :class:`Fraction` instances are hashable, |
| and should be treated as immutable. In addition, |
| :class:`Fraction` has the following methods: |
| |
| |
| .. method:: from_float(flt) |
| |
| This class method constructs a :class:`Fraction` representing the exact |
| value of *flt*, which must be a :class:`float`. Beware that |
| ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)`` |
| |
| |
| .. method:: from_decimal(dec) |
| |
| This class method constructs a :class:`Fraction` representing the exact |
| value of *dec*, which must be a :class:`decimal.Decimal` instance. |
| |
| |
| .. method:: limit_denominator(max_denominator=1000000) |
| |
| Finds and returns the closest :class:`Fraction` to ``self`` that has |
| denominator at most max_denominator. This method is useful for finding |
| rational approximations to a given floating-point number: |
| |
| >>> from fractions import Fraction |
| >>> Fraction('3.1415926535897932').limit_denominator(1000) |
| Fraction(355, 113) |
| |
| or for recovering a rational number that's represented as a float: |
| |
| >>> from math import pi, cos |
| >>> Fraction.from_float(cos(pi/3)) |
| Fraction(4503599627370497, 9007199254740992) |
| >>> Fraction.from_float(cos(pi/3)).limit_denominator() |
| Fraction(1, 2) |
| |
| |
| .. method:: __floor__() |
| |
| Returns the greatest :class:`int` ``<= self``. This method can |
| also be accessed through the :func:`math.floor` function: |
| |
| >>> from math import floor |
| >>> floor(Fraction(355, 113)) |
| 3 |
| |
| |
| .. method:: __ceil__() |
| |
| Returns the least :class:`int` ``>= self``. This method can |
| also be accessed through the :func:`math.ceil` function. |
| |
| |
| .. method:: __round__() |
| __round__(ndigits) |
| |
| The first version returns the nearest :class:`int` to ``self``, |
| rounding half to even. The second version rounds ``self`` to the |
| nearest multiple of ``Fraction(1, 10**ndigits)`` (logically, if |
| ``ndigits`` is negative), again rounding half toward even. This |
| method can also be accessed through the :func:`round` function. |
| |
| |
| .. function:: gcd(a, b) |
| |
| Return the greatest common divisor of the integers `a` and `b`. If |
| either `a` or `b` is nonzero, then the absolute value of `gcd(a, |
| b)` is the largest integer that divides both `a` and `b`. `gcd(a,b)` |
| has the same sign as `b` if `b` is nonzero; otherwise it takes the sign |
| of `a`. `gcd(0, 0)` returns `0`. |
| |
| |
| .. seealso:: |
| |
| Module :mod:`numbers` |
| The abstract base classes making up the numeric tower. |