gh-131704: add PyNumber_Complex() function

Author: skirpichev

Doc/c-api/number.rst

@@ -252,6 +252,16 @@ Number Protocol
    This is the equivalent of the Python expression ``float(o)``.
 
 
+.. c:function:: PyObject* PyNumber_Complex(PyObject *o)
+
+   .. index:: pair: built-in function; complex
+
+   Returns the *o* converted to a complex object on success, or ``NULL`` on failure.
+   This is the equivalent of the Python expression ``complex(o)``.
+
+   .. versionadded:: next
+
+
 .. c:function:: PyObject* PyNumber_Index(PyObject *o)
 
    Returns the *o* converted to a Python int on success or ``NULL`` with a

Doc/data/stable_abi.dat

@@ -564,6 +564,12 @@ PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
   This is the equivalent of the Python expression: float(o). */
 PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
 
+/* Returns the object 'o' converted to a complex object on success, or NULL
+   on failure.
+
+  This is the equivalent of the Python expression: complex(o). */
+PyAPI_FUNC(PyObject *) PyNumber_Complex(PyObject *o);
+
 
 /* --- In-place variants of (some of) the above number protocol functions -- */
 

Include/abstract.h

@@ -57,6 +57,9 @@ class IntLike(WithDunder):
 class FloatLike(WithDunder):
     methname = '__float__'
 
+class ComplexLike(WithDunder):
+    methname = '__complex__'
+
 
 def subclassof(base):
     return type(base.__name__ + 'Subclass', (base,), {})
@@ -302,6 +305,47 @@ def test_float(self):
         self.assertRaises(TypeError, float_, object())
         self.assertRaises(SystemError, float_, NULL)
 
+    def test_complex(self):
+        # Test PyNumber_Complex()
+        complex_ = _testcapi.number_complex
+
+        self.assertEqual(complex_(1.25), 1.25+0j)
+        self.assertEqual(complex_(123), 123+0j)
+        self.assertEqual(complex_("1.25"), 1.25+0j)
+        self.assertEqual(complex_(1+2j), 1+2j)
+        self.assertEqual(complex_("1+2j"), 1+2j)
+
+        self.assertEqual(complex_(FloatLike.with_val(4.25)), 4.25 + 0j)
+        self.assertEqual(complex_(IndexLike.with_val(99)), 99.0 + 0j)
+        self.assertEqual(complex_(IndexLike.with_val(-1)), -1.0 + 0j)
+        self.assertEqual(complex_(ComplexLike.with_val(1+2j)), 1+2j)
+
+        self.assertRaises(TypeError, complex_, FloatLike.with_val(687))
+        x = FloatLike.with_val(subclassof(float)(4.25))
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", DeprecationWarning)
+            self.assertRaises(DeprecationWarning, complex_, x)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(complex_(x), 4.25+0j)
+        self.assertRaises(RuntimeError, complex_,
+                          FloatLike.with_exc(RuntimeError))
+
+        self.assertRaises(TypeError, complex_, ComplexLike.with_val(687))
+        x = ComplexLike.with_val(subclassof(complex)(1+2j))
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", DeprecationWarning)
+            self.assertRaises(DeprecationWarning, complex_, x)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(complex_(x), 1+2j)
+        self.assertRaises(RuntimeError, complex_,
+                          ComplexLike.with_exc(RuntimeError))
+
+        self.assertRaises(TypeError, complex_, IndexLike.with_val(1.25))
+        self.assertRaises(OverflowError, complex_, IndexLike.with_val(2**2000))
+
+        self.assertRaises(TypeError, complex_, object())
+        self.assertRaises(SystemError, complex_, NULL)
+
     def test_index(self):
         # Test PyNumber_Index()
         index = _testcapi.number_index

Lib/test/test_capi/test_number.py

@@ -2546,3 +2546,5 @@
     added = '3.14'
 [function.PyComplex_FromString]
     added = '3.14'
+[function.PyNumber_Complex]
+    added = '3.14'

Lib/test/test_stable_abi_ctypes.py

@@ -87,6 +87,7 @@ BINARYFUNC(InPlaceOr, inplaceor)
 
 UNARYFUNC(Long, long)
 UNARYFUNC(Float, float)
+UNARYFUNC(Complex, complex)
 UNARYFUNC(Index, index)
 
 static PyObject *
@@ -160,6 +161,7 @@ static PyMethodDef test_methods[] = {
     {"number_inplaceor", number_inplaceor, METH_VARARGS},
     {"number_long", number_long, METH_O},
     {"number_float", number_float, METH_O},
+    {"number_complex", number_complex, METH_O},
     {"number_index", number_index, METH_O},
     {"number_tobase", number_tobase, METH_VARARGS},
     {"number_asssizet", number_asssizet, METH_VARARGS},

Misc/stable_abi.toml

@@ -1648,6 +1648,56 @@ PyNumber_Float(PyObject *o)
     return PyFloat_FromString(o);
 }
 
+PyObject *
+PyNumber_Complex(PyObject *o)
+{
+    if (o == NULL) {
+        return null_error();
+    }
+
+    if (PyComplex_CheckExact(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;
+        }
+        Py_complex cv = ((PyComplexObject *)res)->cval;
+        Py_DECREF(res);
+        return PyComplex_FromCComplex(cv);
+    }
+
+    PyNumberMethods *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);
+}
 
 PyObject *
 PyNumber_ToBase(PyObject *n, int base)

Modules/_testcapi/numbers.c

@@ -1099,61 +1099,24 @@ PyComplex_FromString(PyObject *op)
 static PyObject *
 actual_complex_new(PyTypeObject *type, PyObject *args, PyObject *kwargs)
 {
-    PyObject *res = NULL;
-    PyNumberMethods *nbr;
+    Py_ssize_t nargs = PyTuple_GET_SIZE(args);
 
-    if (PyTuple_GET_SIZE(args) > 1 || (kwargs != NULL && PyDict_GET_SIZE(kwargs))) {
+    if (nargs > 1 || (kwargs != NULL && PyDict_GET_SIZE(kwargs))) {
         return complex_new(type, args, kwargs);
     }
-    if (!PyTuple_GET_SIZE(args)) {
+    if (!nargs) {
         return complex_subtype_from_doubles(type, 0, 0);
     }
 
     PyObject *arg = PyTuple_GET_ITEM(args, 0);
-    /* Special-case for a single argument when type(arg) is complex. */
-    if (PyComplex_CheckExact(arg) && type == &PyComplex_Type) {
-        /* Note that we can't know whether it's safe to return
-           a complex *subclass* instance as-is, hence the restriction
-           to exact complexes here.  If either the input or the
-           output is a complex subclass, it will be handled below
-           as a non-orthogonal vector.  */
-        return Py_NewRef(arg);
-    }
-    if (PyUnicode_Check(arg)) {
-        return complex_subtype_from_string(type, arg);
-    }
-    PyObject *tmp = try_complex_special_method(arg);
-    if (tmp) {
-        Py_complex c = ((PyComplexObject*)tmp)->cval;
-        res = complex_subtype_from_doubles(type, c.real, c.imag);
-        Py_DECREF(tmp);
-    }
-    else if (PyErr_Occurred()) {
-        return NULL;
-    }
-    else if (PyComplex_Check(arg)) {
-        /* Note that if arg is of a complex subtype, we're only
-           retaining its real & imag parts here, and the return
-           value is (properly) of the builtin complex type. */
-        Py_complex c = ((PyComplexObject*)arg)->cval;
+    PyObject *res = PyNumber_Complex(arg);
+
+    if (res && type != &PyComplex_Type) {
+        Py_complex c = _PyComplexObject_CAST(res)->cval;
+
+        Py_DECREF(res);
         res = complex_subtype_from_doubles(type, c.real, c.imag);
     }
-    else if ((nbr = Py_TYPE(arg)->tp_as_number) != NULL &&
-             (nbr->nb_float != NULL || nbr->nb_index != NULL))
-    {
-        /* The argument really is entirely real, and contributes
-           nothing in the imaginary direction.
-           Just treat it as a double. */
-        double r = PyFloat_AsDouble(arg);
-        if (r != -1.0 || !PyErr_Occurred()) {
-            res = complex_subtype_from_doubles(type, r, 0);
-        }
-    }
-    else {
-        PyErr_Format(PyExc_TypeError,
-                     "complex() argument must be a string or a number, not %T",
-                     arg);
-    }
     return res;
 }