From 436be4a340ffeaa42e16188deaf43c55cef38fe3 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 Co-authored-by: Jelle Zijlstra Co-authored-by: Sergey B Kirpichev --- development-tools/clinic.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 2f4677430..7954153ff 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1495,6 +1495,27 @@ 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 var-positional parameter functions +------------------------------------------------- + +To convert a var-positional parameter function, +prepending the parameter name with ``*`` , +and the parameter should use the ``object`` converter:: + + /*[clinic input] + var_positional_sample + + foo: int + *args: object + [clinic start generated code]*/ + +The implementation function will receive var-positional arguments +as *args* array. + +.. versionadded:: 3.11 +.. versionchanged:: 3.14 + + How to convert ``tp_new`` and ``tp_init`` functions --------------------------------------------------- From 16237b2f25cad8040128289f5c98b0585830f6df Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Fri, 15 Aug 2025 16:18:58 +0100 Subject: [PATCH 2/6] Update development-tools/clinic.rst Co-authored-by: Sergey B Kirpichev --- development-tools/clinic.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 7954153ff..354337e54 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1513,7 +1513,6 @@ The implementation function will receive var-positional arguments as *args* array. .. versionadded:: 3.11 -.. versionchanged:: 3.14 How to convert ``tp_new`` and ``tp_init`` functions From 816d5e81fd901d8b6abd69f93c06df28546e2688 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 15 Aug 2025 18:42:28 +0300 Subject: [PATCH 3/6] Update development-tools/clinic.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- development-tools/clinic.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 354337e54..6b87de1ee 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1498,9 +1498,9 @@ a *type* argument to the object converter for :c:macro:`METH_O`. How to convert var-positional parameter functions ------------------------------------------------- -To convert a var-positional parameter function, -prepending the parameter name with ``*`` , -and the parameter should use the ``object`` converter:: +To convert a var-positional parameter function, prepend the parameter name +with ``*`` and use the the ``object`` converter. +For example:: /*[clinic input] var_positional_sample From 18e9be616c9374336c0592eecbb611c50601700c Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 15 Aug 2025 18:43:06 +0300 Subject: [PATCH 4/6] Apply suggestions from code review --- development-tools/clinic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 6b87de1ee..e97001abf 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1499,14 +1499,14 @@ How to convert var-positional parameter functions ------------------------------------------------- To convert a var-positional parameter function, prepend the parameter name -with ``*`` and use the the ``object`` converter. +with ``*`` and use the the ``array`` converter. For example:: /*[clinic input] var_positional_sample foo: int - *args: object + *args: array [clinic start generated code]*/ The implementation function will receive var-positional arguments From 132293045a72d85383017f59a95fa8859ee81a76 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 16 Aug 2025 04:46:31 +0300 Subject: [PATCH 5/6] Mention tuple converter --- development-tools/clinic.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index e97001abf..4dc49b77c 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1509,8 +1509,9 @@ For example:: *args: array [clinic start generated code]*/ -The implementation function will receive var-positional arguments -as *args* array. +The implementation function will receive var-positional arguments as C array +*args* of :c:type:`PyObject * `. Alternatively, you could use +``tuple`` converter to pass a regular :c:type:`PyTupleObject` as argument. .. versionadded:: 3.11 From 5644df2c9707734963514213562ac233454bd968 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 18 Aug 2025 04:12:33 +0300 Subject: [PATCH 6/6] Update development-tools/clinic.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- development-tools/clinic.rst | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 4dc49b77c..6446d1a46 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -1495,23 +1495,33 @@ 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 var-positional parameter functions -------------------------------------------------- +How to convert ``*args`` parameters (starargs / var-positional) +--------------------------------------------------------------- + +There are two converters suitable for ``*args``: *array* and *tuple*. -To convert a var-positional parameter function, prepend the parameter name -with ``*`` and use the the ``array`` converter. +Using the *array* converter will provide the implementation function with +a C array *args* of type of :c:type:`PyObject * ` and the number +of items in the array as :c:type:`Py_ssize_t` *args_length*. For example:: /*[clinic input] var_positional_sample - foo: int + spam: int *args: array [clinic start generated code]*/ -The implementation function will receive var-positional arguments as C array -*args* of :c:type:`PyObject * `. Alternatively, you could use -``tuple`` converter to pass a regular :c:type:`PyTupleObject` as argument. +Using the *tuple* converter will provide the implementation function with +a standard :c:type:`PyTupleObject`. +For example:: + + /*[clinic input] + var_positional_sample + + spam: int + *args: tuple + [clinic start generated code]*/ .. versionadded:: 3.11