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>
This commit is contained in:
Sergey B Kirpichev 2023-02-27 22:11:28 +03:00 committed by GitHub
parent 4f3786b761
commit 4624987b29
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 21 additions and 27 deletions

View File

@ -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

View File

@ -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.

View File

@ -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)

View File

@ -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]*/

View File

@ -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]*/

View File

@ -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;

View File

@ -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);