gh-131704: add PyComplex_FromString() function

Author: skirpichev

Doc/c-api/complex.rst

@@ -207,6 +207,13 @@ Complex Numbers as Python Objects
    .. versionchanged:: 3.13
       Use :meth:`~object.__complex__` if available.
 
+.. c:function:: PyObject* PyComplex_FromString(PyObject *str)
+
+   Create a Python complex number object from the string value in *str* or
+   return ``NULL`` with an exception set on error.
+
+   .. versionadded:: next
+
 .. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
 
    Return the :c:type:`Py_complex` value of the complex number *op*.

Doc/data/stable_abi.dat

@@ -14,6 +14,7 @@ PyAPI_DATA(PyTypeObject) PyComplex_Type;
 #define PyComplex_CheckExact(op) Py_IS_TYPE((op), &PyComplex_Type)
 
 PyAPI_FUNC(PyObject *) PyComplex_FromDoubles(double real, double imag);
+PyAPI_FUNC(PyObject *) PyComplex_FromString(PyObject *op);
 
 PyAPI_FUNC(double) PyComplex_RealAsDouble(PyObject *op);
 PyAPI_FUNC(double) PyComplex_ImagAsDouble(PyObject *op);

Include/complexobject.h

@@ -131,6 +131,19 @@ def test_imagasdouble(self):
 
         # CRASHES imagasdouble(NULL)
 
+    def test_fromstring(self):
+        # Test PyComplex_FromString()
+        fromstring = _testlimitedcapi.complex_fromstring
+
+        self.assertEqual(fromstring("1+2j"), 1+2j)
+        self.assertEqual(fromstring("(1+2j)"), 1+2j)
+        self.assertEqual(fromstring("2j"), 2j)
+
+        self.assertRaises(ValueError, fromstring, "2j\0")
+        self.assertRaises(TypeError, fromstring, 2j)
+
+        # CRASHES fromstring(NULL)
+
     def test_asccomplex(self):
         # Test PyComplex_AsCComplex()
         asccomplex = _testcapi.complex_asccomplex

Lib/test/test_capi/test_complex.py

@@ -2544,3 +2544,5 @@
     added = '3.14'
 [function.Py_PACK_VERSION]
     added = '3.14'
+[function.PyComplex_FromString]
+    added = '3.14'

Lib/test/test_stable_abi_ctypes.py

@@ -58,13 +58,21 @@ complex_imagasdouble(PyObject *Py_UNUSED(module), PyObject *obj)
     return PyFloat_FromDouble(imag);
 }
 
+static PyObject *
+complex_fromstring(PyObject *Py_UNUSED(module), PyObject *obj)
+{
+    NULLABLE(obj);
+    return PyComplex_FromString(obj);
+}
+
 
 static PyMethodDef test_methods[] = {
     {"complex_check", complex_check, METH_O},
     {"complex_checkexact", complex_checkexact, METH_O},
     {"complex_fromdoubles", complex_fromdoubles, METH_VARARGS},
     {"complex_realasdouble", complex_realasdouble, METH_O},
     {"complex_imagasdouble", complex_imagasdouble, METH_O},
+    {"complex_fromstring", complex_fromstring, METH_O},
     {NULL},
 };
 

Misc/stable_abi.toml

@@ -1080,6 +1080,12 @@ complex_subtype_from_string(PyTypeObject *type, PyObject *v)
     return result;
 }
 
+PyObject *
+PyComplex_FromString(PyObject *op)
+{
+    return complex_subtype_from_string(&PyComplex_Type, op);
+}
+
 /* The constructor should only accept a string as a positional argument,
  * not as by the 'real' keyword.  But Argument Clinic does not allow
  * to distinguish between argument passed positionally and by keyword.