From a8ba2b867d062aea73bdb845f697144af3eed958 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Mon, 28 Aug 2023 22:40:15 +0200 Subject: [PATCH 1/6] gh-108494: AC: Document How to use the Limited C API --- Doc/howto/clinic.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 667859e20a5d87..0030e1961befc4 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1905,6 +1905,17 @@ blocks embedded in Python files look slightly different. They look like this: #/*[python checksum:...]*/ +How to use the Limited C API +---------------------------- + +If a C source code contains ``#define Py_LIMITED_API``, the generated C code +will use the :ref:`Limited API ` to parse arguments. Private +functions are not used in this case and the code parsing arguments can be a +less efficient depending on the parameters (types, number, etc.). + +.. versionadded:: 3.13 + + .. _clinic-howto-override-signature: How to override the generated signature From 96502dfb7feaa6a434f5d372b246d14b34f0f80e Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Tue, 29 Aug 2023 17:19:00 +0200 Subject: [PATCH 2/6] Address reviews --- Doc/howto/clinic.rst | 13 ++++++++++--- .../2023-08-25-22-40-12.gh-issue-108494.4RbDdu.rst | 3 ++- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 0030e1961befc4..f6ff87686676af 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:`How to use the Limited C API `. + .. option:: FILE ... The list of files to process. @@ -1905,13 +1910,15 @@ 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 a C source code contains ``#define Py_LIMITED_API``, the generated C code will use the :ref:`Limited API ` to parse arguments. Private -functions are not used in this case and the code parsing arguments can be a -less efficient depending on the parameters (types, number, etc.). +functions are not used in this case. However the code parsing arguments can be +a less efficient depending on the parameters (types, number, etc.). .. versionadded:: 3.13 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 2d611527b26092..c8fe4e38a1e70b 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 Argument Clinic :ref:`How to use the +Limited C API `. Patch by Victor Stinner. From 8b2c572a498108da68a687b5801419776ab44212 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Tue, 29 Aug 2023 18:36:12 +0200 Subject: [PATCH 3/6] Update Doc/howto/clinic.rst Co-authored-by: Alex Waygood --- Doc/howto/clinic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index f6ff87686676af..5ae2309efb183c 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1917,8 +1917,8 @@ How to use the Limited C API If a C source code contains ``#define Py_LIMITED_API``, the generated C code will use the :ref:`Limited API ` to parse arguments. Private -functions are not used in this case. However the code parsing arguments can be -a less efficient depending on the parameters (types, number, etc.). +functions are not used in this case. However, the code parsing arguments can be +less efficient depending on the parameters (types, number, etc.). .. versionadded:: 3.13 From 60ec4ec77c6cfe8f3e28bcf4dfad42eb34ba2e5e Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Tue, 29 Aug 2023 20:29:23 +0200 Subject: [PATCH 4/6] Update Doc/howto/clinic.rst Co-authored-by: Alex Waygood --- Doc/howto/clinic.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 5ae2309efb183c..c786091cdd9a48 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1915,10 +1915,13 @@ blocks embedded in Python files look slightly different. They look like this: How to use the Limited C API ---------------------------- -If a C source code contains ``#define Py_LIMITED_API``, the generated C code -will use the :ref:`Limited API ` to parse arguments. Private -functions are not used in this case. However, the code parsing arguments can be -less efficient depending on the parameters (types, number, etc.). +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 From 84687de815427e53b94d43545336128a3b3de30f Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Tue, 29 Aug 2023 22:51:01 +0200 Subject: [PATCH 5/6] Update Doc/howto/clinic.rst Co-authored-by: Erlend E. Aasland --- Doc/howto/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index c786091cdd9a48..92701b09c3bca2 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -196,7 +196,7 @@ The CLI supports the following options: .. option:: --limited Use the :ref:`Limited API ` to parse arguments in the generated C code. - See :ref:`How to use the Limited C API `. + See :ref:`clinic-howto-limited-capi`. .. option:: FILE ... From 214f6bff5b6ecfe143c30a2f4127586287acce57 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Tue, 29 Aug 2023 22:51:18 +0200 Subject: [PATCH 6/6] Update Misc/NEWS.d/next/Tools-Demos/2023-08-25-22-40-12.gh-issue-108494.4RbDdu.rst Co-authored-by: Erlend E. Aasland --- .../2023-08-25-22-40-12.gh-issue-108494.4RbDdu.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 c8fe4e38a1e70b..b96da7c0a16df8 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,3 +1,3 @@ :ref:`Argument Clinic ` now has a partial support of the -:ref:`Limited API `: see Argument Clinic :ref:`How to use the -Limited C API `. Patch by Victor Stinner. +:ref:`Limited API `: see :ref:`clinic-howto-limited-capi`. +Patch by Victor Stinner.