diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 82050845237bbdf..320f1e6dbcc4ea8 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -806,7 +806,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) @@ -814,7 +814,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 a697f6cd3edd900..4817da41e3e2174 100644 --- a/Doc/c-api/stable.rst +++ b/Doc/c-api/stable.rst @@ -25,19 +25,19 @@ are private API that can change without notice even in patch releases. Stable Application Binary Interface =================================== +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. + +.. _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 @@ -57,6 +57,19 @@ 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. + On Windows, extensions that use the Stable ABI should be linked against ``python3.dll`` rather than a version-specific library such as ``python39.dll``. @@ -101,9 +114,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. @@ -136,9 +149,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 @@ -147,12 +160,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 c2903b9ec3285bf..304cc31575b1dc8 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -318,7 +318,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 `. .. _METH_FASTCALL-METH_KEYWORDS: diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index 01d7fc4dc1ecf18..a7ca19677134d09 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 @@ -301,7 +301,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 *PyType_Slot.pfunc diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 62711802a783ae4..8b662ceac84e7bd 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -2082,7 +2082,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 146511b9e3658a4..686252d808653d1 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1084,7 +1084,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 0362fa6c6854435..732fd6f993b722f 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 427953e0077aab6..660c4a464b49216 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -740,6 +740,12 @@ The :mod:`test.support` module defines the following functions: Decorator for only running the test if :data:`HAVE_DOCSTRINGS`. +.. decorator:: requires_limited_api + + Decorator for only running the test if :ref:`Limited C API ` + is available. + + .. decorator:: cpython_only Decorator for tests only applicable to CPython. diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 175b9e5b2ab5f73..3d43d06e0293a2c 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -2654,7 +2654,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/Lib/test/test_stable_abi_ctypes.py b/Lib/test/test_stable_abi_ctypes.py index 18c85061ca08932..288b9eaa58e8132 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/Misc/NEWS.d/3.11.0a1.rst b/Misc/NEWS.d/3.11.0a1.rst index fe21d9b5e660936..46c65300abf2c26 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 d4ae7dc30b04b17..3f9a66298faa1b7 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 b1763b57d913c2e..a076e7149800743 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 50e7a9607bec95a..690262eea6b64e2 100755 --- a/PC/python3dll.c +++ b/PC/python3dll.c @@ -1,4 +1,3 @@ - /* Re-export stable Python ABI */ /* Generated by Tools/scripts/stable_abi.py */ diff --git a/Tools/scripts/stable_abi.py b/Tools/scripts/stable_abi.py index f5a9f8d2dd617b0..aa68c95b7c702b7 100755 --- a/Tools/scripts/stable_abi.py +++ b/Tools/scripts/stable_abi.py @@ -183,7 +183,7 @@ def _decorator(func): def gen_python3dll(manifest, args, outfile): """Generate/check the source for the Windows stable ABI library""" write = partial(print, file=outfile) - write(textwrap.dedent(r""" + write(textwrap.dedent(r"""\ /* Re-export stable Python ABI */ /* Generated by Tools/scripts/stable_abi.py */ @@ -265,8 +265,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 """ @@ -339,7 +339,7 @@ def test_windows_feature_macros(self): 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()