since it is very relevant to the topic of this mailing list, I'd like to
announce the new HPy blog (and its first post):
Any feedback (both on the blog post and on hpy itself) is appreciated!
After the e-mails from the previous week, I set up a call with Eric to
sync on Limited API/Stable ABI issues.
The higher-bandwidth (and more emotion-friendly) medium worked great for
us, but unfortunately, everyone else was excluded.
Here are some rather unstructued notes from my point of view. They might
be good discussion starters :)
Please read PEP 652 “Maintaining the Stable ABI” for my thoughts, plans
and rationales for the short term.
For the long term, there are some more vague plans and ideas:
There's not a 1:1 mapping between “Limited API”, “Stable ABI” and
“C-API, the Good Parts™”, *but* unless you're deep in this space, it
makes sense to conflate them. I aim to make them converge.
I intend to focus my CPython time on Limited API/Stable ABI for the
next... few years, probably.
The work I'm doing (extension isolation & now stable ABI) is similar to
the subinterpreters effort in several ways:
- They are both incomplete, but useful *today* for some limited cases,
and have lots of potential
- They need long-term effort, but most of the many steps are useful in
their own right.
In addition to the use cases in PEP 652, the stable ABI *should* ideally
be useful for:
- bindings for non-Python software, where shoehorning Python into the
buildsystem is not straightforward and building for several Python
versions at once is not practical. Also, raw speed tends to not matter.
- GUI apps, whose scripting plugins could use any Python the
user/scripter has installed. (Think Blender, if it was a smaller project
that couldn't afford to bundle Python.)
And here's some more concrete stuff. (Remember that these are still
Static `PyObject` and `PyObject*` are the main thing in the Limited API
that's blocking subinterpreters. We see no other blockers.
A possible way to solve this is to make isolated subinterpreters support
*opt-in* for extension modules:
- Introduce a macro similar to the old PY_SSIZE_T_CLEAN that removes the
problematic items from the headers.
- This macro will give you access to a flag you can use to tell the
runtime the extension is subinterp-safe.
- Python will support both the current, GIL-sharing subinterpreters, and
isolated subinterpreters. (All signs say implementing this will be easy,
relative to making subinterpreters always isolated and breaking existing
- The macro will affect both the full API and the limited subset.
PEP 384  introduced the limited API (AKA Py_LIMITED_API) and stable
ABI. The main objective:
"Extension modules and applications embedding Python can work with
different feature releases as long as they restrict themselves to this
This goal is completely reasonable, particularly in 2009.
Furthermore, even though there are things we would have done
differently, in hindsight, the limited API mostly reaches that goal.
However, is it relevant in the current ecosystem? The burden on
extension maintainers to build for each Python release is much lower
now. At the same time, the maintenance burden of the current limited
API (especially ABI compatibility) is relatively high, especially for
our group of volunteers. It also makes some improvements harder. 
So the question is: Is the stable ABI still worth it? If not, what
would be the impact of abandoning it?
Note that the limited API is fine on its own, though I'll argue that
we should re-focus it (PEP 652?) and use a new name (to differentiate
from the API tied to the stable ABI). 
(Sorry for all the posts related to the limited API. It's been a pain
point for me lately.)
Would it be feasible to have distinct header files that contain only
the limited API (perhaps in Include/limited)?
The files could be auto-generated to avoid duplicated code (like other
files in the repo), though the nature of the limited API suggests the
only future changes would be opt-in ones, which should be manual
anyway. If there is no auto-generation then there should be a test to
ensure the limited API matches the corresponding public API
definitions exactly. Either way, Include/Python.h would have to be
updated to switch to Include/limited if Py_LIMITED_API is defined.
Also, FWIW, Include/limited would effectively fill the role of the
manifest described in PEP 652. 
With Include/limited, would we still need Include/cpython? I suppose
we could keep only public API in Include/*.h and keep
"private-but-not-internal" API in Include/cpython (or rename it to
Include/private or Include/unstable).
Finally, is the separation of headers by access "rings" worth it? On
the one hand it makes the divisions explicit and obvious and helps
avoid API leaking out accidentally. We'd had success in that regard
with Include/internal and Include/cpython. On the other hand, the
divisions mean related API is often spread out across multiple files
(albeit with matching names), where otherwise those would all be in
Anway, this is something that came to mind as I was writing up my
other posts to this list.
The stable ABI (ergo the limited API) is consistently problematic when
it comes to isolating subinterpreters. For example, there are ~120
PyObject exposed by the limited API, which is difficult to deal with
in terms of multiple interpreters. (See
https://bugs.python.org/issue43503.) After struggling with this
problem for a while I had an idea (which I'm pretty sure is just me
remembering something someone suggested at some point):
Let's mandate that extensions targeting the limited API cannot be
imported in subinterpreters. If we have that constraint in place then
nearly all the complex problems go away, since we have substantially
more flexibility to adapt the public API. (We'd still be careful
about API compatibility but wouldn't have to worry about ABI
compatibility.) Note that such extensions could still *create*
There are two concerns I have that counter the benefits of the idea:
* there may be existing extensions using the limited API *and* subinterpreters
* what if we want to allow "limited" extensions in subinterpreters in
As to the first one, I don't think it's a problem. Given the small
sets of people using either of the features, I expect the intersection
of those sets will be empty. That said, it would be worth looking at
all the extensions we know use subinterpreters, just to be sure.
That leaves the possibility of future support for importing limited
API extensions in subinterpreters. At the point we allow them, all
the complex problems come back and would have to be dealt with. Here
are some possible solutions:
* deal with the problems directly (if possible); the status quo
* introduce a "limited API 2.0"
* specify that a subset of the limited API that extensions must target
in order to support for subinterpreters (i.e.
Any of these could be done now, later, or only once the support is
needed (or never if it never comes up). My preference is to not worry
about it for now.
Maybe the limited API + subinterpreters would never be an issue (so
doing any of them now would be a waste of effort). I don't know. I
bring it up because I recall talk of Cython supporting/targeting the
limited API. Also, I hope subinterpreters become a widely used
feature and extensions that use the limited API would want to run
## What Would Need to be Done?
* add the restriction to the docs
* update the import machinery to raise ImportError if an extension
targets the limited API
* how can the import machinery identify such modules?
* we may end up doing this relative to PEP 489 anyway
Anyway, your thoughts on the proposal would be helpful.
In PEP 384  it says:
"This PEP proposes to define a stable set of API functions which
are guaranteed to be available for the lifetime of Python 3,
and which will also remain binary-compatible across versions."
Thus there are two parts that the PEP ties together closely: the
limited API (AKA Py_LIMITED_API) and the stable ABI. For the most
part, the API stability goal was driven by ABI stability.
Lately the binary compatibility part has seemed less important (as
implied by sprint/list discussions), while the limited API has begun
to stand on its own conceptually. On top of that, the limited API has
started to take on a second, distinct-but-similar role: "an
approximation of the minimal future API" or "the basic API that most
extensions should stick to". In that case strict compatibility is
desirable but not required (like it is with the stable ABI) or quite
Do we want a stand-alone public API that is focused on a minimal set
and extra resilient to future changes (but with less strict
compatibility guarantees)? If so then we should be deliberate about
* introduce a different macro (Py_BASIC_API? Py_MINIMAL_API?)
* assess which parts of the limited API to keep in this new API (and
what to add from the full API)
* decide if there are any future-looking gaps we could fill (e.g. with macros)
* document the inclusions explicitly
* make (relative) compatibility guarantees clear
This will provide what folks are after (mostly) without incurring the
maintenance cost of binary compatibility. It seems like there's a lot
of overlap here with PEP 652, though I'm suggesting a distinct API.
Regardless, I think Py_LIMITED_API should preserve its strong
association with the stable ABI.
Finally, is such a "minimal" API worth it? Is the current full
"public" API sufficient (and projects like HPy can be the
less-constrained, future-oriented adaptations)? Would a minimal API
mean we'd be more free to make breaking changes in the rest of the
On Wed, Mar 17, 2021 at 12:08 PM Barry Warsaw <barry(a)python.org> wrote:
> Perhaps an even deeper and more provocative question is whether extension writers should be writing against *any* C API?
> Decoupling extensions from the concrete C API could give the interpreter more flexibility for internal change.
Good point! I'm totally on board. :) I suppose that would be a
Python 4.0 event and we could have no stable ABI for 4.0. (PEP 384
explicitly applies to Python 3.)
As Victor mentioned earlier today, there is work in progress on documenting the C API hierarchy: https://github.com/python/cpython/pull/24884
I've received valuable reviews from Victor and Guido, but I'd like to have a few more eyes on it.
Most of the text is stolen from bpo-43416, bpo-35134, PEP 384, and PEP 652. I've tried to put it together as concise as possible.
Any kind of feeback is highly appreciated.