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. For example, IMO PyCode_New() (C API) and types.CodeType constructor (Python API) should be moved to the internal C API, likely with a deprecation period. Cython should not use it but a new stable API. Victor -- Night gathers, and now my watch begins. It shall not end until my death. _______________________________________________ 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/LFE4OV3NYWR4GBMCISZ3H7JH3SEFMX2E/ Code of Conduct: http://python.org/psf/codeofconduct/
