gh-131704: add PyComplex_FromString() and PyNumber_Complex() C-API functions

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/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/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/abstract.h

@@ -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/complexobject.h

@@ -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/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

@@ -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
@@ -293,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

@@ -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,), {})
@@ -80,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"))
@@ -302,6 +306,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

Misc/NEWS.d/next/C_API/2025-03-25-12-53-40.gh-issue-131704.Q6amy8.rst

@@ -0,0 +1,3 @@
+Add :c:func:`PyComplex_FromString` to create :class:`complex` numbers from
+strings and :c:func:`PyNumber_Complex` (``complex(o)`` equivalent).  Patch by
+Sergey B Kirpichev.

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]
@@ -2544,3 +2546,7 @@
     added = '3.14'
 [function.Py_PACK_VERSION]
     added = '3.14'
+[function.PyComplex_FromString]
+    added = '3.14'
+[function.PyNumber_Complex]
+    added = '3.14'

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/_testcapi/numbers.c

@@ -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},

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) {

Modules/_testlimitedcapi/complex.c

@@ -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},
 };