[Python-checkins] gh-101825: Clarify that as_integer_ratio() output is always normalized (#101843)
mdickinson
webhook-mailer at python.org
Mon Feb 27 14:11:39 EST 2023
https://github.com/python/cpython/commit/4624987b296108c2dc1e6e3a24e65d2de7afd451
commit: 4624987b296108c2dc1e6e3a24e65d2de7afd451
branch: main
author: Sergey B Kirpichev <skirpichev at gmail.com>
committer: mdickinson <dickinsm at gmail.com>
date: 2023-02-27T19:11:28Z
summary:
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 at users.noreply.github.com>
Co-authored-by: Mark Dickinson <dickinsm at gmail.com>
files:
M Doc/library/fractions.rst
M Doc/library/stdtypes.rst
M Lib/fractions.py
M Objects/clinic/floatobject.c.h
M Objects/clinic/longobject.c.h
M Objects/floatobject.c
M Objects/longobject.c
diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst
index c61bbac892e0..fe2e8ab655ed 100644
--- 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 41947d66c151..1240f80b0f11 100644
--- 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 f718b35639be..c95db0730e5b 100644
--- a/Lib/fractions.py
+++ b/Lib/fractions.py
@@ -331,10 +331,9 @@ def is_integer(self):
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 6bc25a0a409f..a99fd74e4b62 100644
--- 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 206bffdd086a..c26ceafbc2be 100644
--- 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 912b742f797d..d641311f1126 100644
--- 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 8293f133bed2..51655cd0bad9 100644
--- 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);
More information about the Python-checkins
mailing list