Merged revisions 60481,60485,60489-60492,60494-60496,60498-60499,60501-60503,60505-60506,60508-60509,60523-60524,60532,60543,60545,60547-60548,60552,60554,60556-60559,60561-60562,60569,60571-60572,60574,60576-60583,60585-60586,60589,60591,60594-60595,60597-60598,60600-60601,60606-60612,60615,60617,60619-60621,60623-60625,60627-60629,60631,60633,60635,60647,60650,60652,60654,60656,60658-60659,60664-60666,60668-60670,60672,60676,60678,60680-60683,60685-60686,60688,60690,60692-60694,60697-60700,60705-60706,60708,60711,60714,60720,60724-60730,60732,60736,60742,60744,60746,60748,60750-60766,60769-60786 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r60752 | mark.dickinson | 2008-02-12 22:31:59 +0100 (Tue, 12 Feb 2008) | 5 lines

  Implementation of Fraction.limit_denominator.

  Remove Fraction.to_continued_fraction and
  Fraction.from_continued_fraction
........
  r60754 | mark.dickinson | 2008-02-12 22:40:53 +0100 (Tue, 12 Feb 2008) | 3 lines

  Revert change in r60712:  turn alternate constructors back into
  classmethods instead of staticmethods.
........
  r60755 | mark.dickinson | 2008-02-12 22:46:54 +0100 (Tue, 12 Feb 2008) | 4 lines

  Replace R=fractions.Fraction with F=fractions.Fraction in
  test_fractions.py.  This should have been part of the name
  change from Rational to Fraction.
........
  r60758 | georg.brandl | 2008-02-13 08:20:22 +0100 (Wed, 13 Feb 2008) | 3 lines

  #2063: correct order of utime and stime in os.times()
  result on Windows.
........
  r60762 | jeffrey.yasskin | 2008-02-13 18:58:04 +0100 (Wed, 13 Feb 2008) | 7 lines

  Working on issue #1762: Brought
    ./python.exe -m timeit -s 'from fractions import Fraction; f = Fraction(3, 2)' 'isinstance(3, Fraction); isinstance(f, Fraction)'
  from 12.3 usec/loop to 3.44 usec/loop and
    ./python.exe -m timeit -s 'from fractions import Fraction' 'Fraction(3, 2)'
  from 48.8 usec to 23.6 usec by avoiding genexps and sets in __instancecheck__
  and inlining the common case from __subclasscheck__.
........
  r60765 | brett.cannon | 2008-02-13 20:15:44 +0100 (Wed, 13 Feb 2008) | 5 lines

  Fix --enable-universalsdk and its comment line so that zsh's flag completion
  works.

  Thanks to Jeroen Ruigrok van der Werven for the fix.
........
  r60771 | kurt.kaiser | 2008-02-14 01:08:55 +0100 (Thu, 14 Feb 2008) | 2 lines

  Bring NEWS.txt up to date from check-in msgs.
........
  r60772 | raymond.hettinger | 2008-02-14 02:08:02 +0100 (Thu, 14 Feb 2008) | 3 lines

  Update notes on Decimal.
........
  r60773 | raymond.hettinger | 2008-02-14 03:41:22 +0100 (Thu, 14 Feb 2008) | 1 line

  Fix decimal repr which should have used single quotes like other reprs.
........
  r60785 | jeffrey.yasskin | 2008-02-14 07:12:24 +0100 (Thu, 14 Feb 2008) | 11 lines

  Performance optimizations on Fraction's constructor.

    ./python.exe -m timeit -s 'from fractions import Fraction' 'Fraction(3)`
  31.7 usec/loop -> 9.2 usec/loop

    ./python.exe -m timeit -s 'from fractions import Fraction' 'Fraction(3, 2)'`
  27.7 usec/loop -> 9.32 usec/loop

    ./python.exe -m timeit -s 'from fractions import Fraction; f = Fraction(3, 2)' 'Fraction(f)'
  31.9 usec/loop -> 14.3 usec/loop
........
  r60786 | jeffrey.yasskin | 2008-02-14 08:49:25 +0100 (Thu, 14 Feb 2008) | 5 lines

  Change simple instances (in Fraction) of self.numerator and self.denominator to
  self._numerator and self._denominator. This speeds abs() up from 12.2us to
  10.8us and trunc() from 2.07us to 1.11us. This doesn't change _add and friends
  because they're more complicated.
........

1 files changed, 18 insertions, 0 deletions

diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst
index 1deea64..9ef1230 100644
--- a/Doc/library/fractions.rst
+++ b/Doc/library/fractions.rst
@@ -46,6 +46,24 @@ Rational number class.
    :class:`decimal.Decimal`.
 
 
+.. method:: Fraction.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::
+
+      >>> 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(4503599627370497L, 9007199254740992L)
+      >>> Fraction.from_float(cos(pi/3)).limit_denominator()
+      Fraction(1, 2)
+
+
 .. method:: Fraction.__floor__()
 
    Returns the greatest :class:`int` ``<= self``. Will be accessible