You can get the library directly from PyPI:
pip install click
There is a screencast available which shows the basic API of click and how to build simple applications with it. It also explores how to build commands with subcommands.
Examples of click applications can be found in the documentation as well as in the GitHub repository together with readme files:
Click is based on declaring commands through decorators. Internally, there is a non-decorator interface for advanced use cases, but it’s discouraged for high-level usage.
A function becomes a click command line tool by decorating it through click.command(). At its simplest, just decorating a function with this decorator will make it into a callable script:
import click
@click.command()
def hello():
click.echo('Hello World!')
What’s happening is that the decorator converts the function into a Command which then can be invoked:
if __name__ == '__main__':
hello()
And what it looks like:
$ python hello.py
Hello World!
And the corresponding help page:
$ python hello.py --help
Usage: hello.py [OPTIONS]
Options:
--help Show this message and exit.
Why does this example use echo() instead of the regular print() function? The answer to this question is that click attempts to support both Python 2 and Python 3 the same way and to be very robust even when the environment is misconfigured. Click wants to be functional at least on a basic level even if everything is completely broken.
What this means is that the echo() function applies some error correction in case the terminal is misconfigured instead of dying with an UnicodeError.
As an added benefit, starting with click 2.0, the echo function also has good support for ANSI colors. It will automatically strip ANSI codes if the output stream is a file and if colorama is supported, ANSI colors will also work on Windows. See ANSI Colors for more information.
If you don’t need this, you can also use the print() construct / function.
Commands can be attached to other commands of type Group. This allows arbitrary nesting of scripts. As an example here is a script that implements two commands for managing databases:
@click.group()
def cli():
pass
@click.command()
def initdb():
click.echo('Initialized the database')
@click.command()
def dropdb():
click.echo('Dropped the database')
cli.add_command(initdb)
cli.add_command(dropdb)
As you can see, the group() decorator works like the command() decorator, but creates a Group object instead which can be given multiple subcommands that can be attached with Group.add_command().
For simple scripts, it’s also possible to automatically attach and create a command by using the Group.command() decorator instead. The above script can instead be written like this:
@click.group()
def cli():
pass
@cli.command()
def initdb():
click.echo('Initialized the database')
@cli.command()
def dropdb():
click.echo('Dropped the database')
To add parameters, use the option() and argument() decorators:
@click.command()
@click.option('--count', default=1, help='number of greetings')
@click.argument('name')
def hello(count, name):
for x in range(count):
click.echo('Hello %s!' % name)
What it looks like:
$ python hello.py --help
Usage: hello.py [OPTIONS] NAME
Options:
--count INTEGER number of greetings
--help Show this message and exit.