Document how to use varargs in Argument Clinic - #1629
AA-Turner merged 6 commits into
Conversation
Sorry, something went wrong.
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
|
This is a minor correction of closed pr #1277 (now var-positional arguments passed a C array). The rest looks fine for me. |
Sorry, something went wrong.
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
AA-Turner
left a comment
There was a problem hiding this comment.
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)
Sorry, something went wrong.
It's not removed, just an alias for tuple. |
Sorry, something went wrong.
| 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. |
There was a problem hiding this comment.
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.
| 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]*/ |
Sorry, something went wrong.
There was a problem hiding this comment.
IMO, it's too verbose. But OK.
Sorry, something went wrong.
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
📚 Documentation preview 📚: https://cpython-devguide--1629.org.readthedocs.build/