https://github.com/python/cpython/commit/b266fbc9ecd25d08ab572ecb91913e86b6ddc75e
commit: b266fbc9ecd25d08ab572ecb91913e86b6ddc75e
branch: main
author: Sergey B Kirpichev <skirpic...@gmail.com>
committer: AA-Turner <9087854+aa-tur...@users.noreply.github.com>
date: 2025-08-04T02:15:59Z
summary:
gh-122450: Expand documentation for ``Rational`` and ``Fraction`` (#136800)
Co-authored-by: Adam Turner <9087854+aa-tur...@users.noreply.github.com>
Co-authored-by: Serhiy Storchaka <storch...@gmail.com>
files:
M Doc/library/fractions.rst
M Doc/library/numbers.rst
M Lib/numbers.py
diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst
index 8796056b4b8722..d6d1c7a461c51c 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.
.. 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 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.
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: arch...@mail-archive.com
