From 2e3b6734100395d9a60b49662ba6f26f63d75e76 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 30 Aug 2023 16:02:48 +0200 Subject: [PATCH] python/cpython#108494: Argument Clinic: Document how to generate code that uses the limited C API (python/cpython#108584) Co-authored-by: Alex Waygood Co-authored-by: Erlend E. Aasland --- development-tools/clinic.rst | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 28fe4b6e36..eade2b9905 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -152,7 +152,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 @@ -187,6 +187,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. @@ -1899,6 +1904,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