| :mod:`fractions` --- Rational numbers |
| ===================================== |
| |
| .. module:: fractions |
| :synopsis: Rational numbers. |
| |
| .. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com> |
| .. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com> |
| |
| **Source code:** :source:`Lib/fractions.py` |
| |
| -------------- |
| |
| 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(float) |
| Fraction(decimal) |
| Fraction(string) |
| |
| The first version requires that *numerator* and *denominator* are instances |
| of :class:`numbers.Rational` and returns a new :class:`Fraction` instance |
| with value ``numerator/denominator``. If *denominator* is ``0``, it |
| raises a :exc:`ZeroDivisionError`. The second version requires that |
| *other_fraction* is an instance of :class:`numbers.Rational` and returns a |
| :class:`Fraction` instance with the same value. The next two versions accept |
| either a :class:`float` or a :class:`decimal.Decimal` instance, and return a |
| :class:`Fraction` instance with exactly the same value. Note that due to the |
| usual issues with binary floating-point (see :ref:`tut-fp-issues`), the |
| argument to ``Fraction(1.1)`` is not exactly equal to 11/10, and so |
| ``Fraction(1.1)`` does *not* return ``Fraction(11, 10)`` as one might expect. |
| (But see the documentation for the :meth:`limit_denominator` method below.) |
| The last version of the constructor expects a string or unicode instance. |
| The usual form for this instance is:: |
| |
| [sign] numerator ['/' denominator] |
| |
| where the optional ``sign`` may be either '+' or '-' and |
| ``numerator`` and ``denominator`` (if present) are strings of |
| decimal digits (underscores may be used to delimit digits as with |
| integral literals in code). In addition, any string that represents a finite |
| value and is accepted by the :class:`float` constructor is also |
| accepted by the :class:`Fraction` constructor. 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) |
| >>> Fraction(' -3/7 ') |
| Fraction(-3, 7) |
| >>> Fraction('1.414213 \t\n') |
| Fraction(1414213, 1000000) |
| >>> Fraction('-.125') |
| Fraction(-1, 8) |
| >>> Fraction('7e-6') |
| Fraction(7, 1000000) |
| >>> Fraction(2.25) |
| Fraction(9, 4) |
| >>> Fraction(1.1) |
| Fraction(2476979795053773, 2251799813685248) |
| >>> from decimal import Decimal |
| >>> Fraction(Decimal('1.1')) |
| Fraction(11, 10) |
| |
| |
| 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 :term:`hashable`, |
| and should be treated as immutable. In addition, |
| :class:`Fraction` has the following properties and methods: |
| |
| .. versionchanged:: 3.2 |
| The :class:`Fraction` constructor now accepts :class:`float` and |
| :class:`decimal.Decimal` instances. |
| |
| .. versionchanged:: 3.9 |
| The :func:`math.gcd` function is now used to normalize the *numerator* |
| and *denominator*. :func:`math.gcd` always return a :class:`int` type. |
| Previously, the GCD type depended on *numerator* and *denominator*. |
| |
| .. versionchanged:: 3.11 |
| Underscores are now permitted when creating a :class:`Fraction` instance |
| from a string, following :PEP:`515` rules. |
| |
| .. versionchanged:: 3.11 |
| :class:`Fraction` implements ``__int__`` now to satisfy |
| ``typing.SupportsInt`` instance checks. |
| |
| .. versionchanged:: 3.12 |
| Space is allowed around the slash for string inputs: ``Fraction('2 / 3')``. |
| |
| .. versionchanged:: 3.12 |
| :class:`Fraction` instances now support float-style formatting, with |
| presentation types ``"e"``, ``"E"``, ``"f"``, ``"F"``, ``"g"``, ``"G"`` |
| and ``"%""``. |
| |
| .. versionchanged:: 3.13 |
| Formatting of :class:`Fraction` instances without a presentation type |
| now supports fill, alignment, sign handling, minimum width and grouping. |
| |
| .. attribute:: numerator |
| |
| Numerator of the Fraction in lowest term. |
| |
| .. attribute:: denominator |
| |
| Denominator of the Fraction in lowest term. |
| |
| |
| .. method:: as_integer_ratio() |
| |
| Return a tuple of two integers, whose ratio is equal |
| to the original Fraction. The ratio is in lowest terms |
| and has a positive denominator. |
| |
| .. versionadded:: 3.8 |
| |
| .. method:: is_integer() |
| |
| Return ``True`` if the Fraction is an integer. |
| |
| .. versionadded:: 3.12 |
| |
| .. classmethod:: from_float(flt) |
| |
| Alternative constructor which only accepts instances of |
| :class:`float` or :class:`numbers.Integral`. Beware that |
| ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``. |
| |
| .. note:: |
| |
| From Python 3.2 onwards, you can also construct a |
| :class:`Fraction` instance directly from a :class:`float`. |
| |
| |
| .. classmethod:: from_decimal(dec) |
| |
| Alternative constructor which only accepts instances of |
| :class:`decimal.Decimal` or :class:`numbers.Integral`. |
| |
| .. note:: |
| |
| From Python 3.2 onwards, you can also construct a |
| :class:`Fraction` instance directly from 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(cos(pi/3)) |
| Fraction(4503599627370497, 9007199254740992) |
| >>> Fraction(cos(pi/3)).limit_denominator() |
| Fraction(1, 2) |
| >>> Fraction(1.1).limit_denominator() |
| Fraction(11, 10) |
| |
| |
| .. 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. |
| |
| .. method:: __format__(format_spec, /) |
| |
| Provides support for formatting of :class:`Fraction` instances via the |
| :meth:`str.format` method, the :func:`format` built-in function, or |
| :ref:`Formatted string literals <f-strings>`. |
| |
| If the ``format_spec`` format specification string does not end with one |
| of the presentation types ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``, |
| ``'G'`` or ``'%'`` then formatting follows the general rules for fill, |
| alignment, sign handling, minimum width, and grouping as described in the |
| :ref:`format specification mini-language <formatspec>`. The "alternate |
| form" flag ``'#'`` is supported: if present, it forces the output string |
| to always include an explicit denominator, even when the value being |
| formatted is an exact integer. The zero-fill flag ``'0'`` is not |
| supported. |
| |
| If the ``format_spec`` format specification string ends with one of |
| the presentation types ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``, |
| ``'G'`` or ``'%'`` then formatting follows the rules outlined for the |
| :class:`float` type in the :ref:`formatspec` section. |
| |
| Here are some examples:: |
| |
| >>> from fractions import Fraction |
| >>> format(Fraction(103993, 33102), '_') |
| '103_993/33_102' |
| >>> format(Fraction(1, 7), '.^+10') |
| '...+1/7...' |
| >>> format(Fraction(3, 1), '') |
| '3' |
| >>> format(Fraction(3, 1), '#') |
| '3/1' |
| >>> format(Fraction(1, 7), '.40g') |
| '0.1428571428571428571428571428571428571429' |
| >>> format(Fraction('1234567.855'), '_.2f') |
| '1_234_567.86' |
| >>> f"{Fraction(355, 113):*>20.6e}" |
| '********3.141593e+00' |
| >>> old_price, new_price = 499, 672 |
| >>> "{:.2%} price increase".format(Fraction(new_price, old_price) - 1) |
| '34.67% price increase' |
| |
| |
| .. seealso:: |
| |
| Module :mod:`numbers` |
| The abstract base classes making up the numeric tower. |
