Add nb_complex slot to PyNumberMethods (was nb_reserved)

Author: skirpichev

Doc/c-api/typeobj.rst

@@ -276,7 +276,7 @@ sub-slots
    +---------------------------------------------------------+-----------------------------------+---------------+
    | :c:member:`~PyNumberMethods.nb_int`                     | :c:type:`unaryfunc`               | __int__       |
    +---------------------------------------------------------+-----------------------------------+---------------+
-   | :c:member:`~PyNumberMethods.nb_reserved`                | void *                            |               |
+   | :c:member:`~PyNumberMethods.nb_complex`                 | :c:type:`unaryfunc`               | __complex__   |
    +---------------------------------------------------------+-----------------------------------+---------------+
    | :c:member:`~PyNumberMethods.nb_float`                   | :c:type:`unaryfunc`               | __float__     |
    +---------------------------------------------------------+-----------------------------------+---------------+
@@ -2304,7 +2304,7 @@ Number Object Structures
             binaryfunc nb_xor;
             binaryfunc nb_or;
             unaryfunc nb_int;
-            void *nb_reserved;
+            unaryfunc nb_complex;
             unaryfunc nb_float;
 
             binaryfunc nb_inplace_add;
@@ -2338,11 +2338,6 @@ Number Object Structures
       ``Py_NotImplemented``, if another error occurred they must return ``NULL``
       and set an exception.
 
-   .. note::
-
-      The :c:member:`~PyNumberMethods.nb_reserved` field should always be ``NULL``.  It
-      was previously called :c:member:`!nb_long`, and was renamed in
-      Python 3.0.1.
 
 .. c:member:: binaryfunc PyNumberMethods.nb_add
 .. c:member:: binaryfunc PyNumberMethods.nb_subtract
@@ -2361,7 +2356,7 @@ Number Object Structures
 .. c:member:: binaryfunc PyNumberMethods.nb_xor
 .. c:member:: binaryfunc PyNumberMethods.nb_or
 .. c:member:: unaryfunc PyNumberMethods.nb_int
-.. c:member:: void *PyNumberMethods.nb_reserved
+.. c:member:: unaryfunc PyNumberMethods.nb_complex
 .. c:member:: unaryfunc PyNumberMethods.nb_float
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_add
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_subtract

Include/cpython/object.h

@@ -80,7 +80,7 @@ typedef struct {
     binaryfunc nb_xor;
     binaryfunc nb_or;
     unaryfunc nb_int;
-    void *nb_reserved;  /* the slot formerly known as nb_long */
+    unaryfunc nb_complex;  /* the slot formerly known as nb_long */
     unaryfunc nb_float;
 
     binaryfunc nb_inplace_add;

Include/typeslots.h

@@ -94,3 +94,7 @@
 /* New in 3.14 */
 #define Py_tp_token 83
 #endif
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030E0000
+/* New in 3.14 */
+#define Py_nb_complex 84
+#endif

Lib/test/test_capi/test_complex.py

@@ -306,6 +306,16 @@ def test_py_c_abs(self):
 
         self.assertEqual(_py_c_abs(complex(*[DBL_MAX]*2))[1], errno.ERANGE)
 
+    def test_old__complex__(self):
+        old_complex_like = _testcapi.old_complex_like
+
+        x = old_complex_like()
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(complex(x), 1+2j)
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", DeprecationWarning)
+            self.assertRaises(DeprecationWarning, complex, x)
+
 
 if __name__ == "__main__":
     unittest.main()

Lib/test/test_capi/test_number.py

@@ -83,6 +83,7 @@ def test_check(self):
         self.assertTrue(check(0.5))
         self.assertTrue(check(FloatLike.with_val(4.25)))
         self.assertTrue(check(1+2j))
+        self.assertTrue(check(ComplexLike.with_val(1+2j)))
 
         self.assertFalse(check([]))
         self.assertFalse(check("abc"))

Misc/stable_abi.toml

@@ -238,6 +238,8 @@
     added = '3.2'
 [const.Py_nb_float]
     added = '3.2'
+[const.Py_nb_complex]
+    added = '3.14'
 [const.Py_nb_inplace_add]
     added = '3.2'
 [const.Py_nb_inplace_subtract]

Modules/_datetimemodule.c

@@ -3057,7 +3057,7 @@ static PyNumberMethods delta_as_number = {
     0,                                          /*nb_xor*/
     0,                                          /*nb_or*/
     0,                                          /*nb_int*/
-    0,                                          /*nb_reserved*/
+    0,                                          /*nb_complex*/
     0,                                          /*nb_float*/
     0,                                          /*nb_inplace_add*/
     0,                                          /*nb_inplace_subtract*/

Modules/_decimal/_decimal.c

@@ -4841,7 +4841,7 @@ dec_ceil(PyObject *self, PyObject *Py_UNUSED(dummy))
 
 /* __complex__ */
 static PyObject *
-dec_complex(PyObject *self, PyObject *Py_UNUSED(dummy))
+dec_complex(PyObject *self)
 {
     PyObject *f;
     double x;
@@ -5161,7 +5161,6 @@ static PyMethodDef dec_methods [] =
   { "__ceil__", dec_ceil, METH_NOARGS, NULL },
   { "__floor__", dec_floor, METH_NOARGS, NULL },
   { "__trunc__", dec_trunc, METH_NOARGS, NULL },
-  { "__complex__", dec_complex, METH_NOARGS, NULL },
   { "__sizeof__", dec_sizeof, METH_NOARGS, NULL },
 
   { NULL, NULL, 1 }
@@ -5194,6 +5193,7 @@ static PyType_Slot dec_slots[] = {
     {Py_nb_bool, nm_nonzero},
     {Py_nb_int, nm_dec_as_long},
     {Py_nb_float, PyDec_AsFloat},
+    {Py_nb_complex, dec_complex},
     {Py_nb_floor_divide, nm_mpd_qdivint},
     {Py_nb_true_divide, nm_mpd_qdiv},
     {0, NULL},

Modules/_testcapimodule.c

@@ -2684,7 +2684,7 @@ static PyNumberMethods matmulType_as_number = {
     0,                          /* nb_xor */
     0,                          /* nb_or */
     0,                          /* nb_int */
-    0,                          /* nb_reserved */
+    0,                          /* nb_complex */
     0,                          /* nb_float */
     0,                          /* nb_inplace_add */
     0,                          /* nb_inplace_subtract */
@@ -3175,6 +3175,28 @@ create_manual_heap_type(void)
     return (PyObject *)type;
 }
 
+/* Complex-like type with a __complex__ method, instead of nb_complex slot,
+   to test deprecation. */
+
+static PyObject *
+complex_dunder(PyObject *self, PyObject *Py_UNUSED(dummy))
+{
+    return PyComplex_FromDoubles(1, 2);
+}
+
+static PyMethodDef old_complex_methods[] = {
+    {"__complex__", complex_dunder, METH_NOARGS},
+    {NULL, NULL} /* sentinel */
+};
+
+PyTypeObject OldComplexLikeType = {
+    PyVarObject_HEAD_INIT(NULL, 0)
+    .tp_name = "old_complex_like",
+    .tp_new = PyType_GenericNew,
+    .tp_methods = old_complex_methods,
+};
+
+
 static struct PyModuleDef _testcapimodule = {
     PyModuleDef_HEAD_INIT,
     .m_name = "_testcapi",
@@ -3315,6 +3337,10 @@ PyInit__testcapi(void)
         return NULL;
     }
 
+    if (PyType_Ready(&OldComplexLikeType) < 0)
+        return NULL;
+    Py_INCREF(&OldComplexLikeType);
+    PyModule_AddObject(m, "old_complex_like", (PyObject *)&OldComplexLikeType);
 
     /* Include tests from the _testcapi/ directory */
     if (_PyTestCapi_Init_Vectorcall(m) < 0) {

Objects/abstract.c

@@ -905,7 +905,7 @@ PyNumber_Check(PyObject *o)
     if (o == NULL)
         return 0;
     PyNumberMethods *nb = Py_TYPE(o)->tp_as_number;
-    return nb && (nb->nb_index || nb->nb_int || nb->nb_float || PyComplex_Check(o));
+    return nb && (nb->nb_index || nb->nb_int || nb->nb_float || nb->nb_complex);
 }
 
 /* Binary operators */
@@ -1659,44 +1659,61 @@ PyNumber_Complex(PyObject *o)
         return Py_NewRef(o);
     }
 
-    PyObject *f = _PyObject_LookupSpecial(o, &_Py_ID(__complex__));
-    if (f) {
-        PyObject *res = _PyObject_CallNoArgs(f);
-        Py_DECREF(f);
-        if (!res || PyComplex_CheckExact(res)) {
-            return res;
-        }
-        if (!PyComplex_Check(res)) {
-            PyErr_Format(PyExc_TypeError,
-                         "%.50s.__complex__ returned non-complex (type %.50s)",
-                         Py_TYPE(o)->tp_name, Py_TYPE(res)->tp_name);
-            Py_DECREF(res);
-            return NULL;
-        }
-        /* Issue #26983: warn if 'res' not of exact type complex. */
-        if (PyErr_WarnFormat(PyExc_DeprecationWarning, 1,
-                "%.50s.__complex__ returned non-complex (type %.50s).  "
-                "The ability to return an instance of a strict subclass of complex "
-                "is deprecated, and may be removed in a future version of Python.",
-                Py_TYPE(o)->tp_name, Py_TYPE(res)->tp_name)) {
-            Py_DECREF(res);
-            return NULL;
+    PyNumberMethods *m = Py_TYPE(o)->tp_as_number;
+    PyObject *res = NULL;
+
+    if (m && m->nb_complex) {
+        res = m->nb_complex(o);
+        goto complex_slot;
+    }
+    else {
+        PyObject *f = _PyObject_LookupSpecial(o, &_Py_ID(__complex__));
+        if (f) {
+            res = _PyObject_CallNoArgs(f);
+            Py_DECREF(f);
+            if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                             "Use nb_complex slot to implement __complex__", 1)) {
+                Py_XDECREF(res);
+                return NULL;
+            }
+            goto complex_slot;
         }
-        Py_complex cv = ((PyComplexObject *)res)->cval;
-        Py_DECREF(res);
-        return PyComplex_FromCComplex(cv);
     }
-
-    PyNumberMethods *m = Py_TYPE(o)->tp_as_number;
+    m = Py_TYPE(o)->tp_as_number;
     if (m && (m->nb_float || m->nb_index)) {
         double real = PyFloat_AsDouble(o);
         if (real != -1 || !PyErr_Occurred()) {
             return PyComplex_FromDoubles(real, 0.0);
         }
         return NULL;
     }
-
     return PyComplex_FromString(o);
+complex_slot:
+    if (!res) {
+        return NULL;
+    }
+    if (PyComplex_CheckExact(res)) {
+        return res;
+    }
+    if (!PyComplex_Check(res)) {
+        PyErr_Format(PyExc_TypeError,
+                     "%.50s.__complex__ returned non-complex (type %.50s)",
+                     Py_TYPE(o)->tp_name, Py_TYPE(res)->tp_name);
+        Py_DECREF(res);
+        return NULL;
+    }
+    /* Issue #26983: warn if 'res' not of exact type complex. */
+    if (PyErr_WarnFormat(PyExc_DeprecationWarning, 1,
+            "%.50s.__complex__ returned non-complex (type %.50s).  "
+            "The ability to return an instance of a strict subclass of complex "
+            "is deprecated, and may be removed in a future version of Python.",
+            Py_TYPE(o)->tp_name, Py_TYPE(res)->tp_name)) {
+        Py_DECREF(res);
+        return NULL;
+    }
+    Py_complex cv = ((PyComplexObject *)res)->cval;
+    Py_DECREF(res);
+    return PyComplex_FromCComplex(cv);
 }
 
 PyObject *