Basic Concepts¶
There is a very similar logic behind how Python3 handles arguments of the callables and how typical CLI handles arguments provided by the user. This fact makes Kickoff able to translate signatures of your functions into corresponding CLI commands. Table below summarizes this relationship.
| Function Argument | Example | Command Line Argument | Example |
|---|---|---|---|
| None | foobar() |
None | foobar |
| Argument without default value | foobar(qux) |
Required parameter | foobar <QUX> |
| Argument with default value | foobar(qux=123) |
Optional parameter | foobar [<QUX>] |
| Argument with default value of boolean type | foobar(*, qux=False) |
Flag | foobar [--qux] |
| Keyword-only argument without default value | foobar(*, qux) |
Required option | foobar --qux <QUX> |
| Keyword-only argument with default value | foobar(*, qux=123) |
Optional option | foobar [--qux <QUX>] |
| Non-keyworded variable-length argument list | foobar(*args) |
Optional multi-parameter | foobar [<ARGS> ...] |
| Keyworded variable-length argument list | foobar(**kwargs) |
Ignored | foobar |
See ex01_simple to gain some experience.
You might have noticed that docstrings in the code can be used for providing descriptions. In addition, annotations can be used to specify details which cannot be distinguished from Python syntax. Kickoff expects annotations to be of dict type. Keys of the dictionary are passed to click.argument or click.option function as corresponding parameters. Additionally alias can be used to specify short name of given CLI option. Values of return annotation are used as arguments to click.Command class.
Table below shows couple of practical examples on how to use annotations.
| Function Argument | Example | Command Line Argument | Example |
|---|---|---|---|
required specifier & variable-length argument list |
foobar(*qux: dict(required=True)) |
Required multi-parameter | foobar <ARGS> ... |
multiple specifier |
foobar(*, qux: dict(multiple=True) |
Required multi-option | foobar --qux <QUX> ... |
multiple & required specifiers |
foobar(*, qux: dict(multiple=True, required=False)) |
Optional multi-option | foobar [--qux <QUX> ...] |
count specifier |
foobar(*, qux: dict(count=True) ) |
Required counting flag | foobar --qux ... |
count specifier & default value |
foobar(*, qux: dict(count=True) =0 ) |
Optional counting flag | foobar [--qux ...] |
Example ex02_args_and_opts covers more use cases. Note that settings specified in annotations overwite those which were deduced from function signature.
Please also check Command Groups chapter to see full mapping of Python AST elements and CLI elements.