[3.13] 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 1877e72d009e8ce6117e8a07fab2215dcf645bae..b77c5723700bbf806949cfd08a4e16c748fa4804 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.
 
 .. class:: Fraction(numerator=0, denominator=1)
            Fraction(other_fraction)
@@ -25,7 +25,7 @@ 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 ``numerator/denominator``. If *denominator* is ``0``, it
+   with a value equal to ``numerator/denominator``. If *denominator* is zero, 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
@@ -116,7 +116,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.