From bae415ad02c79cf3a2eec4aa6969221a12e6716f Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Tue, 6 Jun 2023 10:40:32 +0200 Subject: gh-102304: doc: Add links to Stable ABI and Limited C API (#105345) * Add "limited-c-api" and "stable-api" references. * Rename "stable-abi-list" reference to "limited-api-list". * Makefile: Document files regenerated by "make regen-limited-abi" * Remove first empty line in generated files: - Lib/test/test_stable_abi_ctypes.py - PC/python3dll.c --- Doc/c-api/exceptions.rst | 4 +-- Doc/c-api/stable.rst | 55 ++++++++++++++++++++++-------------- Doc/c-api/structures.rst | 2 +- Doc/c-api/type.rst | 4 +-- Doc/c-api/typeobj.rst | 2 +- Doc/c-api/unicode.rst | 2 +- Doc/howto/isolating-extensions.rst | 2 +- Doc/library/test.rst | 2 +- Doc/whatsnew/3.11.rst | 2 +- Doc/whatsnew/3.12.rst | 2 +- Lib/test/test_stable_abi_ctypes.py | 3 +- Makefile.pre.in | 5 ++++ Misc/NEWS.d/3.11.0a1.rst | 2 +- Misc/NEWS.d/3.11.0a2.rst | 2 +- Modules/_testcapi_feature_macros.inc | 2 +- PC/python3dll.c | 1 - Tools/build/stable_abi.py | 8 +++--- 17 files changed, 58 insertions(+), 42 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 1694aa2..a24ecac 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -887,7 +887,7 @@ because the :ref:`call protocol ` takes care of recursion handling. depth limit. .. versionchanged:: 3.9 - This function is now also available in the limited API. + This function is now also available in the :ref:`limited API `. .. c:function:: void Py_LeaveRecursiveCall(void) @@ -895,7 +895,7 @@ because the :ref:`call protocol ` takes care of recursion handling. *successful* invocation of :c:func:`Py_EnterRecursiveCall`. .. versionchanged:: 3.9 - This function is now also available in the limited API. + This function is now also available in the :ref:`limited API `. Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires special recursion handling. In addition to protecting the stack, diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst index 3721fc0..df01e73 100644 --- a/Doc/c-api/stable.rst +++ b/Doc/c-api/stable.rst @@ -20,9 +20,9 @@ but will need to be compiled separately for 3.9.x and 3.10.x. There are two tiers of C API with different stability exepectations: -- *Unstable API*, may change in minor versions without a deprecation period. - It is marked by the ``PyUnstable`` prefix in names. -- *Limited API*, is compatible across several minor releases. +- :ref:`Unstable API `, may change in minor versions without + a deprecation period. It is marked by the ``PyUnstable`` prefix in names. +- :ref:`Limited API `, is compatible across several minor releases. When :c:macro:`Py_LIMITED_API` is defined, only this subset is exposed from ``Python.h``. @@ -55,19 +55,15 @@ CPython development and spend extra effort adjusting to changes. Stable Application Binary Interface =================================== +.. _limited-c-api: + +Limited C API +------------- + Python 3.2 introduced the *Limited API*, a subset of Python's C API. Extensions that only use the Limited API can be compiled once and work with multiple versions of Python. -Contents of the Limited API are :ref:`listed below `. - -To enable this, Python provides a *Stable ABI*: a set of symbols that will -remain compatible across Python 3.x versions. The Stable ABI contains symbols -exposed in the Limited API, but also other ones – for example, functions -necessary to support older versions of the Limited API. - -(For simplicity, this document talks about *extensions*, but the Limited API -and Stable ABI work the same way for all uses of the API – for example, -embedding Python.) +Contents of the Limited API are :ref:`listed below `. .. c:macro:: Py_LIMITED_API @@ -87,6 +83,23 @@ embedding Python.) You can also define ``Py_LIMITED_API`` to ``3``. This works the same as ``0x03020000`` (Python 3.2, the version that introduced Limited API). + +.. _stable-abi: + +Stable ABI +---------- + +To enable this, Python provides a *Stable ABI*: a set of symbols that will +remain compatible across Python 3.x versions. + +The Stable ABI contains symbols exposed in the :ref:`Limited API +`, but also other ones – for example, functions necessary to +support older versions of the Limited API. + +(For simplicity, this document talks about *extensions*, but the Limited API +and Stable ABI work the same way for all uses of the API – for example, +embedding Python.) + On Windows, extensions that use the Stable ABI should be linked against ``python3.dll`` rather than a version-specific library such as ``python39.dll``. @@ -131,9 +144,9 @@ Limited API Caveats ------------------- Note that compiling with ``Py_LIMITED_API`` is *not* a complete guarantee that -code conforms to the Limited API or the Stable ABI. ``Py_LIMITED_API`` only -covers definitions, but an API also includes other issues, such as expected -semantics. +code conforms to the :ref:`Limited API ` or the :ref:`Stable ABI +`. ``Py_LIMITED_API`` only covers definitions, but an API also +includes other issues, such as expected semantics. One issue that ``Py_LIMITED_API`` does not guard against is calling a function with arguments that are invalid in a lower Python version. @@ -166,9 +179,9 @@ Platform Considerations ======================= ABI stability depends not only on Python, but also on the compiler used, -lower-level libraries and compiler options. For the purposes of the Stable ABI, -these details define a “platform”. They usually depend on the OS -type and processor architecture +lower-level libraries and compiler options. For the purposes of +the :ref:`Stable ABI `, these details define a “platform”. They +usually depend on the OS type and processor architecture It is the responsibility of each particular distributor of Python to ensure that all Python versions on a particular platform are built @@ -177,12 +190,12 @@ This is the case with Windows and macOS releases from ``python.org`` and many third-party distributors. -.. _stable-abi-list: +.. _limited-api-list: Contents of Limited API ======================= -Currently, the Limited API includes the following items: +Currently, the :ref:`Limited API ` includes the following items: .. limited-api-list:: diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 7ce3578..766f881 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -288,7 +288,7 @@ There are these calling conventions: .. versionchanged:: 3.10 - ``METH_FASTCALL`` is now part of the stable ABI. + ``METH_FASTCALL`` is now part of the :ref:`stable ABI `. .. data:: METH_FASTCALL | METH_KEYWORDS diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index 89cd743..bf261b9 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -42,7 +42,7 @@ Type Objects Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily meant for use with ``Py_LIMITED_API``; the individual flag bits are guaranteed to be stable across Python releases, but access to - :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API. + :c:member:`~PyTypeObject.tp_flags` itself is not part of the :ref:`limited API `. .. versionadded:: 3.2 @@ -472,7 +472,7 @@ The following functions and structs are used to create .. versionchanged:: 3.11 :c:member:`~PyBufferProcs.bf_getbuffer` and :c:member:`~PyBufferProcs.bf_releasebuffer` are now available - under the limited API. + under the :ref:`limited API `. .. c:member:: void *pfunc diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 0584989..c6e783a 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -2150,7 +2150,7 @@ This results in types that are limited relative to types defined in Python: include any subinterpreter-specific state. Also, since :c:type:`PyTypeObject` is only part of the :ref:`Limited API -` as an opaque struct, any extension modules using static types must be +` as an opaque struct, any extension modules using static types must be compiled for a specific Python minor version. diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index e3c6ee4..0db052d 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -994,7 +994,7 @@ These are the UTF-8 codec APIs: The return type is now ``const char *`` rather of ``char *``. .. versionchanged:: 3.10 - This function is a part of the :ref:`limited API `. + This function is a part of the :ref:`limited API `. .. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode) diff --git a/Doc/howto/isolating-extensions.rst b/Doc/howto/isolating-extensions.rst index 0262054..8adb85f 100644 --- a/Doc/howto/isolating-extensions.rst +++ b/Doc/howto/isolating-extensions.rst @@ -461,7 +461,7 @@ Module State Access from Slot Methods, Getters and Setters .. After adding to limited API: - If you use the :ref:`limited API , + If you use the :ref:`limited API `, you must update ``Py_LIMITED_API`` to ``0x030b0000``, losing ABI compatibility with earlier versions. diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 20f633b..1b045c7 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -803,7 +803,7 @@ The :mod:`test.support` module defines the following functions: .. decorator:: requires_limited_api - Decorator for only running the test if :ref:`Limited C API ` + Decorator for only running the test if :ref:`Limited C API ` is available. diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index a734233..4519413 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -2650,7 +2650,7 @@ Removed * :c:func:`PyMarshal_WriteObjectToString` * the ``Py_MARSHAL_VERSION`` macro - These are not part of the :ref:`limited API `. + These are not part of the :ref:`limited API `. (Contributed by Victor Stinner in :issue:`45474`.) diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index 2a90f81..af62602 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -1580,7 +1580,7 @@ New Features (Contributed by Petr Viktorin in :gh:`103509`.) -* Added the new limited C API function :c:func:`PyType_FromMetaclass`, +* Added the new :ref:`limited C API ` function :c:func:`PyType_FromMetaclass`, which generalizes the existing :c:func:`PyType_FromModuleAndSpec` using an additional metaclass argument. (Contributed by Wenzel Jakob in :gh:`93012`.) diff --git a/Lib/test/test_stable_abi_ctypes.py b/Lib/test/test_stable_abi_ctypes.py index 60ad360..6898367 100644 --- a/Lib/test/test_stable_abi_ctypes.py +++ b/Lib/test/test_stable_abi_ctypes.py @@ -1,5 +1,4 @@ - -# Generated by Tools/scripts/stable_abi.py +# Generated by Tools/build/stable_abi.py """Test that all symbols of the Stable ABI are accessible using ctypes """ diff --git a/Makefile.pre.in b/Makefile.pre.in index ae428eb..9cc3164 100644 --- a/Makefile.pre.in +++ b/Makefile.pre.in @@ -1309,6 +1309,11 @@ check-abidump: all .PHONY: regen-limited-abi regen-limited-abi: all + # Regenerate files using using Tools/build/stable_abi.py: + # - Doc/data/stable_abi.dat + # - Lib/test/test_stable_abi_ctypes.py + # - Modules/_testcapi_feature_macros.inc + # - PC/python3dll.c $(RUNSHARED) ./$(BUILDPYTHON) $(srcdir)/Tools/build/stable_abi.py --generate-all $(srcdir)/Misc/stable_abi.toml ############################################################################ diff --git a/Misc/NEWS.d/3.11.0a1.rst b/Misc/NEWS.d/3.11.0a1.rst index ea96206..2f40252 100644 --- a/Misc/NEWS.d/3.11.0a1.rst +++ b/Misc/NEWS.d/3.11.0a1.rst @@ -4980,7 +4980,7 @@ Removed documentation for the removed ``PyParser_*`` C API. .. nonce: fy0AXK .. section: C API -The list in :ref:`stable-abi-list` now shows the public name +The list in :ref:`limited-api-list` now shows the public name :c:struct:`PyFrameObject` rather than ``_frame``. The non-existing entry ``_node`` no longer appears in the list. diff --git a/Misc/NEWS.d/3.11.0a2.rst b/Misc/NEWS.d/3.11.0a2.rst index 225bd61..cf26137 100644 --- a/Misc/NEWS.d/3.11.0a2.rst +++ b/Misc/NEWS.d/3.11.0a2.rst @@ -1234,7 +1234,7 @@ defined: * :c:func:`PyMarshal_WriteObjectToString` * the ``Py_MARSHAL_VERSION`` macro -These are not part of the :ref:`limited API `. +These are not part of the :ref:`limited API `. Patch by Victor Stinner. diff --git a/Modules/_testcapi_feature_macros.inc b/Modules/_testcapi_feature_macros.inc index b1763b5..a076e71 100644 --- a/Modules/_testcapi_feature_macros.inc +++ b/Modules/_testcapi_feature_macros.inc @@ -1,4 +1,4 @@ -// Generated by Tools/scripts/stable_abi.py +// Generated by Tools/build/stable_abi.py // Add an entry in dict `result` for each Stable ABI feature macro. diff --git a/PC/python3dll.c b/PC/python3dll.c index f2c0d9d..5665d55 100755 --- a/PC/python3dll.c +++ b/PC/python3dll.c @@ -1,4 +1,3 @@ - /* Re-export stable Python ABI */ /* Generated by Tools/build/stable_abi.py */ diff --git a/Tools/build/stable_abi.py b/Tools/build/stable_abi.py index 42b2dd9..4cd1cd9 100644 --- a/Tools/build/stable_abi.py +++ b/Tools/build/stable_abi.py @@ -183,7 +183,7 @@ def generator(var_name, default_path): def gen_python3dll(manifest, args, outfile): """Generate/check the source for the Windows stable ABI library""" write = partial(print, file=outfile) - content = f""" + content = f"""\ /* Re-export stable Python ABI */ /* Generated by {SCRIPT_NAME} */ @@ -267,8 +267,8 @@ def gen_doc_annotations(manifest, args, outfile): def gen_ctypes_test(manifest, args, outfile): """Generate/check the ctypes-based test for exported symbols""" write = partial(print, file=outfile) - write(textwrap.dedent(''' - # Generated by Tools/scripts/stable_abi.py + write(textwrap.dedent(f'''\ + # Generated by {SCRIPT_NAME} """Test that all symbols of the Stable ABI are accessible using ctypes """ @@ -341,7 +341,7 @@ def gen_ctypes_test(manifest, args, outfile): def gen_testcapi_feature_macros(manifest, args, outfile): """Generate/check the stable ABI list for documentation annotations""" write = partial(print, file=outfile) - write('// Generated by Tools/scripts/stable_abi.py') + write(f'// Generated by {SCRIPT_NAME}') write() write('// Add an entry in dict `result` for each Stable ABI feature macro.') write() -- cgit v0.12