Options¶
Adding options to commands can be accomplished with the option()
decorator. At runtime the decorator invokes the Option
class. Options in Click are distinct from positional arguments.
Useful and often used kwargs are:
default
: Passes a default.help
: Sets help message.nargs
: Sets the number of arguments.required
: Makes option required.type
: Sets parameter type
Option Decorator¶
Click expects you to pass at least two positional arguments to the option decorator. They are option name and function argument name.
@click.command()
@click.option('--string-to-echo', 'string_to_echo')
def echo(string_to_echo):
click.echo(string_to_echo)
$ echo --help
Usage: echo [OPTIONS]
Options:
--string-to-echo TEXT
--help Show this message and exit.
However, if you don’t pass in the function argument name, then Click will try to infer it. A simple way to name your option is by taking the function argument, adding two dashes to the front and converting underscores to dashes. In this case, Click will infer the function argument name correctly so you can add only the option name.
@click.command()
@click.option('--string-to-echo')
def echo(string_to_echo):
click.echo(string_to_echo)
$ echo --string-to-echo 'Hi!'
Hi!
More formally, Click will try to infer the function argument name by:
If a positional argument name does not have a prefix, it is chosen.
If a positional argument name starts with with two dashes, the first one given is chosen.
The first positional argument prefixed with one dash is chosen otherwise.
The chosen positional argument is converted to lower case, up to two dashes are removed from the beginning, and other dashes are converted to underscores to get the function argument name.
Decorator Arguments |
Function Name |
---|---|
|
foo_bar |
|
x |
|
dest |
|
camelcase |
|
f |
|
f |
|
_f |
Basic Example¶
A simple click.Option
takes one argument. This will assume the argument is not required. If the decorated function takes an positional argument then None is passed it. This will also assume the type is str
.
@click.command()
@click.option('--text')
def print_this(text):
click.echo(text)
$ print-this --text=this
this
$ print-this
$ print-this --help
Usage: print-this [OPTIONS]
Options:
--text TEXT
--help Show this message and exit.
Setting a Default¶
Instead of setting the type
, you may set a default and Click will try to infer the type.
@click.command()
@click.option('--n', default=1)
def dots(n):
click.echo('.' * n)
$ dots --help
Usage: dots [OPTIONS]
Options:
--n INTEGER
--help Show this message and exit.
Multi Value Options¶
To make an option take multiple values, pass in nargs
. Note only a fixed number of arguments is supported. The values are passed to the underlying function as a tuple.
@click.command()
@click.option('--pos', nargs=2, type=float)
def findme(pos):
a, b = pos
click.echo(f"{a} / {b}")
$ findme --pos 2.0 3.0
2.0 / 3.0
Multi Value Options as Tuples¶
:::{versionadded} 4.0 :::
As you can see that by using nargs
set to a specific number each item in
the resulting tuple is of the same type. This might not be what you want.
Commonly you might want to use different types for different indexes in
the tuple. For this you can directly specify a tuple as type:
@click.command()
@click.option('--item', type=(str, int))
def putitem(item):
name, id = item
click.echo(f"name={name} id={id}")
And on the command line:
$ putitem --item peter 1338
name=peter id=1338
By using a tuple literal as type, nargs
gets automatically set to the
length of the tuple and the click.Tuple
type is automatically
used. The above example is thus equivalent to this:
@click.command()
@click.option('--item', nargs=2, type=click.Tuple([str, int]))
def putitem(item):
name, id = item
click.echo(f"name={name} id={id}")
Multiple Options¶
The multiple options format allows you to call the underlying function multiple times with one command line entry. If set, the default must be a list or tuple. Setting a string as a default will be interpreted as list of characters.
@click.command()
@click.option('--message', '-m', multiple=True)
def commit(message):
click.echo('\n'.join(message))
$ commit -m foo -m bar -m here
foo
bar
here
Counting¶
To count the occurrence of an option pass in count=True
. If the option is not passed in, then the count is 0. Counting is commonly used for verbosity.
@click.command()
@click.option('-v', '--verbose', count=True)
def log(verbose):
click.echo(f"Verbosity: {verbose}")
$ log
Verbosity: 0
$ log -vvv
Verbosity: 3
Boolean¶
Boolean options (boolean flags) take the value True or False. The simplest case sets the default value to False
if the flag is not passed, and True
if it is.
import sys
@click.command()
@click.option('--shout', is_flag=True)
def info(shout):
rv = sys.platform
if shout:
rv = rv.upper() + '!!!!111'
click.echo(rv)
$ info
win32
$ info --shout
WIN32!!!!111
To implement this more explicitly, pass in on-option /
off-option. Click will automatically set is_flag=True
. Click always wants you to provide an enable
and disable flag so that you can change the default later.
import sys
@click.command()
@click.option('--shout/--no-shout', default=False)
def info(shout):
rv = sys.platform
if shout:
rv = rv.upper() + '!!!!111'
click.echo(rv)
$ info
win32
$ info --shout
WIN32!!!!111
$ info --no-shout
win32
If a forward slash(/
) is contained in your option name already, you can split the parameters using ;
. In Windows /
is commonly used as the prefix character.
@click.command()
@click.option('/debug;/no-debug')
def log(debug):
click.echo(f"debug={debug}")
:::{versionchanged} 6.0 :::
If you want to define an alias for the second option only, then you will need to use leading whitespace to disambiguate the format string.
import sys
@click.command()
@click.option('--shout/--no-shout', ' /-N', default=False)
def info(shout):
rv = sys.platform
if shout:
rv = rv.upper() + '!!!!111'
click.echo(rv)
$ info --help
Usage: info [OPTIONS]
Options:
--shout / -N, --no-shout
--help Show this message and exit.
Flag Value¶
To have an flag pass a value to the underlying function set flag_value
. This automatically sets is_flag=True
. To set a default flag, set default=True
. Setting flag values can be used to create patterns like this:
import sys
@click.command()
@click.option('--upper', 'transformation', flag_value='upper', default=True)
@click.option('--lower', 'transformation', flag_value='lower')
def info(transformation):
click.echo(getattr(sys.platform, transformation)())
$ info --help
Usage: info [OPTIONS]
Options:
--upper
--lower
--help Show this message and exit.
$ info --upper
WIN32
$ info --lower
win32
$ info
WIN32
Values from Environment Variables¶
To pass in a value in from a specific environment variable use envvar
.
@click.command()
@click.option('--username', envvar='USERNAME')
def greet(username):
click.echo(f"Hello {username}!")
$ export USERNAME=john
$ greet
Hello john!
If a list is passed to envvar
, the first environment variable found is picked.
@click.command()
@click.option('--username', envvar=['ALT_USERNAME', 'USERNAME'])
def greet(username):
click.echo(f"Hello {username}!")
$ export ALT_USERNAME=Bill
$ export USERNAME=john
$ greet
Hello Bill!
Multiple Options from Environment Values¶
As options can accept multiple values, pulling in such values from
environment variables (which are strings) is a bit more complex. The way
Click solves this is by leaving it up to the type to customize this
behavior. For both multiple
and nargs
with values other than
1
, Click will invoke the ParamType.split_envvar_value()
method to
perform the splitting.
The default implementation for all types is to split on whitespace. The
exceptions to this rule are the File
and Path
types
which both split according to the operating system’s path splitting rules.
On Unix systems like Linux and OS X, the splitting happens on
every colon (:
), and for Windows, splitting on every semicolon (;
).
@click.command()
@click.option('paths', '--path', envvar='PATHS', multiple=True,
type=click.Path())
def perform(paths):
for path in paths:
click.echo(path)
if __name__ == '__main__':
perform()
$ export PATHS='./foo/bar;./test'
$ perform
./foo/bar
./test
Other Prefix Characters¶
Click can deal with prefix characters besides -
for options. Click can use
/
, +
as well as others. Note that alternative prefix characters are generally used very sparingly if at all within POSIX.
@click.command()
@click.option('+w/-w')
def chmod(w):
click.echo(f"writable={w}")
$ chmod +w
writable=True
$ chmod -w
writable=False
There are special considerations for using /
as prefix character, see Boolean for more.
Optional Value¶
Providing the value to an option can be made optional, in which case
providing only the option’s flag without a value will either show a
prompt or use its flag_value
.
Setting is_flag=False, flag_value=value
tells Click that the option
can still be passed a value, but only if the flag is given the
flag_value
.
@click.command()
@click.option("--name", is_flag=False, flag_value="Flag", default="Default")
def hello(name):
click.echo(f"Hello, {name}!")
$ hello
Hello, Default!
$ hello --name Value
Hello, Value!
$ hello --name
Hello, Flag!