◐ Shell
reader mode source ↗
Skip to content

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

Merged
encukou merged 7 commits into
python:mainfrom
encukou:doc-useful-macros
Feb 6, 2026
Merged

gh-141004: Reorganize and reword the 'Useful macros' section#144471
encukou merged 7 commits into
python:mainfrom
encukou:doc-useful-macros

Conversation

@encukou

@encukou encukou commented Feb 4, 2026 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Member

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

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

@encukou
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
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Feb 4, 2026
@bedevere-app bedevere-app Bot mentioned this pull request Feb 4, 2026
Open
vstinner
vstinner reviewed Feb 4, 2026
View reviewed changes

@vstinner vstinner left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide comment

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

encukou and others added 2 commits February 4, 2026 15:35
@encukou @vstinner
Update Doc/c-api/intro.rst …
abac586 
Co-authored-by: Victor Stinner <vstinner@python.org>
@encukou
Avoid warning
aa56752
@encukou

encukou commented Feb 4, 2026

Copy link
Copy Markdown
Member Author

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

vstinner commented Feb 4, 2026

Copy link
Copy Markdown
Member

Sort by what?

I'm thinking at the alphabetical order.

@ZeroIntensity

ZeroIntensity commented Feb 4, 2026

Copy link
Copy Markdown
Member

Sorry, I just caused conflicts here with #144279.

@encukou

encukou commented Feb 5, 2026

Copy link
Copy Markdown
Member Author

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
ZeroIntensity reviewed Feb 5, 2026
View reviewed changes

@ZeroIntensity ZeroIntensity left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide comment

Mostly LGTM, with two little things below.

vstinner
vstinner approved these changes Feb 5, 2026
View reviewed changes

@vstinner vstinner left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide comment

LGTM. I like the new organization.

@encukou @ZeroIntensity
Apply suggestions from code review …
9de0587 
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
ZeroIntensity
ZeroIntensity approved these changes Feb 5, 2026
View reviewed changes

@ZeroIntensity ZeroIntensity left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide comment

LGTM as well, thanks for the cleanup!

@encukou encukou added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Feb 6, 2026
Hide details View details @encukou encukou merged commit f85e117 into python:main Feb 6, 2026
33 checks passed
@encukou encukou deleted the doc-useful-macros branch February 6, 2026 10:55
@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs Feb 6, 2026
@miss-islington-app

miss-islington-app Bot commented Feb 6, 2026

Copy link
Copy Markdown

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Feb 6, 2026
@encukou @vstinner
@ZeroIntensity @miss-islington
pythongh-141004: Reorganize and reword the 'Useful macros' section (p… …
9ee75e2 
…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 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>
@miss-islington-app

miss-islington-app Bot commented Feb 6, 2026

Copy link
Copy Markdown

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

bedevere-app Bot commented Feb 6, 2026

Copy link
Copy Markdown

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

@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Feb 6, 2026
encukou added a commit that referenced this pull request Feb 6, 2026
@miss-islington @encukou
@vstinner @ZeroIntensity
[3.14] gh-141004: Reorganize and reword the 'Useful macros' section (G… …
3fe9735 
…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

bedevere-bot commented Feb 6, 2026

Copy link
Copy Markdown

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

@encukou encukou removed the needs backport to 3.13 bugs and security fixes label Feb 9, 2026
@encukou

encukou commented Feb 9, 2026

Copy link
Copy Markdown
Member Author

I'm not planning to resolve 3.13 conflicts & backport to 3.13. The main point of docs backports beyond the current stable version is to make future backports easier (especially security issue fix docs), but in this part of the docs, complex changes don't seem too likely.

thunder-coding pushed a commit to thunder-coding/cpython that referenced this pull request Feb 15, 2026
@encukou @vstinner
@ZeroIntensity @thunder-coding
pythongh-141004: Reorganize and reword the 'Useful macros' section (p… …
c34c962 
…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

Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
ljfp pushed a commit to ljfp/cpython that referenced this pull request Apr 25, 2026
@encukou @vstinner
@ZeroIntensity @ljfp
pythongh-141004: Reorganize and reword the 'Useful macros' section (p… …
7d8b204 
…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

Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vstinner vstinner

@ZeroIntensity ZeroIntensity ZeroIntensity approved these changes

Assignees

@encukou encukou

Labels

docs skip news topic-C-API

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@encukou @vstinner @ZeroIntensity @bedevere-bot