From 58bf1078d68462aceb466d53b60d129dc686a306 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 7 Dec 2021 14:26:54 +0100 Subject: [PATCH 1/4] Add guidelines for changing/removing from the Limited API --- c-api.rst | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/c-api.rst b/c-api.rst index 9198c80cb..047802e14 100644 --- a/c-api.rst +++ b/c-api.rst @@ -101,8 +101,44 @@ No changes that break the Stable ABI are allowed. The Limited API should be defined in ``Include/``, excluding the ``cpython`` and ``internal`` subdirectories. -Guidelines for changing the Limited API ---------------------------------------- + +Guidelines for changing the Limited API, and removing items from it +------------------------------------------------------------------- + +While the *Stable ABI* must not be broken, the existing Limited API can be +changed, and items can be removed from it, if: + +- the Backwards Compatibility Policy (:pep:`387`) is followed, and +- the Stable ABI is not broken -- that is, extensions compiled with + Limited API of older versions of Python continue to work on + newer versions of Python. + +This is tricky to do and requires careful thought. +Some examples: + +- Functions, structs etc. accessed by macros in *any version* of the + Limited API are part of the Stable ABI, even if they are named with + an underscore. They must not be removed and their signature must not change. + (Their implementation may change, though.) +- Structs members cannot be rearranged if they were part of any version of + the Limited API. +- If the Limited API allows users to allocate a struct directly, + its size must not change. +- Exported symbols (functions and data) must continue to be available + as exported symbols. Specifically, a function can only be converted + to a `static inline` function (or macro) if Python also continues to + provide the actual function. + For an example, see the ``Py_NewRef`` `macro`_ and `redefinition`_ in 3.10. + +.. _macro: https://github.com/python/cpython/blob/3.10/Objects/object.c#L2298-L2308 +.. _redefinition: https://github.com/python/cpython/blob/main/Include/object.h#L603-L606 + +It is possible to remove items marked as part of the Stable ABI, but only +if there was no way to use them in any past version of the Limited API. + + +Guidelines for adding to the Limited API +---------------------------------------- - Guidelines for the general :ref:`public-capi` apply. From bae3bb1412b047800eb9a404f7c1e078f590ee46 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 7 Dec 2021 15:42:45 +0100 Subject: [PATCH 2/4] Link to a tag rather than a branch --- c-api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/c-api.rst b/c-api.rst index 047802e14..19f6605a2 100644 --- a/c-api.rst +++ b/c-api.rst @@ -130,8 +130,8 @@ Some examples: provide the actual function. For an example, see the ``Py_NewRef`` `macro`_ and `redefinition`_ in 3.10. -.. _macro: https://github.com/python/cpython/blob/3.10/Objects/object.c#L2298-L2308 -.. _redefinition: https://github.com/python/cpython/blob/main/Include/object.h#L603-L606 +.. _macro: https://github.com/python/cpython/blob/v3.10.1/Include/object.h#L591-L595 +.. _redefinition: https://github.com/python/cpython/blob/v3.10.1/Objects/object.c#L2298-L2308 It is possible to remove items marked as part of the Stable ABI, but only if there was no way to use them in any past version of the Limited API. From b7f731ff0749468d7e78fb9aff3b3cfeafe2bb90 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 14 Dec 2021 14:06:18 +0100 Subject: [PATCH 3/4] Add more backticks --- c-api.rst | 2 +- conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/c-api.rst b/c-api.rst index 19f6605a2..5e629005d 100644 --- a/c-api.rst +++ b/c-api.rst @@ -126,7 +126,7 @@ Some examples: its size must not change. - Exported symbols (functions and data) must continue to be available as exported symbols. Specifically, a function can only be converted - to a `static inline` function (or macro) if Python also continues to + to a ``static inline`` function (or macro) if Python also continues to provide the actual function. For an example, see the ``Py_NewRef`` `macro`_ and `redefinition`_ in 3.10. diff --git a/conf.py b/conf.py index 468fe1f17..f52435ea6 100644 --- a/conf.py +++ b/conf.py @@ -93,7 +93,7 @@ # -- Options for HTML output --------------------------------------------------- # Use the upstream python-docs-theme -html_theme = 'furo' +#html_theme = 'furo' html_theme_options = {} From e751783e500d0418adda50aecd138d2c74a57c7f Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 14 Dec 2021 14:33:21 +0100 Subject: [PATCH 4/4] Undo unrelated change --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index f52435ea6..468fe1f17 100644 --- a/conf.py +++ b/conf.py @@ -93,7 +93,7 @@ # -- Options for HTML output --------------------------------------------------- # Use the upstream python-docs-theme -#html_theme = 'furo' +html_theme = 'furo' html_theme_options = {}