gh-101825: Clarify that as_integer_ratio() output is always normalized (#101843)

Make docstrings for `as_integer_ratio` consistent across types, and document that
the returned pair is always normalized (coprime integers, with positive denominator).

---------

Co-authored-by: Owain Davies <116417456+OTheDev@users.noreply.github.com>
Co-authored-by: Mark Dickinson <dickinsm@gmail.com>

diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst
index c61bbac892e0e43e6388028b1d52bdb5a11dbcb5..fe2e8ab655edf8ac10fdda63109fec22c77a9070 100644 (file)
--- a/Doc/library/fractions.rst
+++ b/Doc/library/fractions.rst
@@ -118,7 +118,8 @@ another rational number, or from a string.
    .. method:: as_integer_ratio()
 
       Return a tuple of two integers, whose ratio is equal
-      to the Fraction and with a positive denominator.
+      to the original Fraction.  The ratio is in lowest terms
+      and has a positive denominator.
 
       .. versionadded:: 3.8
 

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 41947d66c1513461dc8284066c009b6e019ee209..1240f80b0f11f022742160ab3a894236baea2c93 100644 (file)
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -602,8 +602,8 @@ class`. In addition, it provides a few more methods:
 
 .. method:: int.as_integer_ratio()
 
-   Return a pair of integers whose ratio is exactly equal to the original
-   integer and with a positive denominator. The integer ratio of integers
+   Return a pair of integers whose ratio is equal to the original
+   integer and has a positive denominator.  The integer ratio of integers
    (whole numbers) is always the integer as the numerator and ``1`` as the
    denominator.
 
@@ -624,7 +624,7 @@ class`. float also has the following additional methods.
 .. method:: float.as_integer_ratio()
 
    Return a pair of integers whose ratio is exactly equal to the
-   original float and with a positive denominator.  Raises
+   original float. The ratio is in lowest terms and has a positive denominator.  Raises
    :exc:`OverflowError` on infinities and a :exc:`ValueError` on
    NaNs.
 

diff --git a/Lib/fractions.py b/Lib/fractions.py
index f718b35639beee0b8f05ddf72b5974ad3f672cf0..c95db0730e5b6d2397fe7722681a70e71b6fc472 100644 (file)
--- a/Lib/fractions.py
+++ b/Lib/fractions.py
@@ -331,10 +331,9 @@ class Fraction(numbers.Rational):
         return self._denominator == 1
 
     def as_integer_ratio(self):
-        """Return the integer ratio as a tuple.
+        """Return a pair of integers, whose ratio is equal to the original Fraction.
 
-        Return a tuple of two integers, whose ratio is equal to the
-        Fraction and with a positive denominator.
+        The ratio is in lowest terms and has a positive denominator.
         """
         return (self._numerator, self._denominator)
 

diff --git a/Objects/clinic/floatobject.c.h b/Objects/clinic/floatobject.c.h
index 6bc25a0a409f97f7d9107cd4a9160fca622fe423..a99fd74e4b621bb7ce2ffbdcb274d4667d4429c2 100644 (file)
--- a/Objects/clinic/floatobject.c.h
+++ b/Objects/clinic/floatobject.c.h
@@ -173,12 +173,10 @@ PyDoc_STRVAR(float_as_integer_ratio__doc__,
 "as_integer_ratio($self, /)\n"
 "--\n"
 "\n"
-"Return integer ratio.\n"
+"Return a pair of integers, whose ratio is exactly equal to the original float.\n"
 "\n"
-"Return a pair of integers, whose ratio is exactly equal to the original float\n"
-"and with a positive denominator.\n"
-"\n"
-"Raise OverflowError on infinities and a ValueError on NaNs.\n"
+"The ratio is in lowest terms and has a positive denominator.  Raise\n"
+"OverflowError on infinities and a ValueError on NaNs.\n"
 "\n"
 ">>> (10.0).as_integer_ratio()\n"
 "(10, 1)\n"
@@ -327,4 +325,4 @@ float___format__(PyObject *self, PyObject *arg)
 exit:
     return return_value;
 }
-/*[clinic end generated code: output=74bc91bb44014df9 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=ea329577074911b9 input=a9049054013a1b77]*/

diff --git a/Objects/clinic/longobject.c.h b/Objects/clinic/longobject.c.h
index 206bffdd086a5c8ba7a32601b6a9e52d50073fa5..c26ceafbc2be0dfa3bbb8258305da948be824356 100644 (file)
--- a/Objects/clinic/longobject.c.h
+++ b/Objects/clinic/longobject.c.h
@@ -231,10 +231,9 @@ PyDoc_STRVAR(int_as_integer_ratio__doc__,
 "as_integer_ratio($self, /)\n"
 "--\n"
 "\n"
-"Return integer ratio.\n"
+"Return a pair of integers, whose ratio is equal to the original int.\n"
 "\n"
-"Return a pair of integers, whose ratio is exactly equal to the original int\n"
-"and with a positive denominator.\n"
+"The ratio is in lowest terms and has a positive denominator.\n"
 "\n"
 ">>> (10).as_integer_ratio()\n"
 "(10, 1)\n"
@@ -485,4 +484,4 @@ int_is_integer(PyObject *self, PyObject *Py_UNUSED(ignored))
 {
     return int_is_integer_impl(self);
 }
-/*[clinic end generated code: output=e518fe2b5d519322 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=cfdf35d916158d4f input=a9049054013a1b77]*/

diff --git a/Objects/floatobject.c b/Objects/floatobject.c
index 912b742f797d249b1bcde6348903bbc8e7e3e7d5..d641311f1126cd25ed4deae9f130b937cc2a35cd 100644 (file)
--- a/Objects/floatobject.c
+++ b/Objects/floatobject.c
@@ -1546,12 +1546,10 @@ float_fromhex(PyTypeObject *type, PyObject *string)
 /*[clinic input]
 float.as_integer_ratio
 
-Return integer ratio.
+Return a pair of integers, whose ratio is exactly equal to the original float.
 
-Return a pair of integers, whose ratio is exactly equal to the original float
-and with a positive denominator.
-
-Raise OverflowError on infinities and a ValueError on NaNs.
+The ratio is in lowest terms and has a positive denominator.  Raise
+OverflowError on infinities and a ValueError on NaNs.
 
 >>> (10.0).as_integer_ratio()
 (10, 1)
@@ -1563,7 +1561,7 @@ Raise OverflowError on infinities and a ValueError on NaNs.
 
 static PyObject *
 float_as_integer_ratio_impl(PyObject *self)
-/*[clinic end generated code: output=65f25f0d8d30a712 input=e21d08b4630c2e44]*/
+/*[clinic end generated code: output=65f25f0d8d30a712 input=d5ba7765655d75bd]*/
 {
     double self_double;
     double float_part;

diff --git a/Objects/longobject.c b/Objects/longobject.c
index 8293f133bed213551971b2b37e30a57fadb32207..51655cd0bad9ecc3704a015ca365afe2651096c5 100644 (file)
--- a/Objects/longobject.c
+++ b/Objects/longobject.c
@@ -6020,10 +6020,9 @@ int_bit_count_impl(PyObject *self)
 /*[clinic input]
 int.as_integer_ratio
 
-Return integer ratio.
+Return a pair of integers, whose ratio is equal to the original int.
 
-Return a pair of integers, whose ratio is exactly equal to the original int
-and with a positive denominator.
+The ratio is in lowest terms and has a positive denominator.
 
 >>> (10).as_integer_ratio()
 (10, 1)
@@ -6035,7 +6034,7 @@ and with a positive denominator.
 
 static PyObject *
 int_as_integer_ratio_impl(PyObject *self)
-/*[clinic end generated code: output=e60803ae1cc8621a input=55ce3058e15de393]*/
+/*[clinic end generated code: output=e60803ae1cc8621a input=384ff1766634bec2]*/
 {
     PyObject *ratio_tuple;
     PyObject *numerator = long_long(self);