From 449ff4ef69328bd896d69b86c5fd3e3d0c593e9c Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 23 Feb 2024 22:38:58 +0800 Subject: [PATCH 1/6] Document how to use varargs in Argument Clinic --- development-tools/clinic.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 910de404ac..a9ff714285 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2213,3 +2213,23 @@ and update your unit tests to reflect the new behaviour. If you forget to update your input block during the alpha and beta phases, the compiler warning will turn into a compiler error when the release candidate phase begins. + + +How to convert variadic arguments functions +------------------------------------------- + +Some functions can be called with an arbitrary number of arguments. +These arguments will be wrapped up in a tuple. + +To convert a function to accept variadic arguments, +add a ``*`` in front of the parameter name just like Python, +and the parameter should use the ``object`` converter:: + + /*[clinic input] + vararg_sample + + foo: int + *args: object + [clinic start generated code]*/ + +.. versionadded:: 3.11 From bf96705b2c9b38443cdc2b703363bef13a75c241 Mon Sep 17 00:00:00 2001 From: AN Long Date: Sun, 25 Feb 2024 17:14:10 +0800 Subject: [PATCH 2/6] move up the section --- development-tools/clinic.rst | 40 ++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index a9ff714285..8ed9ae1065 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1495,6 +1495,26 @@ You can still use a self converter, a return converter, and specify a *type* argument to the object converter for :c:macro:`METH_O`. +How to convert variadic arguments functions +------------------------------------------- + +Some functions can be called with an arbitrary number of arguments. +These arguments will be wrapped up in a tuple. + +To convert a function to accept variadic arguments, +add a ``*`` in front of the parameter name just like Python, +and the parameter should use the ``object`` converter:: + + /*[clinic input] + vararg_sample + + foo: int + *args: object + [clinic start generated code]*/ + +.. versionadded:: 3.11 + + How to convert ``tp_new`` and ``tp_init`` functions --------------------------------------------------- @@ -2213,23 +2233,3 @@ and update your unit tests to reflect the new behaviour. If you forget to update your input block during the alpha and beta phases, the compiler warning will turn into a compiler error when the release candidate phase begins. - - -How to convert variadic arguments functions -------------------------------------------- - -Some functions can be called with an arbitrary number of arguments. -These arguments will be wrapped up in a tuple. - -To convert a function to accept variadic arguments, -add a ``*`` in front of the parameter name just like Python, -and the parameter should use the ``object`` converter:: - - /*[clinic input] - vararg_sample - - foo: int - *args: object - [clinic start generated code]*/ - -.. versionadded:: 3.11 From ec5c72869e8b46437bf27119318b80bfb61907ea Mon Sep 17 00:00:00 2001 From: AN Long Date: Sun, 25 Feb 2024 17:25:15 +0800 Subject: [PATCH 3/6] Use the term from https://docs.python.org/3/glossary.html#term-parameter --- development-tools/clinic.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 8ed9ae1065..a43777c0f4 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1495,18 +1495,15 @@ You can still use a self converter, a return converter, and specify a *type* argument to the object converter for :c:macro:`METH_O`. -How to convert variadic arguments functions -------------------------------------------- - -Some functions can be called with an arbitrary number of arguments. -These arguments will be wrapped up in a tuple. +How to convert var-positional parameter functions +------------------------------------------------- -To convert a function to accept variadic arguments, -add a ``*`` in front of the parameter name just like Python, +To convert a :term:`var-positional` parameter function, +prepending the parameter name with ``*`` , and the parameter should use the ``object`` converter:: /*[clinic input] - vararg_sample + var_positional_sample foo: int *args: object From f2edea856fd0ed32a6e8add9c274fca5e4bb0866 Mon Sep 17 00:00:00 2001 From: AN Long Date: Sun, 25 Feb 2024 17:28:24 +0800 Subject: [PATCH 4/6] remove the term markup --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index a43777c0f4..a5fa2e9df5 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1498,7 +1498,7 @@ a *type* argument to the object converter for :c:macro:`METH_O`. How to convert var-positional parameter functions ------------------------------------------------- -To convert a :term:`var-positional` parameter function, +To convert a var-positional parameter function, prepending the parameter name with ``*`` , and the parameter should use the ``object`` converter:: From b2f1914506250494a5e953a65c313a91954771ad Mon Sep 17 00:00:00 2001 From: AN Long Date: Mon, 14 Oct 2024 01:06:59 +0800 Subject: [PATCH 5/6] Add description about what the implementaion functions will receive --- development-tools/clinic.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index a5fa2e9df5..c4fdd11da5 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1509,6 +1509,10 @@ and the parameter should use the ``object`` converter:: *args: object [clinic start generated code]*/ +The implementation function will receive var-positional arguments +as a tuple, you can either use the tuple directly +or parsing them into C types using :c:func:`!PyArg_Parse*` functions. + .. versionadded:: 3.11 From 7d6c9c966de667e1a04731b2922a2540db727c1d Mon Sep 17 00:00:00 2001 From: AN Long Date: Tue, 15 Oct 2024 01:30:51 +0800 Subject: [PATCH 6/6] Update development-tools/clinic.rst Co-authored-by: Jelle Zijlstra --- development-tools/clinic.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index c4fdd11da5..e10592c6c9 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1510,8 +1510,7 @@ and the parameter should use the ``object`` converter:: [clinic start generated code]*/ The implementation function will receive var-positional arguments -as a tuple, you can either use the tuple directly -or parsing them into C types using :c:func:`!PyArg_Parse*` functions. +as a tuple. .. versionadded:: 3.11