Changeset 391 for python/trunk/Doc/library/fractions.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/fractions.rst (modified) (10 diffs)

python/trunk/Doc/library/fractions.rst

@@ -1 @@
-
 :mod:`fractions` --- Rational numbers
 =====================================
@@ -9 +8 @@
 .. versionadded:: 2.6
 
+**Source code:** :source:`Lib/fractions.py`
+
+--------------
 
 The :mod:`fractions` module provides support for rational number arithmetic.
@@ -18 +20 @@
 .. 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.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::
+   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]
@@ -34 +43 @@
    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::
+   decimal digits.  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
@@ -52 +58 @@
       >>> Fraction('3/7')
       Fraction(3, 7)
-      [40794 refs]
       >>> Fraction(' -3/7 ')
       Fraction(-3, 7)
@@ -59 +64 @@
       >>> 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)
 
 
@@ -67 +81 @@
    :class:`Fraction` has the following methods:
 
+   .. versionchanged:: 2.7
+      The :class:`Fraction` constructor now accepts :class:`float` and
+      :class:`decimal.Decimal` instances.
+
 
    .. method:: from_float(flt)
@@ -74 +92 @@
       ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``
 
+      .. note:: From Python 2.7 onwards, you can also construct a
+         :class:`Fraction` instance directly from a :class:`float`.
+
 
    .. method:: from_decimal(dec)
@@ -79 +100 @@
       This class method constructs a :class:`Fraction` representing the exact
       value of *dec*, which must be a :class:`decimal.Decimal`.
+
+      .. note:: From Python 2.7 onwards, you can also construct a
+         :class:`Fraction` instance directly from a :class:`decimal.Decimal`
+         instance.
 
 
@@ -94 +119 @@
 
          >>> from math import pi, cos
-         >>> Fraction.from_float(cos(pi/3))
+         >>> Fraction(cos(pi/3))
          Fraction(4503599627370497, 9007199254740992)
-         >>> Fraction.from_float(cos(pi/3)).limit_denominator()
+         >>> Fraction(cos(pi/3)).limit_denominator()
          Fraction(1, 2)
+         >>> Fraction(1.1).limit_denominator()
+         Fraction(11, 10)