Parameters¶
Click supports only two principle types of parameters for scripts (by design): options and arguments.
Options¶
Are optional.
Recommended to use for everything except subcommands, urls, or files.
Can take a fixed number of arguments. The default is 1. They may be specified multiple times using Multiple Options.
Are fully documented by the help page.
Have automatic prompting for missing input.
Can act as flags (boolean or otherwise).
Can be pulled from environment variables.
Arguments¶
Are optional with in reason, but not entirely so.
Recommended to use for subcommands, urls, or files.
Can take an arbitrary number of arguments.
Are not fully documented by the help page since they may be too specific to be automatically documented. For more see Documenting Arguments.
Can be pulled from environment variables but only explicitly named ones. For more see Environment Variables.
On each principle type you can specify Parameter Types. Specifying these types helps Click add details to your help pages and help with the handling of those types.
Parameter Names¶
Parameters (options and arguments) have a name that will be used as the Python argument name when calling the decorated function with values.
@click.command()
@click.argument('filename')
@click.option('-t', '--times', type=int)
def multi_echo(filename, times):
"""Print value filename multiple times."""
for x in range(times):
click.echo(filename)
In the above example the argument’s name is filename
. The name must match the python arg name. To provide a different name for use in help text, see Truncating Help Texts.
The option’s names are -t
and --times
. More names are available for options and are covered in Options.
And what it looks like when run:
$ multi_echo --times=3 index.txt
index.txt
index.txt
index.txt