Document how to use varargs in Argument Clinic #1629

skirpichev · 2025-08-12T11:37:52Z

📚 Documentation preview 📚: https://cpython-devguide--1629.org.readthedocs.build/

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

skirpichev · 2025-08-12T11:39:54Z

This is a minor correction of closed pr #1277 (now var-positional arguments passed a C array). The rest looks fine for me.

development-tools/clinic.rst

Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

development-tools/clinic.rst

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

development-tools/clinic.rst

AA-Turner

We should mention both the tuple and array converters, they do different things. Notably array results in PyObject * const *args and Py_ssize_t args_length, whereas tuple just passes a regular PyTupleObject.

Also, I found the PR where : object was removed (python/cpython#126560 by @serhiy-storchaka)

skirpichev · 2025-08-16T01:48:24Z

Also, I found the PR where : object was removed

It's not removed, just an alias for tuple.

AA-Turner · 2025-08-17T20:20:39Z

development-tools/clinic.rst

+How to convert var-positional parameter functions
+-------------------------------------------------
+
+To convert a var-positional parameter function, prepend the parameter name
+with ``*`` and use the the ``array`` converter.
+For example::
+
+   /*[clinic input]
+   var_positional_sample
+
+       foo: int
+       *args: array
+   [clinic start generated code]*/
+
+The implementation function will receive var-positional arguments as C array
+*args* of :c:type:`PyObject * <PyObject>`.  Alternatively, you could use
+``tuple`` converter to pass a regular :c:type:`PyTupleObject` as argument.


A suggested rephrasing to split tuple and array. I've also switched to saying *args instead of emphasising var-positional, the documentation uses *args or starargs, when discussing the feature in the language reference, it seems to be only internal to Clinic to say varpos.

Suggested change

How to convert var-positional parameter functions

-------------------------------------------------

To convert a var-positional parameter function, prepend the parameter name

with ``*`` and use the the ``array`` converter.

For example::

/*[clinic input]

var_positional_sample

foo: int

*args: array

[clinic start generated code]*/

The implementation function will receive var-positional arguments as C array

*args* of :c:type:`PyObject * <PyObject>`. Alternatively, you could use

``tuple`` converter to pass a regular :c:type:`PyTupleObject` as argument.

How to convert ``*args`` parameters (starargs / var-positional)

---------------------------------------------------------------

There are two converters suitable for ``*args``: *array* and *tuple*.

Using the *array* converter will provide the implementation function with

a C array *args* of type of :c:type:`PyObject * <PyObject>` and the number

of items in the array as :c:type:`Py_ssize_t` *args_length*.

For example::

/*[clinic input]

var_positional_sample

spam: int

*args: array

[clinic start generated code]*/

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]*/

IMO, it's too verbose. But OK.

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Document how to use varargs in Argument Clinic

436be4a

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

skirpichev requested a review from erlend-aasland August 12, 2025 11:38

skirpichev mentioned this pull request Aug 12, 2025

Argument Clinic should understand *args and **kwargs parameters python/cpython#64490

Open

vstinner reviewed Aug 13, 2025

View reviewed changes