cpython/Doc/library/fractions.rst

: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.

.. index:: single: as_integer_ratio()

.. class:: Fraction(numerator=0, denominator=1)
           Fraction(number)
           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 *number* is an instance of
   :class:`numbers.Rational` or has the :meth:`!as_integer_ratio` method
   (this includes :class:`float` and :class:`decimal.Decimal`).
   It returns a :class:`Fraction` instance with exactly the same value.
   Assumed, that the :meth:`!as_integer_ratio` method returns a pair
   of coprime integers and last one is positive.
   Note that due to the
   usual issues with binary 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.
   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 returns an :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.

   .. versionchanged:: 3.14
      The :class:`Fraction` constructor now accepts any objects with the
      :meth:`!as_integer_ratio` method.

   .. 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.