Skip to content

PEP 689: Rename to "Unstable C API tier" #2576

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 4, 2022
Merged

PEP 689: Rename to "Unstable C API tier" #2576

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
26715b0
PEP 689: Rename to "Unstable C API tier"
encukou May 3, 2022
57959e5
Improve wording in Rationale as suggested by AA-Turner
encukou May 3, 2022
94f8ee8
Update pep-0689.rst
encukou May 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 28 additions & 26 deletions pep-0689.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
PEP: 689
Title: Semi-stable C API tier
Title: Unstable C API tier
Author: Petr Viktorin <[email protected]>
Status: Draft
Type: Standards Track
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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.
Comment on lines +99 to 100
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence now reads oddly, although it makes sense on the second reading (I think!)

A

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the terminology is not perfect -- there's something more unstable than the unstable API.
But as discussed in the thread, it's better than “semi-stable”.



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),
Expand All @@ -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
Expand All @@ -137,25 +141,25 @@ 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.

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:
Expand Down Expand Up @@ -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
Expand Down