Add rational.Rational as an implementation of numbers.Rational with infinite
precision. This has been discussed at http://bugs.python.org/issue1682. It's
useful primarily for teaching, but it also demonstrates how to implement a
member of the numeric tower, including fallbacks for mixed-mode arithmetic.
I expect to write a couple more patches in this area:
* Rational.from_decimal()
* Rational.trim/approximate() (maybe with different names)
* Maybe remove the parentheses from Rational.__str__()
* Maybe rename one of the Rational classes
* Maybe make Rational('3/2') work.
diff --git a/Doc/library/rational.rst b/Doc/library/rational.rst
new file mode 100644
index 0000000..dd18305
--- /dev/null
+++ b/Doc/library/rational.rst
@@ -0,0 +1,65 @@
+
+:mod:`rational` --- Rational numbers
+====================================
+
+.. module:: rational
+ :synopsis: Rational numbers.
+.. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
+.. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
+.. versionadded:: 2.6
+
+
+The :mod:`rational` module defines an immutable, infinite-precision
+Rational number class.
+
+
+.. class:: Rational(numerator=0, denominator=1)
+ Rational(other_rational)
+
+ The first version requires that *numerator* and *denominator* are
+ instances of :class:`numbers.Integral` and returns a new
+ ``Rational`` representing ``numerator/denominator``. If
+ *denominator* is :const:`0`, raises a :exc:`ZeroDivisionError`. The
+ second version requires that *other_rational* is an instance of
+ :class:`numbers.Rational` and returns an instance of
+ :class:`Rational` with the same value.
+
+ Implements all of the methods and operations from
+ :class:`numbers.Rational` and is hashable.
+
+
+.. method:: Rational.from_float(flt)
+
+ This classmethod constructs a :class:`Rational` representing the
+ exact value of *flt*, which must be a :class:`float`. Beware that
+ ``Rational.from_float(0.3)`` is not the same value as ``Rational(3,
+ 10)``
+
+
+.. method:: Rational.__floor__()
+
+ Returns the greatest :class:`int` ``<= self``. Will be accessible
+ through :func:`math.floor` in Py3k.
+
+
+.. method:: Rational.__ceil__()
+
+ Returns the least :class:`int` ``>= self``. Will be accessible
+ through :func:`math.ceil` in Py3k.
+
+
+.. method:: Rational.__round__()
+ Rational.__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 ``Rational(1, 10**ndigits)`` (logically, if
+ ``ndigits`` is negative), again rounding half toward even. Will be
+ accessible through :func:`round` in Py3k.
+
+
+.. seealso::
+
+ Module :mod:`numbers`
+ The abstract base classes making up the numeric tower.
+