ZetCode
All Spring Boot Python C# Java JavaScript Subscribe
Python click
last modified July 6, 2020
Python click tutorial shows how to create command line interfaces with the click module.
Python click
Python click module is used to create command-line (CLI) applications. It is an easy-to-use
alternative to the standard optparse and argparse modules. It allows arbitrary nesting of
commands, automatic help page generation, and supports lazy loading of subcommands at
runtime.
The click module was created as a supporting library for the Flask web framework.
The commands are basic building blocks of an application. Click defines commands through
decorators. They are created with the click.command() decorator. Values are passed to the
commands via options or arguments. Options are added with the click.option() decorator,
arguments with the click.argument(). Values in options follow the name of the option while
arguments are taken positionally.
$ pip install -U click
We install the click module. For coloured output, we also need the colorama module.
Python click simple example
The following is a trivial CLI example.
simple.py
import click
@click.command()
def hello():
click.echo('Hello there')
if __name__ == '__main__':
hello()
The example creates a command that outputs a message.
Google Ads -
Sitio O cial
Con Google Ads, no hay
contratos ni mínimo de
Google Ads inversión.
@click.command()
def hello():
click.echo('Hello there')
Click uses the echo instead of the print. It increases compatibility and adds colouring support.
$ ./simple.py
Hello there
$ ./simple.py --help
Usage: simple.py [OPTIONS]
Options:
--help Show this message and exit.
Click creates some help messages out of the box.
Python click default argument
Arguments are added with the click.argument() decorator. The arguments may have default
values.
argument.py
#!/usr/bin/python3
import click
@click.command()
@click.argument('name', default='guest')
def hello(name):
click.echo(f'Hello {name}')
if __name__ == '__main__':
hello()
The example builds a message with the given argument value. If there is no argument, the default
guest is used. The argument is passed to the function as a variable.
Google Ads -
Sitio O cial
Con Google Ads, no hay
contratos ni mínimo de
Google Ads inversión.
$ ./argument.py Peter
Hello Peter
$ ./argument.py
Hello guest
We run the program with and without an argument.
Python click argument types
We can specify the argument types, including int, float, str, bool, choice and various ranges. The
default one is str.
argument_type.py
#!/usr/bin/python3
import click
@click.command()
@click.argument('name', default='guest')
@click.argument('age', type=int)
def hello(name, age):
click.echo(f'{name} is {age} years old')
if __name__ == '__main__':
hello()
In the example, we have two arguments: name and age. They are generated positionally, the first is
name, the second is age.
$ ./argument_type.py Peter 34
Peter is 34 years old
This is the output.
Python click variable number of arguments
With the nargs option, we can set that an argument takes multiple values. For the -1 value, the
argument may take variable number of values.
variable_args.py
#!/usr/bin/python3
import click
from operator import mul
from functools import reduce
@click.command()
@click.argument('vals', type=int, nargs=-1)
def process(vals):
print(f'The sum is {sum(vals)}')
print(f'The product is {reduce(mul, vals, 1)}')
if __name__ == '__main__':
process()
The example creates a process command, which may take variable number of integer values in the
vals argument. The command calculates the sum and the product of the values.
Google Ads -
Sitio O cial
Con Google Ads, no hay
contratos ni mínimo de
Google Ads inversión.
$ ./variable_args.py 1 2 3 4 5
The sum is 15
The product is 120
This is the output.
Python click simple option
Options are added to commands with the click.option() decorator. Option names are prefixed
with one or two dashes.
dots.py
#!/usr/bin/python3
import click
@click.command()
@click.option('--n', type=int, default=1)
def dots(n):
click.echo('.' * n)
if __name__ == '__main__':
dots()
In the example, we have the --n option which takes a number. The number determines how many
times the dot is printed to the console.
$ ./dots.py --n 17
.................
We have outputted seventeen dots.
Python click option names
The options names start with either a single dash or two dashes. Command line programs often
take both short and long options. Click derives the name of the option from the long name, if both
are used.
option_names.py
#!/usr/bin/python3
import click
@click.command()
@click.option('-s', '--string')
def output(string):
click.echo(string)
if __name__ == '__main__':
output()
In the example, we create an option with both short and long names. The name of the variable
passed to the function is string, derived from the longer option name.
$ ./option_names.py -s sky
sky
$ ./option_names.py --string cloud
cloud
We run the program using both option names.
Python click prompt for value
We can ask a user to provide a value interactively.
prompt.py
#!/usr/bin/python3
import click
@click.command()
@click.option("--name", prompt="Your name", help="Provide your name")
def hello(name):
click.echo(f"Hello, {name}")
if __name__ == '__main__':
hello()
The example asks the user for his name.
$ ./prompt.py
Your name: Peter
Hello, Peter
This is a sample output.
Python click colour output
With the secho method, we can output the text in colour. We can also use styles such as bold and
underline. The colour values are limited to a predefined set of values. For colour output we need to
have installed the colorama module.
coloured.py
#!/usr/bin/python3
import click
@click.command()
def coloured():
click.secho('Hello there', fg="blue", bold=True)
if __name__ == '__main__':
coloured()
The example outputs the text in bold blue colour.
Python click flags
Flags are boolean options that can be enabled or disabled. This can be accomplished by defining
two flags in one go separated by a slash (/) for enabling or disabling the option or with the is_flag
parameter.
flags.py
#!/usr/bin/python3
import click
@click.command()
@click.option('--blue', is_flag=True, help='message in blue color')
def hello(blue):
if blue:
click.secho('Hello there', fg='blue')
else:
click.secho('Hello there')
if __name__ == '__main__':
hello()
In the example, we define a --blue boolean option with the is_flag parameter. If set, it prints the
message in blue colour.
flags2.py
#!/usr/bin/python3
import click
@click.command()
@click.argument('word')
@click.option('--shout/--no-shout', default=False)
def output(word, shout):
if shout:
click.echo(word.upper())
else:
click.echo(word)
if __name__ == '__main__':
output()
In the second case, we define --shout and --no-shout flags. If the --shout flag is set, the
specified argument is outputted in uppercase.
Google Ads -
Sitio O cial
Con Google Ads, no hay
contratos ni mínimo de
Google Ads inversión.
$ ./flags2.py --shout sky
SKY
$ ./flags2.py --no-shout sky
sky
This is the output.
Python click environment variables
Values can be pulled from environment variables.
env_var.py
#!/usr/bin/python3
import click
import os
@click.argument('mydir', envvar='MYDIR', type=click.Path(exists=True))
@click.command()
def dolist(mydir):
click.echo(os.listdir(mydir))
if __name__ == '__main__':
dolist()
The example prints the content of the directory specified in the MYDIR environment variable.
export MYDIR=~/Documents; ./env_var.py
['test.py', 'words2.txt', 'test.php', 'words2.txt~', 'testing', 'todo.txt',
'tasks', 'links.txt', 'progs']
This is a sample output.
Python click option tuples
We can have multi-value options which become Python tuples.
multi_val.py
#!/usr/bin/python3
import click
@click.command()
@click.option('--data', required=True, type=(str, int))
def output(data):
click.echo(f'name={data[0]} age={data[1]}')
if __name__ == '__main__':
output()
In the example, the --data option takes two values that become a Python tuple. The values are
used to build a message.
$ ./multi_val.py --data Peter 23
name=Peter age=23
This is a sample output.
Specifying options multiple times
Option values can be provided multiple times and have all the values recorded. The values are
stored in a Python tuple.
multiples.py
#!/usr/bin/python3
import click
@click.command()
@click.option('--word', '-w', multiple=True)
def words(word):
click.echo('\n'.join(word))
if __name__ == '__main__':
words()
In the example, we can specify the --word/-w options multiple times.
Google Ads -
Sitio O cial
Con Google Ads, no hay
contratos ni mínimo de
Google Ads inversión.
$ ./multiples.py -w sky --word forest --word rock -w cloud
sky
forest
rock
cloud
This is a sample output.
The click.File type
The click.File type declares a parameter to be a file for reading or writing. The file is
automatically closed once the context tears down (after the command finished working).
words.txt
sky
cloud
water
forest
rock
moon
falcon
lake
We work with this text file.
head.py
#!/usr/bin/python3
import click
@click.command()
@click.argument('file_name', type=click.File('r'))
@click.argument('lines', default=-1, type=int)
def head(file_name, lines):
counter = 0
for line in file_name:
print(line.strip())
counter += 1
if counter == lines:
break
if __name__ == '__main__':
head()
We create an equivalent of the Linux head command.
$ ./head.py words.txt 4
sky
cloud
water
forest
We show the first four lines of the file.
The click.Path type
The click.Path type is similar to the click.File type. Instead of returning an open file handle it
returns just the filename.
head2.py
#!/usr/bin/python3
import click
@click.command()
@click.argument('file_name', type=click.Path(exists=True))
@click.argument('lines', default=-1, type=int)
def head(file_name, lines):
with open(file_name, 'r') as f:
counter = 0
for line in file_name:
print(line.strip())
counter += 1
if counter == lines:
break
if __name__ == '__main__':
head()
This is the head command created with the click.Path type.
Python click command groups
Commands can be added into groups. Groups are created with the @click.group decorator.
groups.py
#!/usr/bin/python3
import click
@click.group()
def messages():
pass
@click.command()
def generic():
click.echo('Hello there')
@click.command()
def welcome():
click.echo('Welcome')
messages.add_command(generic)
messages.add_command(welcome)
if __name__ == '__main__':
messages()
The example defines two groups.
$ ./groups.py --help
Usage: groups.py [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
generic
welcome
The help message shows two commands.
groups2.py
#!/usr/bin/python3
import click
@click.group()
def cli():
pass
@cli.command(name='gen')
def generic():
click.echo('Hello there')
@cli.command(name='wel')
def welcome():
click.echo('Welcome')
if __name__ == '__main__':
cli()
This is an alternative syntax for creating a command group. The commands take the name of the
function but can be given another name with the name option.
$ ./groups2.py gen
Hello there
$ ./groups2.py wel
Welcome
This is the output.
In this tutorial, we have worked with Python click module.
List all Python tutorials.
Home Facebook Twitter Github Subscribe Privacy
© 2007 - 2021 Jan Bodnar admin(at)zetcode.com
