mirror of
https://github.com/python/cpython.git
synced 2025-10-31 18:28:49 +00:00
3e09f3152e
This PR adds support for float-style formatting for `Fraction` objects: it supports the `"e"`, `"E"`, `"f"`, `"F"`, `"g"`, `"G"` and `"%"` presentation types, and all the various bells and whistles of the formatting mini-language for those presentation types. The behaviour almost exactly matches that of `float`, but the implementation works with the exact `Fraction` value and does not do an intermediate conversion to `float`, and so avoids loss of precision or issues with numbers that are outside the dynamic range of the `float` type.
Note that the `"n"` presentation type is _not_ supported. That support could be added later if people have a need for it.
There's one corner-case where the behaviour differs from that of float: for the `float` type, if explicit alignment is specified with a fill character of `'0'` and alignment type `'='`, then thousands separators (if specified) are inserted into the padding string:
```python
>>> format(3.14, '0=11,.2f')
'0,000,003.14'
```
The exact same effect can be achieved by using the `'0'` flag:
```python
>>> format(3.14, '011,.2f')
'0,000,003.14'
```
For `Fraction`, only the `'0'` flag has the above behaviour with respect to thousands separators: there's no special-casing of the particular `'0='` fill-character/alignment combination. Instead, we treat the fill character `'0'` just like any other:
```python
>>> format(Fraction('3.14'), '0=11,.2f')
'00000003.14'
>>> format(Fraction('3.14'), '011,.2f')
'0,000,003.14'
```
The `Fraction` formatter is also stricter about combining these two things: it's not permitted to use both the `'0'` flag _and_ explicit alignment, on the basis that we should refuse the temptation to guess in the face of ambiguity. `float` is less picky:
```python
>>> format(3.14, '0<011,.2f')
'3.140000000'
>>> format(Fraction('3.14'), '0<011,.2f')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/Users/mdickinson/Repositories/python/cpython/Lib/fractions.py", line 414, in __format__
raise ValueError(
ValueError: Invalid format specifier '0<011,.2f' for object of type 'Fraction'; can't use explicit alignment when zero-padding
```
228 lines
8 KiB
ReStructuredText
228 lines
8 KiB
ReStructuredText
: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 :const:`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 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 ``"%""``.
|
|
|
|
.. 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 Fraction and with 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 float-style formatting of :class:`Fraction`
|
|
instances via the :meth:`str.format` method, the :func:`format` built-in
|
|
function, or :ref:`Formatted string literals <f-strings>`. The
|
|
presentation types ``"e"``, ``"E"``, ``"f"``, ``"F"``, ``"g"``, ``"G"``
|
|
and ``"%"`` are supported. For these presentation types, formatting for a
|
|
:class:`Fraction` object ``x`` follows the rules outlined for
|
|
the :class:`float` type in the :ref:`formatspec` section.
|
|
|
|
Here are some examples::
|
|
|
|
>>> from fractions import Fraction
|
|
>>> 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.
|