gh-128813: soft-deprecate _Py_c_*() functions

[skirpichev]

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

---

📚 Documentation preview 📚: https://cpython-previews--137261.org.readthedocs.build/

[skirpichev]

In follow-up PR I'm planning documenting & deprecating cval field and do more severe rewriting of docs:

1. describe Py_complex as input/output format
2. make a dedicated section for low-level C-API at the end of docs
3. disband all other sections

But let me know if it's better just add all this stuff here, in one shot.

[encukou]

I think it's fine to split the PRs.

[bedevere-bot]

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot s390x RHEL8 Refleaks 3.x (tier-3) has failed when building commit 9ced5c4.

What do you need to do:

1. Don't panic.
2. Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
3. Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/75/builds/3105) and take a look at the build logs.
4. Check if the failure is related to this commit (9ced5c4) or if it is a false positive.
5. If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/75/builds/3105

Failed tests:

• test.test_multiprocessing_fork.test_processes

Failed subtests:

• test_interrupt - test.test_multiprocessing_fork.test_processes.WithProcessesTestProcess.test_interrupt

Summary of the results of the build (if available):

==

Click to see traceback logs

Traceback (most recent call last): File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/test/_test_multiprocessing.py", line 588, in test_interrupt exitcode =self._kill_process(multiprocessing.Process.interrupt) File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/test/_test_multiprocessing.py", line 570, in _kill_processself.assertEqual(join(), None) ~~~~^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/test/_test_multiprocessing.py", line 250, in __call__returnself.func(*args, **kwds) ~~~~~~~~~^^^^^^^^^^^^^^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/process.py", line 156, in join res =self._popen.wait(timeout) File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/popen_fork.py", line 44, in waitreturnself.poll(os.WNOHANGif timeout ==0.0else0) ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/popen_fork.py", line 28, in poll pid, sts = os.waitpid(self.pid, flag) ~~~~~~~~~~^^^^^^^^^^^^^^^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/test/_test_multiprocessing.py", line 566, in handlerraiseRuntimeError('join took too long: %s'% p) RuntimeError: join took too long: <Process name='Process-2' pid=223429 parent=223426 started daemon> Traceback (most recent call last): File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/process.py", line 320, in _bootstrapself.run() ~~~~~~~~^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/process.py", line 108, in runself._target(*self._args, **self._kwargs) ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/test/_test_multiprocessing.py", line 518, in _sleep_some_event time.sleep(100) ~~~~~~~~~~^^^^^ KeyboardInterrupt k Traceback (most recent call last): File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/test/_test_multiprocessing.py", line 588, in test_interrupt exitcode =self._kill_process(multiprocessing.Process.interrupt) File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/test/_test_multiprocessing.py", line 570, in _kill_processself.assertEqual(join(), None) ~~~~^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/test/_test_multiprocessing.py", line 250, in __call__returnself.func(*args, **kwds) ~~~~~~~~~^^^^^^^^^^^^^^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/process.py", line 156, in join res =self._popen.wait(timeout) File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/popen_fork.py", line 44, in waitreturnself.poll(os.WNOHANGif timeout ==0.0else0) ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/popen_fork.py", line 28, in poll pid, sts = os.waitpid(self.pid, flag) ~~~~~~~~~~^^^^^^^^^^^^^^^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/test/_test_multiprocessing.py", line 566, in handlerraiseRuntimeError('join took too long: %s'% p) RuntimeError: join took too long: <Process name='Process-933' pid=201393 parent=190787 started daemon> Traceback (most recent call last): File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/process.py", line 320, in _bootstrapself.run() ~~~~~~~~^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/process.py", line 108, in runself._target(*self._args, **self._kwargs) ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/test/_test_multiprocessing.py", line 517, in _sleep_some_event event.set() ~~~~~~~~~^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/synchronize.py", line 344, in setwithself._cond: ^^^^^^^^^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/synchronize.py", line 242, in __exit__returnself._lock.__exit__(*args) ~~~~~~~~~~~~~~~~~~~^^^^^^^ File "/home/buildbot/buildarea/3.x.cstratak-rhel8-s390x.refleak/build/Lib/multiprocessing/synchronize.py", line 100, in __exit__returnself._semlock.__exit__(*args) ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^ KeyboardInterrupt k