bpo-36048: Use __index__() instead of __int__() for implicit conversion if available. (GH-11952)

Deprecate using the __int__() method in implicit conversions of Python
numbers to C integers.

2 files changed, 57 insertions, 12 deletions

diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 5b1f386..8093f4b 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -131,20 +131,28 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
       single: OverflowError (built-in exception)
 
    Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
-   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
-   (if present) to convert it to a :c:type:`PyLongObject`.
+   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
+   :meth:`__int__` method (if present) to convert it to a
+   :c:type:`PyLongObject`.
 
    Raise :exc:`OverflowError` if the value of *obj* is out of range for a
    :c:type:`long`.
 
    Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
+   .. versionchanged:: 3.8
+      Use :meth:`__index__` if available.
+
+   .. deprecated:: 3.8
+      Using :meth:`__int__` is deprecated.
+
 
 .. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
 
    Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
-   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
-   (if present) to convert it to a :c:type:`PyLongObject`.
+   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
+   :meth:`__int__` method (if present) to convert it to a
+   :c:type:`PyLongObject`.
 
    If the value of *obj* is greater than :const:`LONG_MAX` or less than
    :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
@@ -153,6 +161,12 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
    Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
+   .. versionchanged:: 3.8
+      Use :meth:`__index__` if available.
+
+   .. deprecated:: 3.8
+      Using :meth:`__int__` is deprecated.
+
 
 .. c:function:: long long PyLong_AsLongLong(PyObject *obj)
 
@@ -160,20 +174,28 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
       single: OverflowError (built-in exception)
 
    Return a C :c:type:`long long` representation of *obj*.  If *obj* is not an
-   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
-   (if present) to convert it to a :c:type:`PyLongObject`.
+   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
+   :meth:`__int__` method (if present) to convert it to a
+   :c:type:`PyLongObject`.
 
    Raise :exc:`OverflowError` if the value of *obj* is out of range for a
    :c:type:`long`.
 
    Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
+   .. versionchanged:: 3.8
+      Use :meth:`__index__` if available.
+
+   .. deprecated:: 3.8
+      Using :meth:`__int__` is deprecated.
+
 
 .. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
 
    Return a C :c:type:`long long` representation of *obj*.  If *obj* is not an
-   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
-   (if present) to convert it to a :c:type:`PyLongObject`.
+   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
+   :meth:`__int__` method (if present) to convert it to a
+   :c:type:`PyLongObject`.
 
    If the value of *obj* is greater than :const:`PY_LLONG_MAX` or less than
    :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
@@ -184,6 +206,12 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
    .. versionadded:: 3.2
 
+   .. versionchanged:: 3.8
+      Use :meth:`__index__` if available.
+
+   .. deprecated:: 3.8
+      Using :meth:`__int__` is deprecated.
+
 
 .. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
 
@@ -253,26 +281,40 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
 .. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
 
    Return a C :c:type:`unsigned long` representation of *obj*.  If *obj*
-   is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
-   method (if present) to convert it to a :c:type:`PyLongObject`.
+   is not an instance of :c:type:`PyLongObject`, first call its
+   :meth:`__index__` or :meth:`__int__` method (if present) to convert
+   it to a :c:type:`PyLongObject`.
 
    If the value of *obj* is out of range for an :c:type:`unsigned long`,
    return the reduction of that value modulo ``ULONG_MAX + 1``.
 
    Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
+   .. versionchanged:: 3.8
+      Use :meth:`__index__` if available.
+
+   .. deprecated:: 3.8
+      Using :meth:`__int__` is deprecated.
+
 
 .. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
 
    Return a C :c:type:`unsigned long long` representation of *obj*.  If *obj*
-   is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
-   method (if present) to convert it to a :c:type:`PyLongObject`.
+   is not an instance of :c:type:`PyLongObject`, first call its
+   :meth:`__index__` or :meth:`__int__` method (if present) to convert
+   it to a :c:type:`PyLongObject`.
 
    If the value of *obj* is out of range for an :c:type:`unsigned long long`,
    return the reduction of that value modulo ``PY_ULLONG_MAX + 1``.
 
    Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
+   .. versionchanged:: 3.8
+      Use :meth:`__index__` if available.
+
+   .. deprecated:: 3.8
+      Using :meth:`__int__` is deprecated.
+
 
 .. c:function:: double PyLong_AsDouble(PyObject *pylong)
 
diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst
index 296b21c..9fb220b 100644
--- a/Doc/c-api/number.rst
+++ b/Doc/c-api/number.rst
@@ -11,6 +11,9 @@ Number Protocol
    Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.
    This function always succeeds.
 
+   .. versionchanged:: 3.8
+      Returns ``1`` if *o* is an index integer.
+
 
 .. c:function:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)