(Sorry for all the posts related to the limited API. It's been a pain point for me lately.)
Would it be feasible to have distinct header files that contain only the limited API (perhaps in Include/limited)?
The files could be auto-generated to avoid duplicated code (like other files in the repo), though the nature of the limited API suggests the only future changes would be opt-in ones, which should be manual anyway. If there is no auto-generation then there should be a test to ensure the limited API matches the corresponding public API definitions exactly. Either way, Include/Python.h would have to be updated to switch to Include/limited if Py_LIMITED_API is defined. Also, FWIW, Include/limited would effectively fill the role of the manifest described in PEP 652. [1]
With Include/limited, would we still need Include/cpython? I suppose we could keep only public API in Include/*.h and keep "private-but-not-internal" API in Include/cpython (or rename it to Include/private or Include/unstable).
Finally, is the separation of headers by access "rings" worth it? On the one hand it makes the divisions explicit and obvious and helps avoid API leaking out accidentally. We'd had success in that regard with Include/internal and Include/cpython. On the other hand, the divisions mean related API is often spread out across multiple files (albeit with matching names), where otherwise those would all be in one file.
Anway, this is something that came to mind as I was writing up my other posts to this list.
-eric
[1] https://www.python.org/dev/peps/pep-0652/#stable-abi-manifest