gh-141004: Reorganize and reword the 'Useful macros' section

[encukou]

This is a follow-up to #143508. When all the public macros were documented, the section became somewhat unwieldy.

• Group the macros
• Roughly order them to put the most important ones first
• Add expansions where it makes sense; especially if there's an equivalent in modern C or a common compiler

• Issue: Document the entire C API #141004

---

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

[vstinner]

Since you're already moving many functions, it may be interesting to sort functions in each category.

[vstinner]

Note: C11 added _Noreturn, but C23 adds [[noreturn]] and deprecates _Noreturn.

[encukou]

I'm aware, but don't want to get in the details too much.
We require C11, and as far as I know, deprecations in the C standard don't mean planned removal.

[encukou]

it may be interesting to sort functions in each category

Sort by what?
IMO, sorting by relevance works great, even though it's not objective.

[vstinner]

Sort by what?

I'm thinking at the alphabetical order.

[ZeroIntensity]

Sorry, I just caused conflicts here with #144279.

[encukou]

More macros -- more structure. How does this version look?

I've grouped them in categories, and sorted by relevance first, alphabet second. For example, Py_MAX/Py_MIN before Py_CHARMASK.

FWIW, I think combined entries are a great way to reduce duplication for things that do almost the same thing: Py_MAX & Py_MIN, Py_LL & Py_ULL. Sorting alphabetically would make these harder to find.

[ZeroIntensity]

Mostly LGTM, with two little things below.

[vstinner]

LGTM. I like the new organization.

[ZeroIntensity]

LGTM as well, thanks for the cleanup!

[miss-islington-app]

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @encukou, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker f85e1170d2b22d2ee42cd568144e0c9f57b0db67 3.13

[bedevere-app]

GH-144541 is a backport of this pull request to the 3.14 branch.

[bedevere-bot]

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

Hi! The buildbot s390x Fedora Stable Refleaks 3.14 (tier-3) has failed when building commit 3fe9735.

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/1776/builds/892) and take a look at the build logs.
4. Check if the failure is related to this commit (3fe9735) 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/1776/builds/892

Failed tests:

• test_external_inspection
• test_pyrepl

Failed subtests:

• test_only_active_thread - test.test_external_inspection.TestGetStackTrace.test_only_active_thread
• test_repl_eio - test.test_pyrepl.test_unix_console.TestUnixConsoleEIOHandling.test_repl_eio

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

==

Click to see traceback logs

Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.14.cstratak-fedora-stable-s390x.refleak/build/Lib/test/test_external_inspection.py", line 1246, in test_only_active_thread
    self.assertEqual(
    ~~~~~~~~~~~~~~~~^
        len(gil_traces), 1, "Should have exactly one GIL holder"
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
AssertionError: 0 != 1 : Should have exactly one GIL holder


Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.14.cstratak-fedora-stable-s390x.refleak/build/Lib/test/test_pyrepl/test_unix_console.py", line 390, in test_repl_eio
    _, err = proc.communicate(timeout=support.LONG_TIMEOUT)
             ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/buildbot/buildarea/3.14.cstratak-fedora-stable-s390x.refleak/build/Lib/subprocess.py", line 1220, in communicate
    stdout, stderr = self._communicate(input, endtime, timeout)
                     ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/buildbot/buildarea/3.14.cstratak-fedora-stable-s390x.refleak/build/Lib/subprocess.py", line 2153, in _communicate
    self._check_timeout(endtime, orig_timeout, stdout, stderr)
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/buildbot/buildarea/3.14.cstratak-fedora-stable-s390x.refleak/build/Lib/subprocess.py", line 1267, in _check_timeout
    raise TimeoutExpired(
    ...<2 lines>...
            stderr=b''.join(stderr_seq) if stderr_seq else None)
subprocess.TimeoutExpired: Command '['/home/buildbot/buildarea/3.14.cstratak-fedora-stable-s390x.refleak/build/python', '-E', '-S', '/home/buildbot/buildarea/3.14.cstratak-fedora-stable-s390x.refleak/build/Lib/test/test_pyrepl/eio_test_script.py']' timed out after 675.0 seconds


Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.14.cstratak-fedora-stable-s390x.refleak/build/Lib/subprocess.py", line 1138, in __del__
    _warn("subprocess %s is still running" % self.pid,
ResourceWarning: subprocess 2751248 is still running
Warning -- Unraisable exception
Exception ignored while finalizing file <_io.FileIO name=10 mode='rb' closefd=True>:
Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.14.cstratak-fedora-stable-s390x.refleak/build/Lib/unittest/case.py", line 668, in run
    with outcome.testPartExecutor(self):
ResourceWarning: unclosed file <_io.TextIOWrapper name=10 encoding='UTF-8'>
Warning -- Unraisable exception
Exception ignored while finalizing file <_io.FileIO name=8 mode='rb' closefd=True>:
Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.14.cstratak-fedora-stable-s390x.refleak/build/Lib/unittest/case.py", line 668, in run
    with outcome.testPartExecutor(self):
ResourceWarning: unclosed file <_io.TextIOWrapper name=8 encoding='UTF-8'>