From 5abc68101992043b08cd260053ea17fddeb62ab4 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 14 May 2021 05:28:08 -0700 Subject: [PATCH] Reword paragraph on specific value for Py_LIMITED_API (GH-26101) (GH-26123) (cherry picked from commit ddd30b2dd207c3c963874f0644cdff2ee5989575) Co-authored-by: Petr Viktorin --- Doc/c-api/stable.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst index 2f67b097eae975..4ae20e93e36785 100644 --- a/Doc/c-api/stable.rst +++ b/Doc/c-api/stable.rst @@ -41,22 +41,22 @@ embedding Python.) .. c:macro:: Py_LIMITED_API - Define this macro ``Py_LIMITED_API`` before including ``Python.h`` to - opt in to only use the Limited API. - - Defining ``Py_LIMITED_API`` to ``3`` will limit the available API so that - the extension will work without recompilation with all Python 3.x releases - (x>=2) on the particular :ref:`platform `. - - Defining ``Py_LIMITED_API`` to a value of :c:data:`PY_VERSION_HEX` will - limit the available API so that the extension will work without - recompilation with all Python 3 releases from the specified one. - This will allow using additional API introduced up to this version, - but the extension will lose compatibility with earlier Python versions. + Define this macro before including ``Python.h`` to opt in to only use + the Limited API, and to select the Limited API version. + + Define ``Py_LIMITED_API`` to the value of :c:data:`PY_VERSION_HEX` + corresponding to the lowest Python version your extension supports. + The extension will work without recompilation with all Python 3 releases + from the specified one onward, and can use Limited API introduced up to that + version. + Rather than using the ``PY_VERSION_HEX`` macro directly, hardcode a minimum minor version (e.g. ``0x030A0000`` for Python 3.10) for stability when compiling with future Python versions. + You can also define ``Py_LIMITED_API`` to ``3``. This works the same as + ``0x03020000`` (Python 3.2, the version that introduced 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``.