On Sun, Apr 3, 2022 at 6:32 AM Nick Coghlan
On Fri, 1 Apr 2022, 6:47 pm Victor Stinner,
wrote: On Wed, Mar 30, 2022 at 5:42 PM Guido van Rossum
wrote: I'm not convinced that advertising an API as being Unstable (in the documentation?) is going to solve any kind of problem. People love to use private APIs, and they do it simply because it's technically possible :-) At the end of the day, we have to help them updating their code, otherwise we (at least my Red Hat team) cannot update Python.
I designed the internal C API to be more annoying to be used (need to define a macro, need more specific #include) in the hope that people will think twice before using it :-)
The changes you've made have been excellent, and the existing 3 categories (stable public ABI, stable public API, unstable internal API) cover the vast majority of cases.
The final case that isn't quite covered yet is to offer a "semi-stable" API category for use cases that are intrinsically coupled to implementation details that may change between feature releases, but should remain stable within a release series.
The concrete motivating example for the new category is the extra APIs you need in order to provide an alternative eval loop implementation.
The internal API category doesn't properly cover that case, as the APIs there are free to change even in maintenance releases, and setting Py_BUILD_CORE exposes a lot more than what an alternative eval loop would need.
Regular public functions may work in some cases, but aren't necessarily practical in others (such as exposing the internal frame details for use in alternative eval loops).
From an implementation PoV, my own suggestion would be to define a new API tier with an opt-in macro rather than relying solely on documentation or naming conventions.
For example, define "Py_SEMI_STABLE_API" to opt in, with the headers under "Include/cpython/semi_stable/" (I don't like "unstable" as potential terminology here, since the internal API is already unstable - we're splitting the difference between that and the long term stability of the full public API)
Cheers, Nick.
+1 for an official "semi stable API tier". It's already the case that essentially anything in Python can change, it's just a question of how quickly and with how much friction. Public APIs need to go through a multi-version deprecation cycle (https://peps.python.org/pep-0387/#making-incompatible-changes). Private internal APIs can (theoretically) change without notice between patch releases. There's a missing tier for APIs that can change without notice between feature releases, but are guaranteed(*) to be backwards compatible within a feature release, and the PEP 523 frame evaluation API is an excellent example for this need (maybe any newly added API should always go through this stage for a few releases?). Even though the docs ( https://docs.python.org/3.10/c-api/intro.html#include-files) explicitly call out that _Py-prefixed APIs are internal and should not be used by extensions, this isn't the case in practice, so introducing the 3-tier concept could be an opportunity to clean up this situation a bit. What exactly should be the naming conventions per tier, and the names of the tiers, is bikeshedding that should happen after there's agreement about the tiers concept :-) (*) "guaranteed" with exceptions of course (e.g. security or other critical issue)
Victor _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/YCHLFQ5K... Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/ZBNJTAXS... Code of Conduct: http://python.org/psf/codeofconduct/