Add PyNumber_Complex() and PyComplex_FromString() functions

[skirpichev]

Feature or enhancement

Proposal:

Maybe it should be discussed first in the C-API WG, but this case seems more or less obvious for me.

No C-API function exists to create complex numbers from string. This is available on C-level only with using pure-Python API. All others builtin numeric types have a dedicated API for this (PyFloat_FromString() and PyLong_FromString()). Proposal - float-like:

PyObject* PyComplex_FromString(PyObject *str)

In stdlib this can be used e.g. to solve #98485.

Similarly for PyNumber_Complex(), complex numbers apparently are part of the Number Protocol: i.e. PyNumber_Check() is true for them and they support most it's API functions. Why there is no PyNumber_Complex(), which would be working like PyNumber_Long() and PyNumber_Float()? Proposal:

PyObject* PyNumber_Complex(PyObject *o)

An equivalent of complex(o).

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

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

[vstinner]

PyObject* PyComplex_FromString(PyObject *str)

You can already call complex(str) constructor in C via the public type &PyComplex_Type. Why does it need a dedicated function?

All others builtin numeric types have a dedicated API for this (PyFloat_FromString() and PyLong_FromString()).

I'm not convinced that it's a reason to add more functions.

PyObject* PyNumber_Complex(PyObject *o). An equivalent of complex(o).

You can already call complex(o) constructor in C, no?

Why there is no PyNumber_Complex(), which would be working like PyNumber_Long() and PyNumber_Float()?

Nobody asked to add it, and using complex numbers is more rare.

[skirpichev]

You can already call complex(str) constructor in C via the public type &PyComplex_Type. Why does it need a dedicated function? [...] You can already call complex(o) constructor in C, no?

That much more slow. Should I provide benchmarks?

(1) Nobody asked to add it, and (2) using complex numbers is more rare.

(1) I asked:-) (2) That's true, yet it's easy to find examples e.g. for PyNumber_Complex() with a quick search on Github:
https://github.com/wjakob/nanobind/blob/10eafbc528574a7045133e9751d00c8bd61ae0da/src/common.cpp#L963-L964

[vstinner]

@serhiy-storchaka: What do you think of these functions?

[serhiy-storchaka]

This is really a complex issue (even several issues).

PyComplex_FromString(). This is simpler issue. The only problem is that most of _FromString() C API takes a C string as argument. PyFloat_FromString() is the only exception, it takes PyObject* (which can be str, bytes, bytearray, or any object supporting the buffer protocol). So what should PyComplex_FromString() accept? This is a small question, but this is a question.

PyNumber_Complex() is a part of larger issue. There is no slot for the __complex__ special method. This does not only mean that the complex constructor is slower, but that PyNumber_Check() returns false for complex-like objects except the complex instances. There is no public C API to check that the object can be implicitly converted to real or complex number (for the former, we can use PyNumber_Check(x) && !PyComplex_Check(x) -- this is not obvious).

I think that complex should not be a part of the core at first place, it is more like Decimal or Fraction. It is partially integrated, but not completely, so we have to live with this. If we want to integrate complex numbers more (not just the complex type, but complex-like object), we need to design better integration for Decimal, Fraction, high-precision floating numbers, etc at the level of general protocols.

[skirpichev]

This is really a complex issue (even several issues).

Then lets focus on the second.

There is no slot for the __complex__ special method.

There was a proposal to support this: https://discuss.python.org/t/56620

There is no public C API to check that the object can be implicitly converted to real or complex number

And keep in mind that there is no big difference for complexes (wrt float's) on pure-Python level (similar dunder method, etc).

I think that complex should not be a part of the core at first place, it is more like Decimal or Fraction.

Anyway, we have to live with that. BTW, I don't think it's like Decimal's or Fraction's. Complex numbers much more useful and have much wider support in other languages.

If we want to integrate complex numbers more (not just the complex type, but complex-like object), we need to design better integration for Decimal, Fraction, high-precision floating numbers, etc at the level of general protocols.

Why this should be a blocker? I think you mix very different things. E.g. Decimal's aren't even part of the concrete numbers ABC (well, being just Number's).

[skirpichev]

PR is ready: #132347. I kept is as draft, because Victor seems -1 on this idea so far(. Then, maybe it worth a prior discussion on d.p.o and/or C-API WG.

I think there is no way to get rid of complex numbers from the core. So, no reasons to keep them integrated only partially.