bpo-44977: Deprecate delegation of int to __trunc__ (GH-31031)

Calling int(a) when type(a) implements __trunc__ but not __int__
or __index__ now raises a DeprecationWarning.

Doc/library/functions.rst

@@ -891,6 +891,9 @@ are always available.  They are listed here in alphabetical order.
    .. versionchanged:: 3.8
       Falls back to :meth:`__index__` if :meth:`__int__` is not defined.
 
+   .. versionchanged:: 3.11
+      The delegation to :meth:`__trunc__` is deprecated.
+
 
 .. function:: isinstance(object, classinfo)
 

Doc/reference/datamodel.rst

@@ -2760,6 +2760,9 @@ left undefined.
    The built-in function :func:`int` falls back to :meth:`__trunc__` if neither
    :meth:`__int__` nor :meth:`__index__` is defined.
 
+   .. versionchanged:: 3.11
+      The delegation of :func:`int` to :meth:`__trunc__` is deprecated.
+
 
 .. _context-managers:
 

Doc/whatsnew/3.11.rst

@@ -458,6 +458,11 @@ Deprecated
   as deprecated, its docstring is now corrected).
   (Contributed by Hugo van Kemenade in :issue:`45837`.)
 
+* The delegation of :func:`int` to :meth:`__trunc__` is now deprecated. Calling
+  ``int(a)`` when ``type(a)`` implements :meth:`__trunc__` but not
+  :meth:`__int__` or :meth:`__index__` now raises a :exc:`DeprecationWarning`.
+  (Contributed by Zackery Spytz in :issue:`44977`.)
+
 * The following have been deprecated in :mod:`configparser` since Python 3.2.
   Their deprecation warnings have now been updated to note they will removed in
   Python 3.12:
@@ -468,6 +473,7 @@ Deprecated
 
   (Contributed by Hugo van Kemenade in :issue:`45173`.)
 
+
 Removed
 =======
 

Lib/test/test_descr.py

@@ -2061,7 +2061,6 @@ order (MRO) for bases """
             ("__format__", format, format_impl, set(), {}),
             ("__floor__", math.floor, zero, set(), {}),
             ("__trunc__", math.trunc, zero, set(), {}),
-            ("__trunc__", int, zero, set(), {}),
             ("__ceil__", math.ceil, zero, set(), {}),
             ("__dir__", dir, empty_seq, set(), {}),
             ("__round__", round, zero, set(), {}),

Lib/test/test_int.py

@@ -369,12 +369,14 @@ class IntTestCases(unittest.TestCase):
             class JustTrunc(base):
                 def __trunc__(self):
                     return 42
+            with self.assertWarns(DeprecationWarning):
                 self.assertEqual(int(JustTrunc()), 42)
 
             class ExceptionalTrunc(base):
                 def __trunc__(self):
                     1 / 0
-            with self.assertRaises(ZeroDivisionError):
+            with self.assertRaises(ZeroDivisionError), \
+                 self.assertWarns(DeprecationWarning):
                 int(ExceptionalTrunc())
 
             for trunc_result_base in (object, Classic):
@@ -385,6 +387,7 @@ class IntTestCases(unittest.TestCase):
                 class TruncReturnsNonInt(base):
                     def __trunc__(self):
                         return Index()
+                with self.assertWarns(DeprecationWarning):
                     self.assertEqual(int(TruncReturnsNonInt()), 42)
 
                 class Intable(trunc_result_base):
@@ -394,6 +397,7 @@ class IntTestCases(unittest.TestCase):
                 class TruncReturnsNonIndex(base):
                     def __trunc__(self):
                         return Intable()
+                with self.assertWarns(DeprecationWarning):
                     self.assertEqual(int(TruncReturnsNonInt()), 42)
 
                 class NonIntegral(trunc_result_base):
@@ -405,6 +409,7 @@ class IntTestCases(unittest.TestCase):
                     def __trunc__(self):
                         return NonIntegral()
                 try:
+                    with self.assertWarns(DeprecationWarning):
                         int(TruncReturnsNonIntegral())
                 except TypeError as e:
                     self.assertEqual(str(e),
@@ -423,7 +428,8 @@ class IntTestCases(unittest.TestCase):
                     def __trunc__(self):
                         return BadInt()
 
-                with self.assertRaises(TypeError):
+                with self.assertRaises(TypeError), \
+                     self.assertWarns(DeprecationWarning):
                     int(TruncReturnsBadInt())
 
     def test_int_subclass_with_index(self):
@@ -517,12 +523,15 @@ class IntTestCases(unittest.TestCase):
         self.assertIs(type(n), int)
 
         bad_int = TruncReturnsBadInt()
+        with self.assertWarns(DeprecationWarning):
             self.assertRaises(TypeError, int, bad_int)
 
         good_int = TruncReturnsIntSubclass()
+        with self.assertWarns(DeprecationWarning):
             n = int(good_int)
         self.assertEqual(n, 1)
         self.assertIs(type(n), int)
+        with self.assertWarns(DeprecationWarning):
             n = IntSubclass(good_int)
         self.assertEqual(n, 1)
         self.assertIs(type(n), IntSubclass)

Lib/test/test_long.py

@@ -392,6 +392,7 @@ class LongTest(unittest.TestCase):
                 return 42
             def __trunc__(self):
                 return 1729
+        with self.assertWarns(DeprecationWarning):
             self.assertEqual(int(LongTrunc()), 1729)
 
     def check_float_conversion(self, n):

Misc/NEWS.d/next/Core and Builtins/2022-01-30-18-23-08.bpo-44977.BQV_zS.rst

@@ -0,0 +1,3 @@
+The delegation of :func:`int` to :meth:`__trunc__` is now deprecated.
+Calling ``int(a)`` when ``type(a)`` implements :meth:`__trunc__` but not
+:meth:`__int__` or :meth:`__index__` now raises a :exc:`DeprecationWarning`.

Objects/abstract.c

@@ -1564,6 +1564,11 @@ PyNumber_Long(PyObject *o)
     }
     trunc_func = _PyObject_LookupSpecial(o, &PyId___trunc__);
     if (trunc_func) {
+        if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                "The delegation of int() to __trunc__ is deprecated.", 1)) {
+            Py_DECREF(trunc_func);
+            return NULL;
+        }
         result = _PyObject_CallNoArgs(trunc_func);
         Py_DECREF(trunc_func);
         if (result == NULL || PyLong_CheckExact(result)) {