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