From c745d4f65bf8b88b4ad07847292a8ab5300143e4 Mon Sep 17 00:00:00 2001
From: Sergey B Kirpichev <skirpichev@gmail.com>
Date: Mon, 4 Aug 2025 05:15:59 +0300
Subject: [PATCH] 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>
(cherry picked from commit b266fbc9ecd25d08ab572ecb91913e86b6ddc75e)
---
 Doc/library/fractions.rst |  9 +++++----
 Doc/library/numbers.rst   |  4 ++--
 Lib/numbers.py            | 11 ++++++++++-
 3 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst
index 1877e72d009e8c..b77c5723700bbf 100644
--- 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 681d0b76f2a14b..57b35017072c97 100644
--- 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 a2913e32cfada7..37fddb8917727b 100644
--- a/Lib/numbers.py
+++ b/Lib/numbers.py
@@ -290,18 +290,27 @@ def conjugate(self):
 
 
 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.