On Mon, May 30, 2022 at 12:54 PM Steve Dower <steve.dower@python.org> wrote:
I prefer separate header files, provided people outside of core always
have one (presumably "Python.h") that should be included first and
includes enough info to check which headers will be available (i.e. the
version defs).

The idea we were kicking around was e.g. `Python-unstable.h` would be all of the limited API plus the unstable parts, `Python-unlimited.h` would be **everything**, etc. I would expect `Python.h` would continue to be what it is today for compatibility purposes. There wouldn't necessarily be an "always have one" header since these header files would cascade into each other as you opted into more and more unstable APIs (think about this as layers of APIs 😉 and representing each encompassing layer with a header file). This would also let teams set policies of how much instability risk they were willing to take by having CI have an allowlist/blocklist of Python header files.


Modifying preprocessor definitions for different Python versions, or
having to set them before knowing what version is being used, seems more


On 5/30/2022 8:26 PM, Brett Cannon wrote:
> We discussed having leading underscores for this API tier, and it was decided that a leading underscore was preferred.
> This did start a discussion, though, about whether we should control API access/opt-in via `#include` by having `.h` files that convey what API the user is opting into, or use `#define` to control what gets exposed via `Python.h`. The general feeling was that the header file idea is ideal, but it is a little extra work to transition to if you want to be compatible with older versions of Python that wouldn't have the header files (Victor's compatibility project could help here). The question for the team is whether separate header files makes sense to others, or would people prefer using `#define` and `Python.h` to control API access/opt-in?