Petr's compromise

peps/pep-0733.rst

@@ -179,40 +179,25 @@ different subsystems. They need:
 * It would be nice to have an ABI that can be shared
   across Python implementations.
 
-Alternative APIs
-----------------
+Alternative APIs and Binding Generators
+---------------------------------------
 
 There are several projects that implement alternatives to the
 C API, which offer extension users advantanges over programming
 directly with the C API. These APIs are implemented with the
 C API, and in some cases by using CPython internals.
-Examples are
-`HPy <https://hpyproject.org>`__ and
-`pythoncapi-compat <https://pythoncapi-compat.readthedocs.io/en/latest/>`__.
-CPython's DSL for parsing function arguments, the
-`Argument Clinic <https://devguide.python.org/development-tools/clinic/>`__,
-can also be seen as belonging to this category of stakeholders.
-
-Such systems need minimal building blocks for accessing CPython
-efficiently. They don't necessarily need an ergonomic API, because
-they typically generate code that is not intended to be read
-by humans. But they do need it to be comprehensive enough so that
-they don't need to access internals, without sacrificing performance.
-
-These tools might also benefit from a choice between a more stable
-and a more performant (possibly lower-level) API. Their users could
-then decide whether they can afford to regenerate the code often or
-trade some performance for more stability and less maintenance work.
 
+There are also libraries that create bindings between Python and
+other object models, paradigms or languages.
 
-Binding Generators
-------------------
+There is overlap between these categories: binding generators
+usually provide alternative APIs, and vice versa.
 
-Libraries that create bindings between Python and other object models,
-paradigms or languages, such as
+Examples are
 `Cython <https://cython.org>`__,
 `cffi <https://cffi.readthedocs.io/>`__,
-`pybind11 <https://pybind11.readthedocs.io/en/stable/>`__ for C++11,
+`pybind11 <https://pybind11.readthedocs.io/en/stable/>`__ and
+`nanobind <https://github.com/wjakob/nanobind>`__ for C++,
 `PyO3 <https://github.com/PyO3/pyo3>`__ for Rust,
 `PySide <https://pypi.org/project/PySide/>`__ for Qt,
 `PyGObject <https://pygobject.readthedocs.io/en/latest/>`__ for GTK,
@@ -221,8 +206,19 @@ paradigms or languages, such as
 `PyObjC <https://pyobjc.readthedocs.io>`__ for Objective-C,
 `SWIG <https://swig.org/>`__ for C/C++, or
 `Python.NET <https://github.com/pythonnet/pythonnet>`__ for .NET (C#).
+`HPy <https://hpyproject.org>`__ and
+`pythoncapi-compat <https://pythoncapi-compat.readthedocs.io/en/latest/>`__.
+CPython's DSL for parsing function arguments, the
+`Argument Clinic <https://devguide.python.org/development-tools/clinic/>`__,
+can also be seen as belonging to this category of stakeholders.
+
+Alternative APIs need minimal building blocks for accessing CPython
+efficiently. They don't necessarily need an ergonomic API, because
+they typically generate code that is not intended to be read
+by humans. But they do need it to be comprehensive enough so that
+they can avoid accessing internals, without sacrificing performance.
 
-They need to:
+Binding generators often need to:
 
 * Create custom objects (e.g. function/module objects
   and traceback entries) that match the behavior of equivalent
@@ -237,6 +233,12 @@ They need to:
   semantics, virtual multiple inheritance, 1-based indexing, super-long
   inheritance chains, goroutines, channels, etc.).
 
+These tools might also benefit from a choice between a more stable
+and a more performant (possibly lower-level) API. Their users could
+then decide whether they can afford to regenerate the code often or
+trade some performance for more stability and less maintenance work.
+
+
 Strengths of the C API
 ======================