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

encukou · 2026-02-04T13:08:25Z

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/

- 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

vstinner

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

vstinner · 2026-02-04T13:54:30Z

Doc/c-api/intro.rst

+
   A use for ``Py_UNREACHABLE()`` is following a call a function that
-   never returns but that is not declared :c:macro:`_Py_NO_RETURN`.
+   never returns but that is not declared ``_Noreturn``.


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

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.

Doc/c-api/intro.rst

Co-authored-by: Victor Stinner <vstinner@python.org>

encukou · 2026-02-04T14:41:49Z

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 · 2026-02-04T14:47:22Z

Sort by what?

I'm thinking at the alphabetical order.

ZeroIntensity · 2026-02-04T16:44:21Z

Sorry, I just caused conflicts here with #144279.

encukou · 2026-02-05T12:56:37Z

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.

Doc/c-api/intro.rst

vstinner

LGTM. I like the new organization.

Doc/c-api/intro.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

ZeroIntensity

LGTM as well, thanks for the cleanup!

miss-islington-app · 2026-02-06T10:55:15Z

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

…ythonGH-144471) - 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 (cherry picked from commit f85e1170d2b22d2ee42cd568144e0c9f57b0db67) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Victor Stinner <vstinner@python.org> Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

miss-islington-app · 2026-02-06T10:55:24Z

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 · 2026-02-06T10:55:32Z

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

…H-144471) (GH-144541) - 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 (cherry picked from commit f85e117) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Victor Stinner <vstinner@python.org> Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

bedevere-bot · 2026-02-06T14:15:05Z

⚠️⚠️⚠️ 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:

Don't panic.
Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
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.
Check if the failure is related to this commit (3fe9735) or if it is a false positive.
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'>

Reorganize and reword the 'Useful macros' section

44f9a3d

- 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

encukou requested review from ZeroIntensity and vstinner February 4, 2026 13:08

encukou added docs Documentation in the Doc dir topic-C-API labels Feb 4, 2026

github-project-automation bot added this to Docs PRs Feb 4, 2026

github-project-automation bot moved this to Todo in Docs PRs Feb 4, 2026

bedevere-app bot added awaiting core review skip news labels Feb 4, 2026

bedevere-app bot mentioned this pull request Feb 4, 2026

Document the entire C API #141004

Open

vstinner reviewed Feb 4, 2026

View reviewed changes

encukou and others added 2 commits February 4, 2026 15:35

Update Doc/c-api/intro.rst

abac586

Co-authored-by: Victor Stinner <vstinner@python.org>

Avoid warning

aa56752

encukou added 3 commits February 5, 2026 12:00

Merge in the main branch (re-applying additions from python#144279)

4e0b8ec

Merge changes made in GH UI

b6a72a0

Shuffle the macros around

360333d

ZeroIntensity reviewed Feb 5, 2026

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

vstinner approved these changes Feb 5, 2026

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Feb 5, 2026

encukou commented Feb 5, 2026

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Apply suggestions from code review

9de0587

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

ZeroIntensity approved these changes Feb 5, 2026

View reviewed changes

encukou added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Feb 6, 2026

encukou merged commit f85e117 into python:main Feb 6, 2026
33 checks passed

encukou deleted the doc-useful-macros branch February 6, 2026 10:55

github-project-automation bot moved this from Todo to Done in Docs PRs Feb 6, 2026

bedevere-app bot removed the awaiting merge label Feb 6, 2026

miss-islington-app bot assigned encukou Feb 6, 2026

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Feb 6, 2026

Uh oh!

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

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

Conversation

encukou commented Feb 4, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

vstinner Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

encukou Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

encukou commented Feb 4, 2026

Uh oh!

vstinner commented Feb 4, 2026

Uh oh!

ZeroIntensity commented Feb 4, 2026

Uh oh!

encukou commented Feb 5, 2026

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app bot commented Feb 6, 2026

Uh oh!

miss-islington-app bot commented Feb 6, 2026

Uh oh!

bedevere-app bot commented Feb 6, 2026

Uh oh!

bedevere-bot commented Feb 6, 2026

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

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

encukou commented Feb 4, 2026 •

edited by github-actions bot

Loading