On Sun, Apr 3, 2022 at 6:32 AM Nick Coghlan <ncogh...@gmail.com> wrote:
> On Fri, 1 Apr 2022, 6:47 pm Victor Stinner, <vstin...@python.org> wrote: > >> On Wed, Mar 30, 2022 at 5:42 PM Guido van Rossum <gu...@python.org> >> 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-le...@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/YCHLFQ5KW6XF5C5CFWF4MRTZEXVBZBMA/ >> Code of Conduct: http://python.org/psf/codeofconduct/ >> > _______________________________________________ > Python-Dev mailing list -- python-dev@python.org > To unsubscribe send an email to python-dev-le...@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/ZBNJTAXS6TWQY7QH5H5XZS4CP64ZQAUU/ > Code of Conduct: http://python.org/psf/codeofconduct/ >
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@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/DQ5AUS3UBQGJV6YLQ4CJ5F5M7RWFC7DY/ Code of Conduct: http://python.org/psf/codeofconduct/
