From 2928e5dc6512e4206c616cd33e0bcc3288abf6ed Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 30 Aug 2023 16:02:48 +0200 Subject: gh-108494: Argument Clinic: Document how to generate code that uses the limited C API (#108584) Co-authored-by: Alex Waygood Co-authored-by: Erlend E. Aasland --- Doc/howto/clinic.rst | 23 +++++++++++++++++++++- .../2023-08-25-22-40-12.gh-issue-108494.4RbDdu.rst | 3 ++- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 667859e..92701b0 100644 --- 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 ` 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 ` 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 2d61152..b96da7c 100644 --- 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 ` now has a partial support of the -:ref:`Limited API `. Patch by Victor Stinner. +:ref:`Limited API `: see :ref:`clinic-howto-limited-capi`. +Patch by Victor Stinner. -- cgit v0.12