gh-108494: Argument Clinic: Document how to generate code that uses the limited C...

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index 667859e20a5d8782f24cf153ac306b9e41f2b931..92701b09c3bca2e0c22cce8535dbc2c28f9c835d 100644 (file)
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -158,7 +158,7 @@ process a single source file, like this:
 The CLI supports the following options:
 
 .. program:: ./Tools/clinic/clinic.py [-h] [-f] [-o OUTPUT] [-v] \
-             [--converters] [--make] [--srcdir SRCDIR] [FILE ...]
+             [--converters] [--make] [--srcdir SRCDIR] [--limited] [FILE ...]
 
 .. option:: -h, --help
 
@@ -193,6 +193,11 @@ The CLI supports the following options:
    A file to exclude in :option:`--make` mode.
    This option can be given multiple times.
 
+.. option:: --limited
+
+    Use the :ref:`Limited API <limited-c-api>` to parse arguments in the generated C code.
+    See :ref:`clinic-howto-limited-capi`.
+
 .. option:: FILE ...
 
    The list of files to process.
@@ -1905,6 +1910,22 @@ blocks embedded in Python files look slightly different.  They look like this:
     #/*[python checksum:...]*/
 
 
+.. _clinic-howto-limited-capi:
+
+How to use the Limited C API
+----------------------------
+
+If Argument Clinic :term:`input` is located within a C source file
+that contains ``#define Py_LIMITED_API``, Argument Clinic will generate C code
+that uses the :ref:`Limited API <limited-c-api>` to parse arguments. The
+advantage of this is that the generated code will not use private functions.
+However, this *can* result in Argument Clinic generating less efficient code
+in some cases. The extent of the performance penalty will depend
+on the parameters (types, number, etc.).
+
+.. versionadded:: 3.13
+
+
 .. _clinic-howto-override-signature:
 
 How to override the generated signature

diff --git a/Misc/NEWS.d/next/Tools-Demos/2023-08-25-22-40-12.gh-issue-108494.4RbDdu.rst b/Misc/NEWS.d/next/Tools-Demos/2023-08-25-22-40-12.gh-issue-108494.4RbDdu.rst
index 2d611527b260920f263dc0db099eb521b4a16b1e..b96da7c0a16df88f961288230f82873a68995062 100644 (file)
--- a/Misc/NEWS.d/next/Tools-Demos/2023-08-25-22-40-12.gh-issue-108494.4RbDdu.rst
+++ b/Misc/NEWS.d/next/Tools-Demos/2023-08-25-22-40-12.gh-issue-108494.4RbDdu.rst
@@ -1,2 +1,3 @@
 :ref:`Argument Clinic <howto-clinic>` now has a partial support of the
-:ref:`Limited API <limited-c-api>`. Patch by Victor Stinner.
+:ref:`Limited API <limited-c-api>`: see :ref:`clinic-howto-limited-capi`.
+Patch by Victor Stinner.