bpo-37999: Fix outdated __int__ and nb_int references in comments (GH-20449)

* Fix outdated __int__ and nb_int references in comments

* Also update C-API documentation

* Add back missing 'method' word

* Remove .. deprecated notices

2 files changed, 33 insertions, 38 deletions

diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index c5c2aa6..a7bd43d 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -129,9 +129,8 @@ 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:`__index__` or
-   :meth:`__int__` method (if present) to convert it to a
-   :c:type:`PyLongObject`.
+   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` 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`.
@@ -141,16 +140,15 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionchanged:: 3.8
       Use :meth:`__index__` if available.
 
-   .. deprecated:: 3.8
-      Using :meth:`__int__` is deprecated.
+   .. versionchanged:: 3.10
+      This function will no longer use :meth:`__int__`.
 
 
 .. 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:`__index__` or
-   :meth:`__int__` method (if present) to convert it to a
-   :c:type:`PyLongObject`.
+   instance of :c:type:`PyLongObject`, first call its :meth:`__index__`
+   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
@@ -162,8 +160,8 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionchanged:: 3.8
       Use :meth:`__index__` if available.
 
-   .. deprecated:: 3.8
-      Using :meth:`__int__` is deprecated.
+   .. versionchanged:: 3.10
+      This function will no longer use :meth:`__int__`.
 
 
 .. c:function:: long long PyLong_AsLongLong(PyObject *obj)
@@ -172,9 +170,8 @@ 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:`__index__` or
-   :meth:`__int__` method (if present) to convert it to a
-   :c:type:`PyLongObject`.
+   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` 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 long`.
@@ -184,16 +181,15 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionchanged:: 3.8
       Use :meth:`__index__` if available.
 
-   .. deprecated:: 3.8
-      Using :meth:`__int__` is deprecated.
+   .. versionchanged:: 3.10
+      This function will no longer use :meth:`__int__`.
 
 
 .. 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:`__index__` or
-   :meth:`__int__` method (if present) to convert it to a
-   :c:type:`PyLongObject`.
+   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
+   (if present) to convert it to a :c:type:`PyLongObject`.
 
    If the value of *obj* is greater than :const:`LLONG_MAX` or less than
    :const:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
@@ -207,8 +203,8 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionchanged:: 3.8
       Use :meth:`__index__` if available.
 
-   .. deprecated:: 3.8
-      Using :meth:`__int__` is deprecated.
+   .. versionchanged:: 3.10
+      This function will no longer use :meth:`__int__`.
 
 
 .. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
@@ -278,10 +274,9 @@ 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:`__index__` or :meth:`__int__` method (if present) to convert
-   it to a :c:type:`PyLongObject`.
+   Return a C :c:type:`unsigned long` representation of *obj*.  If *obj* is not
+   an instance of :c:type:`PyLongObject`, first call its :meth:`__index__`
+   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``.
@@ -292,16 +287,16 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionchanged:: 3.8
       Use :meth:`__index__` if available.
 
-   .. deprecated:: 3.8
-      Using :meth:`__int__` is deprecated.
+   .. versionchanged:: 3.10
+      This function will no longer use :meth:`__int__`.
 
 
 .. 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:`__index__` or :meth:`__int__` method (if present) to convert
-   it to a :c:type:`PyLongObject`.
+   :meth:`__index__` 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 ``ULLONG_MAX + 1``.
@@ -312,8 +307,8 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionchanged:: 3.8
       Use :meth:`__index__` if available.
 
-   .. deprecated:: 3.8
-      Using :meth:`__int__` is deprecated.
+   .. versionchanged:: 3.10
+      This function will no longer use :meth:`__int__`.
 
 
 .. c:function:: double PyLong_AsDouble(PyObject *pylong)
diff --git a/Objects/longobject.c b/Objects/longobject.c
index a409948..e040d6c 100644
--- a/Objects/longobject.c
+++ b/Objects/longobject.c
@@ -363,7 +363,7 @@ PyLong_FromDouble(double dval)
 #define PY_ABS_LONG_MIN         (0-(unsigned long)LONG_MIN)
 #define PY_ABS_SSIZE_T_MIN      (0-(size_t)PY_SSIZE_T_MIN)
 
-/* Get a C long int from an int object or any object that has an __int__
+/* Get a C long int from an int object or any object that has an __index__
    method.
 
    On overflow, return -1 and set *overflow to 1 or -1 depending on the sign of
@@ -382,7 +382,7 @@ PyLong_AsLongAndOverflow(PyObject *vv, int *overflow)
     long res;
     Py_ssize_t i;
     int sign;
-    int do_decref = 0; /* if nb_int was called */
+    int do_decref = 0; /* if PyNumber_Index was called */
 
     *overflow = 0;
     if (vv == NULL) {
@@ -449,7 +449,7 @@ PyLong_AsLongAndOverflow(PyObject *vv, int *overflow)
     return res;
 }
 
-/* Get a C long int from an int object or any object that has an __int__
+/* Get a C long int from an int object or any object that has an __index__
    method.  Return -1 and set an error if overflow occurs. */
 
 long
@@ -466,7 +466,7 @@ PyLong_AsLong(PyObject *obj)
     return result;
 }
 
-/* Get a C int from an int object or any object that has an __int__
+/* Get a C int from an int object or any object that has an __index__
    method.  Return -1 and set an error if overflow occurs. */
 
 int
@@ -1113,7 +1113,7 @@ PyLong_FromSsize_t(Py_ssize_t ival)
 }
 
 /* Get a C long long int from an int object or any object that has an
-   __int__ method.  Return -1 and set an error if overflow occurs. */
+   __index__ method.  Return -1 and set an error if overflow occurs. */
 
 long long
 PyLong_AsLongLong(PyObject *vv)
@@ -1121,7 +1121,7 @@ PyLong_AsLongLong(PyObject *vv)
     PyLongObject *v;
     long long bytes;
     int res;
-    int do_decref = 0; /* if nb_int was called */
+    int do_decref = 0; /* if PyNumber_Index was called */
 
     if (vv == NULL) {
         PyErr_BadInternalCall();
@@ -1257,7 +1257,7 @@ PyLong_AsUnsignedLongLongMask(PyObject *op)
 }
 
 /* Get a C long long int from an int object or any object that has an
-   __int__ method.
+   __index__ method.
 
    On overflow, return -1 and set *overflow to 1 or -1 depending on the sign of
    the result.  Otherwise *overflow is 0.
@@ -1275,7 +1275,7 @@ PyLong_AsLongLongAndOverflow(PyObject *vv, int *overflow)
     long long res;
     Py_ssize_t i;
     int sign;
-    int do_decref = 0; /* if nb_int was called */
+    int do_decref = 0; /* if PyNumber_Index was called */
 
     *overflow = 0;
     if (vv == NULL) {