diff options
| author | Victor Stinner <vstinner@python.org> | 2023-08-30 14:02:48 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-08-30 14:02:48 (GMT) |
| commit | 2928e5dc6512e4206c616cd33e0bcc3288abf6ed (patch) | |
| tree | 5af868ae8670b13a211d8739f1c6b05393dda68e | |
| parent | e012cf771b8d4f114bd8dbdabf10d1584764541d (diff) | |
| download | cpython-2928e5dc6512e4206c616cd33e0bcc3288abf6ed.zip cpython-2928e5dc6512e4206c616cd33e0bcc3288abf6ed.tar.gz cpython-2928e5dc6512e4206c616cd33e0bcc3288abf6ed.tar.bz2 | |
gh-108494: Argument Clinic: Document how to generate code that uses the limited C API (#108584)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
| -rw-r--r-- | Doc/howto/clinic.rst | 23 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Tools-Demos/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 <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 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 <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. |