Issue 36048: Deprecate implicit truncating when convert Python numbers to C integers: use __index__, not __int__

Currently, C API functions that convert a Python number to a C integer like PyLong_AsLong() and argument parsing functions like PyArg_ParseTuple() with integer converting format units like 'i' use the __int__() special method for converting objects which are not instances of int or int subclasses. This leads to dropping the fractional part if the object is not integral number (e.g. float, Decimal or Fraction). In some cases, there is a special check for float, but it does not prevent truncation for Decimal, Fraction and other numeric types.

For example:

>>> chr(65.5)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: integer argument expected, got float
>>> chr(Decimal('65.5'))
'A'

The proposed PR makes all these functions using __index__() instead of __int__() if available and emit a deprecation warning when __int__() is used for implicit conversion to a C integer.

>>> chr(Decimal('65.5'))
<stdin>:1: DeprecationWarning: an integer is required (got type decimal.Decimal)
'A'

In future versions only __index__() will be used for the implicit conversion, and __int__() will be used only in the int constructor.

Numerous explicit calls of PyNumber_Index() which are used to protect from passing non-integral types to PyLong_AsLong() and like can be removed after the end of the deprecation period. I tried to mark calls which can be removed with comments, but virtually all calls can be removed.

I like the idea. Rejecting float but not decimal.Decimal is inconsistent. __index__ has been written explicitly for this purpose.

I'm always confused and lost in subtle details of the Python and C API in how they handle numbers, so I wrote some notes for myself:
https://pythondev.readthedocs.io/numbers.html

Some functions accept only int, others use __int__, others __index__. Some functions silently truncate into 32 or 64-bit signed integer. Some other raise a OverflowError or ValueError...

See also bpo-34423: "Overflow when casting from double to time_t, and_PyTime_t" or "How to reduce precision loss when converting arbitrary number to int or float?".

I am not sure what to with the int constructor. Should it try __index__ before __int__? Or just make __index__ without __int__ setting the nb_int slot as was proposed by Nick in issue33039?

> I am not sure what to with the int constructor. Should it try __index__ before __int__? Or just make __index__ without __int__ setting the nb_int slot as was proposed by Nick in issue33039?

Shouldn't it try only __int__ since this will default to __index__ once #33039 is closed?

New changeset 6a44f6eef3d0958d88882347190b3e2d1222c2e9 by Serhiy Storchaka in branch 'master':
bpo-36048: Use __index__() instead of __int__() for implicit conversion if available. (GH-11952)
https://github.com/python/cpython/commit/6a44f6eef3d0958d88882347190b3e2d1222c2e9

Relevant NumPy issue: https://github.com/numpy/numpy/issues/13412

Serhiy: any thoughts about what version should be targeted for eventual removal of the functionality deprecated in this PR? 3.10?

> Serhiy: any thoughts about what version should be targeted for eventual removal of the functionality deprecated in this PR? 3.10?

IMHO it should be done at the *very beginning* of a release cycle. Python 3.9.0 alpha 1 *and* alpha 2 versions have already been released. It's too late for the 3.9 cycle.

I'm fine with 3.10.