gh-128813: deprecate cval field of the PyComplexObject struct

[skirpichev]

• Issue: Deprecate PyComplexObject.cval and soft-deprecate _Py_c*() API #128813

---

📚 Documentation preview 📚: https://cpython-previews--137271.org.readthedocs.build/en/137271/c-api/complex.html

[encukou]

Per PEP-387, the preferred deprecation period is 5 years (so the removal would be in 3.20). Is there a reason to accelerate that?

[skirpichev]

Per PEP-387, the preferred deprecation period is 5 years (so the removal would be in 3.20). Is there a reason to accelerate that?

Hmm, probably not soo much. I would bet, that M$ compiler will not have complex types in 3.17 nor in 3.20. Though, maybe we could keep legacy code with _Py_c_*() functions just for M$ systems and use native language type for the rest.

Quick search on GH give me very few project (two), that use this undocumented field:
https://github.com/search?q=%2F-%3Ecval%2F+language%3AC&type=code&l=C&p=1
This is the only an excuse to use minimal lag in versions between announce and removal, as permitted by PEP 387.

[encukou]

maybe we could keep legacy code with _Py_c_*() functions just for M$ systems and use native language type for the rest.

I don't think we want to maintain two implementations.

[skirpichev]

I don't think we want to maintain two implementations.

One of them will be trivial, much like PyFloatObject now. I think that this opportunity could be at least explored. Unless we aren't going into introduction of the imaginary type (which I think is The Right Thing), Annex G double _Complex type - is the future.

I'm fine to delay removal to 3.20. But impact of this deprecation looks to be low and I prefer if it will add as less constraints on us as possible.

CC @vstinner

[skirpichev]

BTW, I can do planned reorganization of docs (#137261 (comment)) here. But, probably, it worth a separate pr.

[vstinner]

Quick search on GH give me very few project (two), that use this undocumented field

IMO it's fine to only deprecate for 2 releases since it's rare to use the C API to access PyComplex objects. I'm not suprised that a code search only finds 2 projects.

[encukou]

One of them will be trivial, much like PyFloatObject now. I think that this opportunity could be at least explored.

If we already need to keep the existing implementation (for MS, and any other compilers without Annex G support), I don't see any benefit in adding a second implementation -- even if it's trivial.

@skirpichev requested a review from @encukou 40 minutes ago

I still see no strong reason to use a shorter-than-default deprecation period.

[skirpichev]

Ok, removal deferred to 3.20.

[encukou]

Thanks! A wording nitpick; but this is ready to go. @vstinner, do you agree?

[vstinner]

LGTM