Document how to use *args in Argument Clinic (#1629)

skirpichev · AA-Turner · aisk · web-flow · commit 25cb6131352e · 2025-08-18T02:25:21.000+01:00
Co-authored-by: Adam Turner &lt;9087854+AA-Turner@users.noreply.github.com&gt;
Co-authored-by: AN Long &lt;aisk1988@gmail.com&gt;
diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst
@@ -1495,6 +1495,37 @@ 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 ``*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]*/
+
+.. versionadded:: 3.11
+
+
 How to convert ``tp_new`` and ``tp_init`` functions
 ---------------------------------------------------
 
