The Python C API should only define macros with a name starting wit `Py`

[vstinner]

Currently, the Python C API defines 472 macros with a name which doesn't start with Py, PY, _Py or _PY prefix.

I propose adding a check to prevent adding new macros which doesn't respect this convention. Existing invalid names will be added to an ignore list for now.

Linked PRs

• gh-157695: Check that C API macros start with "Py" #157696
• gh-157695: Rename HAVE_FLOAT16 macro to _Py_HAVE_FLOAT16 #157752

[vstinner]

The following Include/ header files are not included by Python.h and defines many macros which don't start with Py prefix:

• opcode.h
• opcode_ids.h
• errcode.h
• osdefs.h
• structmember.h

To clean up the C API, a simple move would be to move these header files to the internal C API. Problem: they are actually used in the wild (well, as usual ;-)).

I checked PyPI top 15,000 projects (at 2026-09-17) to find projects including these header files.

Projects (10) including opcode.h:

• coverage (7.16.1)
• crosshair_tool (0.0.110)
• ddtrace (4.15.0)
• nuitka (4.2.1)
• pygments (2.21.0)
• pyobjc_core (12.2.2)
• pywinpty (3.0.5)
• rook (0.1.209)
• slipcover (1.1.0)
• yappi (1.7.6)

I found no project including errcode.h.

Projects (4) including osdefs.h:

• freeze_core (0.7.5)
• mod_wsgi (6.0.6)
• nuitka (4.2.1)
• scandir (1.10.0)

Projects (169) including structmember.h:

• MySQL-python (1.2.5)
• PyICU-binary (2.7.4)
• PyQt5 (5.15.11)
• ... the list is quite long, I prefer to truncate it! :-)

For example, I searched for include\s+["<]errcode\.h[">] for errcode.h include.

[vstinner]

This check is similar to "make smelly" which fails if libpython exports symbols with a name which doesn't start with "Py".

[vstinner]

cc @encukou

[vstinner]

See issue gh-149685 "Use _Py prefix for private C API added in 3.15" for a recent change (last May) about a similar issue.