On Thu, May 5, 2022 at 5:35 AM Thomas Wouters firstname.lastname@example.org wrote: [...]
I've already brought this up to Petr directly, but I would greatly prefer new unstable API functions have leading underscores, and that existing functions being moved to the unstable API are _not_ renamed.
Renaming existing functions means a lot of unnecessary code churn. It looks like we have more _-prefixed unstable functions than not, but I don't think the churn is worth renaming the currently public ones.
Leading underscores for unstable API functions (that aren't currently public) means we keep the widely assumed guarantee that Py*/PY* are part of the public API. The Py_USING_UNSTABLE_API define is per-file, not per symbol/use, so I would rather not open the door to unintended or unaware use of unstable APIs. By giving the functions the leading underscore, we're forcing people to think about -- or check the documentation -- whether the specific function is okay to use.
The unstable API is intended for specific use-cases, and I think it's preferable to put the burden of figuring out if a _Py/_PY* symbol is acceptable for them to use, rather than putting the burden of figuring out if a Py/PY* symbol is acceptable up use on _everyone else_.
I don't think that's necessary. I still see the unstable API as public: it needs more maintenance, but it's not particularly dangerous to use it. I think defining Py_USING_UNSTABLE_API once is quite enough.