diff --git a/peps/pep-0809.rst b/peps/pep-0809.rst index 39c14a6c383..f9c2a19175a 100644 --- a/peps/pep-0809.rst +++ b/peps/pep-0809.rst @@ -157,6 +157,18 @@ are not permitted. That is, the APIs to detect whether a particular behaviour is expected on the current Python release must have been available on all earlier releases that support the ABI. +Accidental changes that occur in releases should be reverted as soon as +discovered, ideally without breaking regular compatibility rules. However, it is +better to have ``3.x.1`` fix a Stable ABI issue introduced in ``3.x.0`` rather +than to leave it present until ``3.y.0``. + +Historically, we have used clever C preprocessor constructs to try and preserve +both source and binary-level compatibility, for example, by selecting macro or +inline functions automatically. Under this new scheme, these should be avoided +in favour of a much more direct relationship between the documented C API and +the shape of the ABI. Changes can be scheduled for the next version of the ABI +if they are important enough to be made. + Opaque PyObject --------------- @@ -252,6 +264,15 @@ same operation, but less efficiently. The final result of this example is a single extension module that is binary compatible with *all* releases supporting ``abi2026`` but is more efficient when running against newer releases of Python. +Additionally, ``PyInterface_Get(void *intf)`` will return a global struct, for +APIs that are not specific to a particular object. It is intended that the two +"get" APIs will support different interfaces, even though they share the +namespace. APIs provided through the struct for a global interface will almost +always require a runtime or interpreter parameter, which is unnecessary when an +object is available. Further, ``PyInterface_Get`` will not require a Python +thread to be attached (a.k.a. the GIL is not required), though any functions +provided by an interface may require it. + Overview complete, here is the full specification of each new API: .. code-block:: c @@ -259,6 +280,9 @@ Overview complete, here is the full specification of each new API: // Abstract API to request an interface for an object (or type). PyAPI_FUNC(int) PyObject_GetInterface(PyObject *obj, void *intf); + // API to request a global interface + PyAPI_FUNC(int) PyInterface_Get(void *intf); + // API to release an interface. PyAPI_FUNC(int) PyInterface_Release(void *intf);