On Wed, 6 Apr 2022, 7:05 am Victor Stinner, <vstin...@python.org> wrote:
> On Sun, Apr 3, 2022 at 3:29 PM Nick Coghlan <ncogh...@gmail.com> wrote: > > 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) > > For me an API is either stable (remains the same forever) or unstable > (change time to time). > > Public API means: stable, documented, tested. > > Internal API means: unstable, not documented, not tested. > > I'm not convinced that it's worth it to create something in the > middle. If you want to add doc and tests, it should become a public > stable API. > The middle semi-stable tier formalises a concept that we already have: no guarantees across feature releases, but both API and ABI stable within a release series. It's useful for tightly coupled projects like Cython, as it means they can get core level performance without the risk of API compatibility breaks in maintenance releases. Without defining this tier, effectively the *entire* internal API becomes semi-stable, as any changes made will risk breaking the third party projects that we've told to define Py_BUILD_CORE when compiling. Cheers, Nick. >
_______________________________________________ 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/7P3ENW56DFR5BOUFSOQUSXPFQNQ5MF56/ Code of Conduct: http://python.org/psf/codeofconduct/
