On 29. 04. 22 19:02, Guido van Rossum wrote:
> On Fri, Apr 29, 2022 at 10:15 AM Petr Viktorin <encukou@gmail.com
> <mailto:encukou@gmail.com>> wrote:
>
> On 29. 04. 22 16:32, Victor Stinner wrote:
> > Ok, let me start with the serious business: API name.
> >
> > I'm not comfortable with "semi-stable". Python already has a "limited
> > API" and a "stable ABI". Just by its name, it's unclear what
> > "semi-stable" means.
[...]
> Nick Coghlan argued against that term:
[...]
> But I also like “unstable” better than “semi-stable”. Splitting the
> internals into “private”/“internal” and “unstable” seems reasonable.
>
>
> I think picking "semi-stable" would be giving in to the OCD nerd in all
> of us. :-) While perhaps technically less precise, "unstable" is the
> catchy name with the right association. (And yes, we should keep it
> stable within bugfix releases, but the name doesn't need to reflect that
> detail.) The "internal API" isn't an API at all (except for CPython core
> developers and contributors). The "unstable API" would definitely be an
> *API* for users outside the core.
>
> So let's please go with "unstable".
Thanks, you worded that perfectly!
Alright, the PEP now uses “unstable” rather than “semi-stable”. And I
don't see any issues with the technical details, so I'll see if it can
still get into Python 3.11. Hopefully Pablo agrees as the Release Manager.
Thanks for the discussion, everyone!
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_.