gh-122450: Expand documentation for ``Rational`` and ``Fraction`` (#136800)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst
index 8796056b4b8722c4ec91d89c8110b96d4a49d7e4..d6d1c7a461c51cd953785d212e10eeae5ecba083 100644 (file)
--- a/Doc/library/fractions.rst
+++ b/Doc/library/fractions.rst
@@ -14,8 +14,8 @@
 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.
+A Fraction instance can be constructed from a pair of rational numbers, from
+a single number, or from a string.
 
 .. index:: single: as_integer_ratio()
 
@@ -25,8 +25,8 @@ another rational number, or from a string.
 
    The first version requires that *numerator* and *denominator* are instances
    of :class:`numbers.Rational` and returns a new :class:`Fraction` instance
-   with value equal to ``numerator/denominator`` where the denominator is positive.
-   If *denominator* is ``0``, it raises a :exc:`ZeroDivisionError`.
+   with a value equal to ``numerator/denominator``.
+   If *denominator* is zero, 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
@@ -125,7 +125,8 @@ another rational number, or from a string.
 
    .. attribute:: denominator
 
-      Denominator of the Fraction in lowest term.
+      Denominator of the Fraction in lowest terms.
+      Guaranteed to be positive.
 
 
    .. method:: as_integer_ratio()

diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst
index 681d0b76f2a14b70520ba84324a8b06eab74c074..57b35017072c97eabcda93633f2a44cf9d31884f 100644 (file)
--- a/Doc/library/numbers.rst
+++ b/Doc/library/numbers.rst
@@ -69,11 +69,11 @@ The numeric tower
 
    .. attribute:: numerator
 
-      Abstract.
+      Abstract.  The numerator of this rational number.
 
    .. attribute:: denominator
 
-      Abstract.
+      Abstract.  The denominator of this rational number.
 
 
 .. class:: Integral

diff --git a/Lib/numbers.py b/Lib/numbers.py
index a2913e32cfada76634c2dafaafaccd7e66d64314..37fddb8917727b6b79216e7941c01d3ade7d1a65 100644 (file)
--- a/Lib/numbers.py
+++ b/Lib/numbers.py
@@ -290,18 +290,27 @@ Real.register(float)
 
 
 class Rational(Real):
-    """.numerator and .denominator should be in lowest terms."""
+    """To Real, Rational adds numerator and denominator properties.
+
+    The numerator and denominator values should be in lowest terms,
+    with a positive denominator.
+    """
 
     __slots__ = ()
 
     @property
     @abstractmethod
     def numerator(self):
+        """The numerator of a rational number in lowest terms."""
         raise NotImplementedError
 
     @property
     @abstractmethod
     def denominator(self):
+        """The denominator of a rational number in lowest terms.
+
+        This denominator should be positive.
+        """
         raise NotImplementedError
 
     # Concrete implementation of Real's conversion to float.