bpo-26680: Incorporate is_integer in all built-in and standard library numeric types (GH-6121)

* bpo-26680: Adds support for int.is_integer() for compatibility with float.is_integer().

The int.is_integer() method always returns True.

* bpo-26680: Adds a test to ensure that False.is_integer() and True.is_integer() are always True.

* bpo-26680: Adds Real.is_integer() with a trivial implementation using conversion to int.

This default implementation is intended to reduce the workload for subclass
implementers. It is not robust in the presence of infinities or NaNs and
may have suboptimal performance for other types.

* bpo-26680: Adds Rational.is_integer which returns True if the denominator is one.

This implementation assumes the Rational is represented in it's
lowest form, as required by the class docstring.

* bpo-26680: Adds Integral.is_integer which always returns True.

* bpo-26680: Adds tests for Fraction.is_integer called as an instance method.

The tests for the Rational abstract base class use an unbound
method to sidestep the inability to directly instantiate Rational.
These tests check that everything works correct as an instance method.

* bpo-26680: Updates documentation for Real.is_integer and built-ins int and float.

The call x.is_integer() is now listed in the table of operations
which apply to all numeric types except complex, with a reference
to the full documentation for Real.is_integer().  Mention of
is_integer() has been removed from the section 'Additional Methods
on Float'.

The documentation for Real.is_integer() describes its purpose, and
mentions that it should be overridden for performance reasons, or
to handle special values like NaN.

* bpo-26680: Adds Decimal.is_integer to the Python and C implementations.

The C implementation of Decimal already implements and uses
mpd_isinteger internally, we just expose the existing function to
Python.

The Python implementation uses internal conversion to integer
using to_integral_value().

In both cases, the corresponding context methods are also
implemented.

Tests and documentation are included.

* bpo-26680: Updates the ACKS file.

* bpo-26680: NEWS entries for int, the numeric ABCs and Decimal.

Co-authored-by: Robert Smallshire <rob@sixty-north.com>

2 files changed, 14 insertions, 5 deletions

diff --git a/Modules/_decimal/_decimal.c b/Modules/_decimal/_decimal.c
index e7c44ac..5200b1a 100644
--- a/Modules/_decimal/_decimal.c
+++ b/Modules/_decimal/_decimal.c
@@ -4138,6 +4138,7 @@ Dec_BoolFunc(mpd_isqnan)
 Dec_BoolFunc(mpd_issnan)
 Dec_BoolFunc(mpd_issigned)
 Dec_BoolFunc(mpd_iszero)
+Dec_BoolFunc(mpd_isinteger)
 
 /* Boolean functions, optional context arg */
 Dec_BoolFuncVA(mpd_isnormal)
@@ -4772,6 +4773,7 @@ static PyMethodDef dec_methods [] =
   { "is_snan", dec_mpd_issnan, METH_NOARGS, doc_is_snan },
   { "is_signed", dec_mpd_issigned, METH_NOARGS, doc_is_signed },
   { "is_zero", dec_mpd_iszero, METH_NOARGS, doc_is_zero },
+  { "is_integer", dec_mpd_isinteger, METH_NOARGS, doc_is_integer},
 
   /* Boolean functions, optional context arg */
   { "is_normal", (PyCFunction)(void(*)(void))dec_mpd_isnormal, METH_VARARGS|METH_KEYWORDS, doc_is_normal },
@@ -5183,6 +5185,7 @@ DecCtx_BoolFunc_NO_CTX(mpd_isqnan)
 DecCtx_BoolFunc_NO_CTX(mpd_issigned)
 DecCtx_BoolFunc_NO_CTX(mpd_issnan)
 DecCtx_BoolFunc_NO_CTX(mpd_iszero)
+DecCtx_BoolFunc_NO_CTX(mpd_isinteger)
 
 static PyObject *
 ctx_iscanonical(PyObject *context UNUSED, PyObject *v)
@@ -5464,6 +5467,7 @@ static PyMethodDef context_methods [] =
   { "is_snan", ctx_mpd_issnan, METH_O, doc_ctx_is_snan },
   { "is_subnormal", ctx_mpd_issubnormal, METH_O, doc_ctx_is_subnormal },
   { "is_zero", ctx_mpd_iszero, METH_O, doc_ctx_is_zero },
+  { "is_integer", ctx_mpd_isinteger, METH_O, doc_ctx_is_integer },
 
   /* Functions with a single decimal argument */
   { "_apply", PyDecContext_Apply, METH_O, NULL }, /* alias for apply */
@@ -6097,5 +6101,3 @@ error:
 
     return NULL; /* GCOV_NOT_REACHED */
 }
-
-
diff --git a/Modules/_decimal/docstrings.h b/Modules/_decimal/docstrings.h
index f7fd6e7..bd602ab 100644
--- a/Modules/_decimal/docstrings.h
+++ b/Modules/_decimal/docstrings.h
@@ -260,6 +260,11 @@ Return True if the argument is a (positive or negative) zero and False\n\
 otherwise.\n\
 \n");
 
+PyDoc_STRVAR(doc_is_integer,
+"is_integer($self, /)\n--\n\n\
+Return True if the argument is finite and integral, otherwise False.\n\
+\n");
+
 PyDoc_STRVAR(doc_ln,
 "ln($self, /, context=None)\n--\n\n\
 Return the natural (base e) logarithm of the operand. The function always\n\
@@ -685,6 +690,11 @@ PyDoc_STRVAR(doc_ctx_is_zero,
 Return True if x is a zero, False otherwise.\n\
 \n");
 
+PyDoc_STRVAR(doc_ctx_is_integer,
+"is_integer($self, x, /)\n--\n\n\
++Return True if x is finite and integral, False otherwise.\n\
++\n");
+
 PyDoc_STRVAR(doc_ctx_ln,
 "ln($self, x, /)\n--\n\n\
 Return the natural (base e) logarithm of x.\n\
@@ -879,6 +889,3 @@ Convert a number to a string using scientific notation.\n\
 
 
 #endif /* DOCSTRINGS_H */
-
-
-