diff --git a/pep-0689.rst b/pep-0689.rst index 67eb6f801f8..adaaeef76c0 100644 --- a/pep-0689.rst +++ b/pep-0689.rst @@ -1,5 +1,5 @@ PEP: 689 -Title: Semi-stable C API tier +Title: Unstable C API tier Author: Petr Viktorin Status: Draft Type: Standards Track @@ -13,7 +13,7 @@ Post-History: `27-Apr-2022 `, and requires deprecation warnings before changes - Private (internal) API, which can change at any time. -We need a tier between Public and Private to accommodate tools like -advanced debuggers and JIT compilers, which need access to CPython -internals but assume the C-API they use does not change in patch releases. +Tools requring access to CPython internals (e.g. advanced +debuggers and JIT compilers) are often built for minor series releases +of CPython, and assume that the C-API internals used do not change +in patch releases. To support these tools, we need a tier between the +Public and Private C-API, with guarantees on stability throughout +the minor-series release. Setting Stability Expectations @@ -49,7 +52,7 @@ in patch releases: - Patch releases only contain bugfixes, which are unlikely to change the API. -Semi-stable API will make the stability expectations more explicit. +Unstable API will make the stability expectations more explicit. It will also hopefully encourage existing users of the private API to reach out to python-dev, so we can expose, standardize and test an API @@ -70,16 +73,17 @@ convention are unlikely to check if underscored functions they are changing are documented and used outside CPython itself. This proposal brings us a bit closer to reserving underscores -only for truly private, unstable, hands-off API. +only for truly internal, private, hands-off API. Warning about API that is changed often --------------------------------------- The ``PyCode_New()`` family is an example of functions that are -documented as unstable, and also often change in practice. +documented as unstable (“Calling [it] directly can bind you to a precise +Python version”), and also often change in practice. -Moving it to the semi-stable tier will make its status obvious even +Moving it to the unstable tier will make its status obvious even to people who don't read the docs carefully enough, and will make it hard to use accidentally. @@ -90,16 +94,16 @@ Changes during the Beta period Since the API itself can change continuously up until Beta 1 (feature freeze) of a minor version, major users of this API are unlikely to test Alpha releases and provide feedback. -It is very difficult to determine what needs to be exposed as semi-stable. +It is very difficult to determine what needs to be exposed as unstable. -Additions to the semi-stable tier will count as *stabilization*, +Additions to the unstable tier will count as *stabilization*, and will be allowed up to Release Candidate 1. Specification ============= -Several functions and types (“APIs”) will be moved to a new *semi-stable* tier. +Several functions and types (“APIs”) will be moved to a new *unstable* tier. They will be expected to stay stable across patch releases, but may change or be removed without warning in minor releases (3.x.0), @@ -109,20 +113,20 @@ When they change significantly, code that uses them should no longer compile (e.g. arguments should be added/removed, or a function should be renamed, but the semantic meaning of an argument should not change). -Their definitions will be moved to a new directory, ``Include/semistable/``, +Their definitions will be moved to a new directory, ``Include/unstable/``, and will be included from ``Python.h``. From Python 3.12 on, these APIs will only be usable when the -``Py_USING_SEMI_STABLE_API`` macro is defined. +``Py_USING_UNSTABLE_API`` macro is defined. CPython will only define the macro for building CPython itself (``Py_BUILD_CORE``). -To make transition to semi-stable API easier, -in Python 3.11 the APIs will be available without ``Py_USING_SEMI_STABLE_API`` +To make transition to unstable API easier, +in Python 3.11 the APIs will be available without ``Py_USING_UNSTABLE_API`` defined. In this case, using them will generate a deprecation warning on compilers that support ``Py_DEPRECATED``. -A similar deprecation period will be used when making more APIs semi-stable +A similar deprecation period will be used when making more APIs unstable in the future: - When moving from public API, the deprecation period should follow Python's @@ -137,14 +141,14 @@ Leading underscores will be removed from the names of the moved APIs. The old underscored name of a renamed API will be available (as an alias using ``#define``) at least until that API changes. -The semi-stable C-API tier and ``Py_USING_SEMI_STABLE_API`` will be documented, -and documentation of each semi-stable API will be updated. +The unstable C-API tier and ``Py_USING_UNSTABLE_API`` will be documented, +and documentation of each unstable API will be updated. Adjustments during Beta periods ------------------------------- -New APIs can be added to the semi-stable tier, and private APIs can be moved +New APIs can be added to the unstable tier, and private APIs can be moved to it, up to the first release candidate of a new minor version. Consensus on the ``capi-sig`` or ``python-dev`` is needed in the Beta period. @@ -152,10 +156,10 @@ In the Beta period, no API may be moved to more private tier, e.g. what is public in Beta 1 must stay public until the final release. -Initial semi-stable API ------------------------ +Initial unstable API +-------------------- -The following API will initially be semi-stable. +The following API will initially be unstable. The set may be adjusted for 3.11. Code object constructors: @@ -211,9 +215,7 @@ This is outside the scope of the PEP. Open Issues =========== -- “Semi-stable” is not a perfect name. - -- The exact set of exposed API may change. +The exact set of exposed API may change. Copyright