So here's my proposal:
- This API stays with the regular public API (Include/cpython/), but to
use it you'll need to #define Py_USING_UNSTABLE_API (name up for
bikeshedding).
- Since we're nearing Beta and there's no rush to break things, in 3.11
you only get a warning if you try to use it without the opt-in #define.
In 3.12 it'll fail.
- The functions will be renamed to drop the leading underscore. The old
names will be available as aliases (using #define) and may be removed
whenever the API changes. (Ideally, the underscore should always mark
API that's fully private with no guarantees at all.)
- The API will be stable during a minor release. (As usual, for extreme
cases, exceptions are possible with SC approval.)
- Docs will be updated:
- https://devguide.python.org/c-api/
- Individual reference entries for the API and the new opt-in macro
This applies to:
- Functions added in PEP 523
- PyCode_New, PyCode_NewWithPosOnlyArgs
- Ideally anything documented as subject to change between minor
releases. (To be kind to users, if something is added later we should
again have one release of compiler warnings before requiring the opt-in.
Unless that API just changed and users would get errors anyway.)
(Technically, this proposal needs SC approval -- PEP 387 exception for
PyCode_New*. I'll play by the rules, of course.)
On 06. 04. 22 17:21, Nick Coghlan wrote:
On Wed, 6 Apr 2022, 7:05 am Victor Stinner, <vstin...@python.org
<mailto:vstin...@python.org>> wrote:
On Sun, Apr 3, 2022 at 3:29 PM Nick Coghlan <ncogh...@gmail.com
<mailto: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/
_______________________________________________
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/ELBMRSGLBJ6LBMA4DMEOFZ2LQCWAGTGP/
Code of Conduct: http://python.org/psf/codeofconduct/
