Skip to content

Commit

Permalink
Docs: Correct "variable" to "variadic" arguments (#5975)
Browse files Browse the repository at this point in the history
Co-authored-by: Sebastiaan Huber <mail@sphuber.net>
  • Loading branch information
ltalirz and sphuber committed Apr 20, 2023
1 parent fce1cd6 commit 9782176
Show file tree
Hide file tree
Showing 2 changed files with 8 additions and 10 deletions.
4 changes: 2 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ A full list of changes can be found below.
A number of improvements in the usage of process functions, i.e., `calcfunction` and `workfunction`, have been added.
Each subsection title is a link to the documentation for more details.

#### [Variable arguments](https://aiida.readthedocs.io/projects/aiida-core/en/latest/topics/processes/functions.html#variable-and-keyword-arguments)
Variable arguments can be used in case the function should accept a list of inputs of unknown length.
#### [Variadic arguments](https://aiida.readthedocs.io/projects/aiida-core/en/latest/topics/processes/functions.html#variadic-and-keyword-arguments)
Variadic arguments can be used in case the function should accept a list of inputs of unknown length.
Consider the example of a calculation function that computes the average of a number of `Int` nodes:
```python
@calcfunction
Expand Down
14 changes: 6 additions & 8 deletions docs/source/topics/processes/functions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -60,12 +60,12 @@ What this means is that *both* the function definition and function call below a
.. include:: include/snippets/functions/signature_plain_python_call_illegal.py
:code: python

Finally, python knows the concept of ``*args`` and ``**kwargs``, also referred to as variable arguments and keyword arguments, which allow one to define a function which accepts an undetermined number of positional and keyword arguments.
Finally, python knows the concept of ``*args`` and ``**kwargs``, which allow one to define a function that accepts a variable number of positional and keyword arguments (also known as a _variadic_ function).

.. include:: include/snippets/functions/signature_plain_python_args_kwargs.py
:code: python

The variable arguments ``*args`` will receive the positionally passed arguments as a tuple and the keyword arguments ``**kwargs`` will receive the named arguments as a dictionary.
The placeholder for positional arguments ``*args`` receives the positionally passed arguments as a tuple, while ``**kwargs`` receives the named arguments as a dictionary.
With the formal definitions out of the way, let's now see which of these concepts are supported by process functions.

Default arguments
Expand All @@ -80,8 +80,8 @@ This pattern looks like the following:

Both function calls in the example above will have the exact same result.

Variable and keyword arguments
==============================
Variadic arguments
==================

Keyword arguments can be used effectively if a process function should take a number of arguments that is unknown beforehand:

Expand All @@ -96,14 +96,12 @@ The provenance generated by this example looks like the following:
The link labels of the inputs are determined based on the naming of the parameters when the function is called.

Note that the inputs **have to be passed as keyword arguments** because they are used for the link labels.
If the inputs would simply have been passed as positional arguments, the engine could have impossibly determined what label to use for the links that connect the input nodes with the calculation function node.
For this reason, invoking a 'dynamic' function, i.e. one that supports ``**kwargs`` in its signature, with more positional arguments that explicitly named in the signature, will raise a ``TypeError``.

.. versionadded:: 2.3

Variable arguments are now supported.
Variadic positional arguments are now supported.

Variable arguments can be used in case the function should accept a list of inputs of unknown length.
Variadic positional arguments can be used in case the function should accept a list of inputs of unknown length.
Consider the example of a calculation function that computes the average of a number of ``Int`` nodes:

.. include:: include/snippets/functions/signature_calcfunction_args.py
Expand Down

0 comments on commit 9782176

Please sign in to comment.