PEP 689: Rename to "Unstable C API tier" (#2576)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
This commit is contained in:
Petr Viktorin
GitHub
parent
f1be4a36a2
commit
5232fda0ab
54
pep-0689.rst
54
pep-0689.rst
|
|
@ -1,5 +1,5 @@
|
|||
PEP: 689
|
||||
Title: Semi-stable C API tier
|
||||
Title: Unstable C API tier
|
||||
Author: Petr Viktorin <encukou@gmail.com>
|
||||
Status: Draft
|
||||
Type: Standards Track
|
||||
|
|
@ -13,7 +13,7 @@ Post-History: `27-Apr-2022 <https://mail.python.org/archives/list/python-dev@pyt
|
|||
Abstract
|
||||
========
|
||||
|
||||
Some functions and types of the C-API are designated *semi-stable*,
|
||||
Some functions and types of the C-API are designated *unstable*,
|
||||
meaning that they will not change in patch (bugfix/security) releases,
|
||||
but may change between minor releases (e.g. between 3.11 and 3.12) without
|
||||
deprecation warnings.
|
||||
|
|
@ -29,9 +29,12 @@ The Python C-API is currently divided into `three tiers <https://devguide.python
|
|||
<387>`, 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue