From 762e14c0868567da1267b1cf716f97e1a4efbe1d Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 19 Jul 2025 14:52:06 +0300 Subject: [PATCH 01/11] gh-122450: Expand numbers.Rational docstrings --- Lib/numbers.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Lib/numbers.py b/Lib/numbers.py index a2913e32cfada7..11ecb6226f2909 100644 --- a/Lib/numbers.py +++ b/Lib/numbers.py @@ -290,18 +290,24 @@ def conjugate(self): class Rational(Real): - """.numerator and .denominator should be in lowest terms.""" + """To Real, adds numerator and denominator properties. + + The numerator and denominator values should be in lowest terms with + denominator positive. + """ __slots__ = () @property @abstractmethod def numerator(self): + """The numerator of a rational number in lowest terms.""" raise NotImplementedError @property @abstractmethod def denominator(self): + """The positive denominator of a rational number in lowest terms.""" raise NotImplementedError # Concrete implementation of Real's conversion to float. From 478e414813f6c00d57b917fb3473708b5cbfa537 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 19 Jul 2025 16:30:11 +0300 Subject: [PATCH 02/11] Revert "gh-122450: Indicate that `Fraction` denominators are always positive (#136789)" This reverts commit eb8ac4c85773160a6104abafdea9159f26363a9b. --- Doc/library/fractions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 8796056b4b8722..392b6d40e861fb 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -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 value ``numerator/denominator``. If *denominator* is ``0``, 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 From c3f506af3467d4e63aae491e35cd984f61a80c32 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 19 Jul 2025 16:36:13 +0300 Subject: [PATCH 03/11] Document Ratiomal.numerator/denominator, remove from Fraction docs --- Doc/library/fractions.rst | 9 --------- Doc/library/numbers.rst | 4 ++-- 2 files changed, 2 insertions(+), 11 deletions(-) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 392b6d40e861fb..5468812483315b 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -119,15 +119,6 @@ another rational number, or from a string. The :class:`Fraction` constructor now accepts any objects with the :meth:`!as_integer_ratio` method. - .. attribute:: numerator - - Numerator of the Fraction in lowest term. - - .. attribute:: denominator - - Denominator of the Fraction in lowest term. - - .. method:: as_integer_ratio() Return a tuple of two integers, whose ratio is equal 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 From f2aaed3ee671834a3af93e6860ac42d6dd5e6a6e Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 21 Jul 2025 13:29:02 +0300 Subject: [PATCH 04/11] address review: more vague preable --- Doc/library/fractions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 5468812483315b..8b04059cc7cccb 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 numbers, from +another number, or from a string. .. index:: single: as_integer_ratio() From a8b6ca29faac2d73361cc4542d0c2fb030be5d80 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 21 Jul 2025 13:30:38 +0300 Subject: [PATCH 05/11] address review: 0 -> zero --- Doc/library/fractions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 8b04059cc7cccb..5684bc6db1c45c 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -25,7 +25,7 @@ another 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 value equal to ``numerator/denominator``. If *denominator* is zero, it raises a :exc:`ZeroDivisionError`. The second version requires that *number* is an instance of From 53e8c262f57cea544f7967a0e79c20f75d07f888 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 21 Jul 2025 15:50:31 +0300 Subject: [PATCH 06/11] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Lib/numbers.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Lib/numbers.py b/Lib/numbers.py index 11ecb6226f2909..37fddb8917727b 100644 --- a/Lib/numbers.py +++ b/Lib/numbers.py @@ -290,10 +290,10 @@ def conjugate(self): class Rational(Real): - """To Real, adds numerator and denominator properties. + """To Real, Rational adds numerator and denominator properties. - The numerator and denominator values should be in lowest terms with - denominator positive. + The numerator and denominator values should be in lowest terms, + with a positive denominator. """ __slots__ = () @@ -307,7 +307,10 @@ def numerator(self): @property @abstractmethod def denominator(self): - """The positive denominator of a rational number in lowest terms.""" + """The denominator of a rational number in lowest terms. + + This denominator should be positive. + """ raise NotImplementedError # Concrete implementation of Real's conversion to float. From fb84af4e62106485c9ddb7ebb9209fc2b267dac8 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 21 Jul 2025 16:09:39 +0300 Subject: [PATCH 07/11] address review: restore Fraction.numerator/denominator in docs --- Doc/library/fractions.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 5684bc6db1c45c..57fd48741ed283 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -119,6 +119,15 @@ another number, or from a string. The :class:`Fraction` constructor now accepts any objects with the :meth:`!as_integer_ratio` method. + .. attribute:: numerator + + Numerator of the Fraction in lowest term. + + .. attribute:: denominator + + Denominator of the Fraction in lowest term. Should be positive. + + .. method:: as_integer_ratio() Return a tuple of two integers, whose ratio is equal From 668518d24005cd9b8466071bd93d406d2da0a41a Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Thu, 31 Jul 2025 11:04:54 +0300 Subject: [PATCH 08/11] Update Doc/library/fractions.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/fractions.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 57fd48741ed283..996f7ebb677e53 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -125,7 +125,8 @@ another number, or from a string. .. attribute:: denominator - Denominator of the Fraction in lowest term. Should be positive. + Denominator of the Fraction in lowest terms. + Guaranteed to be positive. .. method:: as_integer_ratio() From b4bdda225f7b3023cbb9b25ff96f7bf45fd094a7 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Thu, 31 Jul 2025 09:14:21 +0100 Subject: [PATCH 09/11] Add an explicit reference to conversion of constructor arguments --- Doc/library/fractions.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 996f7ebb677e53..40761e86ce1caa 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -25,8 +25,10 @@ another 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``. If *denominator* is zero, it - raises a :exc:`ZeroDivisionError`. + with a value equal to ``numerator/denominator``. + The numerator and denominator of this new instance are converted to be in + simplest integral terms, always with a positive 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 From f558851cba1393f1ad89efe2e371c530f35efec0 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Thu, 31 Jul 2025 13:06:03 +0300 Subject: [PATCH 10/11] Update Doc/library/fractions.rst Co-authored-by: Serhiy Storchaka --- Doc/library/fractions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 40761e86ce1caa..21224f5afdd226 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 numbers, from -another 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() From ec9c6f8a5cafc399caf45849927dad2f61e935c8 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 4 Aug 2025 04:50:07 +0300 Subject: [PATCH 11/11] Update Doc/library/fractions.rst --- Doc/library/fractions.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 21224f5afdd226..d6d1c7a461c51c 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -26,8 +26,6 @@ a single 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 a value equal to ``numerator/denominator``. - The numerator and denominator of this new instance are converted to be in - simplest integral terms, always with a positive denominator. If *denominator* is zero, it raises a :exc:`ZeroDivisionError`. The second version requires that *number* is an instance of