Click is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It’s the “Command Line Interface Creation Kit”. It’s highly configurable but comes with sensible defaults out of the box.
It aims to make the process of writing command line tools quick and fun while also preventing any frustration caused by the inability to implement an intended CLI API.
Click in three points:
What does it look like? Here is an example of a simple Click program:
import click
@click.command()
@click.option('--count', default=1, help='Number of greetings.')
@click.option('--name', prompt='Your name',
help='The person to greet.')
def hello(count, name):
"""Simple program that greets NAME for a total of COUNT times."""
for x in range(count):
click.echo('Hello %s!' % name)
if __name__ == '__main__':
hello()
And what it looks like when run:
$ python hello.py --count=3
Your name: John
Hello John!
Hello John!
Hello John!
It automatically generates nicely formatted help pages:
$ python hello.py --help
Usage: hello.py [OPTIONS]
Simple program that greets NAME for a total of COUNT times.
Options:
--count INTEGER Number of greetings.
--name TEXT The person to greet.
--help Show this message and exit.
You can get the library directly from PyPI:
pip install click
This part of the documentation guides you through all of the library’s usage patterns.
There are so many libraries out there for writing command line utilities; why does Click exist?
This question is easy to answer: because there is not a single command line utility for Python out there which ticks the following boxes:
There are many alternatives to Click and you can have a look at them if you enjoy them better. The obvious ones are optparse and argparse from the standard library.
Click is actually implemented as a wrapper around a mild fork of optparse and does not implement any parsing itself. The reason it’s not based on argparse is that argparse does not allow proper nesting of commands by design and has some deficiencies when it comes to POSIX compliant argument handling.
Click is designed to be fun to work with and at the same time not stand in your way. It’s not overly flexible either. Currently, for instance, it does not allow you to customize the help pages too much. This is intentional because Click is designed to allow you to nest command line utilities. The idea is that you can have a system that works together with another system by tacking two Click instances together and they will continue working as they should.
Too much customizability would break this promise.
Click was written to support the Flask microframework ecosystem because no tool could provide it with the functionality it needed.
To get an understanding of what Click is all about, I strongly recommend looking at the Complex Applications chapter to see what it’s useful for.
Click is internally based on optparse instead of argparse. This however is an implementation detail that a user does not have to be concerned with. The reason however Click is not using argparse is that it has some problematic behaviors that make handling arbitrary command line interfaces hard:
Docopt and many tools like it are cool in how they work, but very few of these tools deal with nesting of commands and composability in a way like Click. To the best of the developer’s knowledge, Click is the first Python library that aims to create a level of composability of applications that goes beyond what the system itself supports.
Docopt, for instance, acts by parsing your help pages and then parsing according to those rules. The side effect of this is that docopt is quite rigid in how it handles the command line interface. The upside of docopt is that it gives you strong control over your help page; the downside is that due to this it cannot rewrap your output for the current terminal width and it makes translations hard. On top of that docopt is restricted to basic parsing. It does not handle argument dispatching and callback invocation or types. This means there is a lot of code that needs to be written in addition to the basic help page to handle the parsing results.
Most of all, however, it makes composability hard. While docopt does support dispatching to subcommands, it for instance does not directly support any kind of automatic subcommand enumeration based on what’s available or it does not enforce subcommands to work in a consistent way.
This is fine, but it’s different from how Click wants to work. Click aims to support fully composable command line user interfaces by doing the following:
The aim of Click is to make composable systems, whereas the aim of docopt is to build the most beautiful and hand-crafted command line interfaces. These two goals conflict with one another in subtle ways. Click actively prevents people from implementing certain patterns in order to achieve unified command line interfaces. You have very little input on reformatting your help pages for instance.
The other question is why Click goes away from optparse and hardcodes certain behaviors instead of staying configurable. There are multiple reasons for this. The biggest one is that too much configurability makes it hard to achieve a consistent command line experience.
The best example for this is optparse’s callback functionality for accepting arbitrary number of arguments. Due to syntactical ambiguities on the command line, there is no way to implement fully variadic arguments. There are always tradeoffs that need to be made and in case of argparse these tradeoffs have been critical enough, that a system like Click cannot even be implemented on top of it.
In this particular case, Click attempts to stay with a handful of accepted paradigms for building command line interfaces that can be well documented and tested.
The question came up why Click does not auto correct parameters given that even optparse and argparse support automatic expansion of long arguments. The reason for this is that it’s a liability for backwards compatibility. If people start relying on automatically modified parameters and someone adds a new parameter in the future, the script might stop working. These kinds of problems are hard to find so Click does not attempt to be magical about this.
This sort of behavior however can be implemented on a higher level to support things such as explicit aliases. For more information see Command Aliases.
You can get the library directly from PyPI:
pip install click
The installation into a virtualenv is heavily recommended.
Virtualenv is probably what you want to use for developing Click applications.
What problem does virtualenv solve? Chances are that you want to use it for other projects besides your Click script. But the more projects you have, the more likely it is that you will be working with different versions of Python itself, or at least different versions of Python libraries. Let’s face it: quite often libraries break backwards compatibility, and it’s unlikely that any serious application will have zero dependencies. So what do you do if two or more of your projects have conflicting dependencies?
Virtualenv to the rescue! Virtualenv enables multiple side-by-side installations of Python, one for each project. It doesn’t actually install separate copies of Python, but it does provide a clever way to keep different project environments isolated. Let’s see how virtualenv works.
If you are on Mac OS X or Linux, chances are that one of the following two commands will work for you:
$ sudo easy_install virtualenv
or even better:
$ sudo pip install virtualenv
One of these will probably install virtualenv on your system. Maybe it’s even in your package manager. If you use Ubuntu, try:
$ sudo apt-get install python-virtualenv
If you are on Windows (or none of the above methods worked) you must install pip first. For more information about this, see installing pip. Once you have it installed, run the pip command from above, but without the sudo prefix.
Once you have virtualenv installed, just fire up a shell and create your own environment. I usually create a project folder and a venv folder within:
$ mkdir myproject
$ cd myproject
$ virtualenv venv
New python executable in venv/bin/python
Installing setuptools, pip............done.
Now, whenever you want to work on a project, you only have to activate the corresponding environment. On OS X and Linux, do the following:
$ . venv/bin/activate
If you are a Windows user, the following command is for you:
$ venv\scripts\activate
Either way, you should now be using your virtualenv (notice how the prompt of your shell has changed to show the active environment).
And if you want to go back to the real world, use the following command:
$ deactivate
After doing this, the prompt of your shell should be as familar as before.
Now, let’s move on. Enter the following command to get Click activated in your virtualenv:
$ pip install Click
A few seconds later and you are good to go.
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.
In the code you wrote so far there is a block at the end of the file which looks like this: if __name__ == '__main__':. This is traditionally how a standalone Python file looks like. With Click you can continue doing that, but there are better ways through setuptools.
There are two main (and many more) reasons for this:
The first one is that setuptools automatically generates executable wrappers for Windows so your command line utilities work on Windows too.
The second reason is that setuptools scripts work with virtualenv on Unix without the virtualenv having to be activated. This is a very useful concept which allows you to bundle your scripts with all requirements into a virtualenv.
Click is perfectly equipped to work with that and in fact the rest of the documentation will assume that you are writing applications through setuptools.
I strongly recommend to have a look at the Setuptools Integration chapter before reading the rest as the examples assume that you will be using setuptools.
When writing command line utilities, it’s recommended to write them as modules that are distributed with setuptools instead of using Unix shebangs.
Why would you want to do that? There are a bunch of reasons:
One of the problems with the traditional approach is that the first module the Python interpreter loads has an incorrect name. This might sound like a small issue but it has quite significant implications.
The first module is not called by it’s actual name, but the interpreter renames it to __main__. While that is a perfectly valid name it means that if another piece of code wants to import from that module it will trigger the import a second time under it’s real name and all the sudden your code is imported twice.
Not on all platforms are things that easy to execute. On Linux and OS X you can add a comment to the beginning of the file (#/usr/bin/env python) and your script works like an executable (assuming it has the executable bit set). This however does not work on Windows. While on Windows you can associate interpreters with file extensions (like having everything ending in .py execute through the Python interpreter) you will then run into issues if you want to use the script in a virtualenv.
In fact running a script in a virtualenv is an issue with OS X and Linux as well. With the traditional approach you need to have the whole virtualenv activated so that the correct Python interpreter is used. Not very user friendly.
The main trick only works if the script is a Python module. If your application grows too large and you want to start using a package you will run into issues.
To bundle your script with setuptools, all you need is the script in a Python package and a setup.py file.
Imagine this directory structure:
yourscript.py
setup.py
Contents of yourscript.py:
import click
@click.command()
def cli():
"""Example script."""
click.echo('Hello World!')
Contents of setup.py:
from setuptools import setup
setup(
name='yourscript',
version='0.1',
py_modules=['yourscript'],
install_requires=[
'Click',
],
entry_points='''
[console_scripts]
yourscript=yourscript:cli
''',
)
The magic is in the entry_points parameter. Below console_scripts, each line identifies one console script. The first part before the equals sign (=) is the name of the script that should be generated, the second part is the import path followed by a colon (:) with the Click command.
That’s it.
To test the script, you can make a new virtualenv and then install your package:
$ virtualenv venv
$ . venv/bin/activate
$ pip install --editable .
Afterwards, your command should be available:
$ yourscript
Hello World!
If your script is growing and you want to switch over to your script being contained in a Python package the changes necessary are minimal. Let’s assume your directory structure changed to this:
yourpackage/
main.py
utils.py
scripts/
yourscript.py
In this case instead of using py_modules in your setup.py file you can use packages and the automatic package finding support of setuptools. In addition to that it’s also recommended to include other package data.
These would be the modified contents of setup.py:
from setuptools import setup, find_packages
setup(
name='yourpackage',
version='0.1',
packages=find_packages(),
include_package_data=True,
install_requires=[
'Click',
],
entry_points='''
[console_scripts]
yourscript=yourpackage.scripts.yourscript:cli
''',
)
Click supports two types of parameters for scripts: options and arguments. There is generally some confusion among authors of command line scripts of when to use which, so here is a quick overview of the differences. As its name indicates, an option is optional. While arguments can be optional within reason, they are much more restricted in how optional they can be.
To help you decide between options and arguments, the recommendation is to use arguments exclusively for things like going to subcommands or input filenames / URLs, and have everything else be an option instead.
Arguments can do less than options. The following features are only available for options:
On the other hand arguments unlike options can accept an arbitrary number of arguments. Options can strictly ever only accept a fixed number of arguments (defaults to 1).
Parameters can be of different types. Types can be implemented with different behavior and some are supported out of the box:
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).
Files can be opened for reading or writing. The special value - indicates stdin or stdout depending on the mode.
By default, the file is opened for reading text data, but it can also be opened in binary mode or for writing. The encoding parameter can be used to force a specific encoding.
The lazy flag controls if the file should be opened immediately or upon first IO. The default is to be non lazy for standard input and output streams as well as files opened for reading, lazy otherwise.
Starting with Click 2.0, files can also be opened atomically in which case all writes go into a separate file in the same folder and upon completion the file will be moved over to the original location. This is useful if a file regularly read by other users is modified.
See File Arguments for more information.
The path type is similar to the File type but it performs different checks. First of all, instead of returning a open file handle it returns just the filename. Secondly, it can perform various basic checks about what the file or directory should be.
| Parameters: |
|
|---|
The choice type allows a value to checked against a fixed set of supported values. All of these values have to be strings.
See Choice Options for an example.
A parameter that works similar to click.INT but restricts the value to fit into a range. The default behavior is to fail if the value falls outside the range, but it can also be silently clamped between the two edges.
See Range Options for an example.
Custom parameter types can be implemented by subclassing click.ParamType. For simple cases, passing a Python function that fails with a ValueError is also supported, though discouraged.
Parameters (both options and arguments) accept a number of positional arguments which are the parameter declarations. Each string with a single dash is added as short argument; each string starting with a double dash as long one. If a string is added without any dashes, it becomes the internal parameter name which is also used as variable name.
If a parameter is not given a name without dashes, a name is generated automatically by taking the longest argument and converting all dashes to underscores. For an option with ('-f', '--foo-bar'), the parameter name is foo_bar. For an option with ('-x',), the parameter is x. For an option with ('-f', '--filename', 'dest'), the parameter is called dest.
To implement a custom type, you need to subclass the ParamType class. Types can be invoked with or without context and parameter object, which is why they need to be able to deal with this.
The following code implements an integer type that accepts hex and octal numbers in addition to normal integers, and converts them into regular integers:
import click
class BasedIntParamType(click.ParamType):
name = 'integer'
def convert(self, value, param, ctx):
try:
if value[:2].lower() == '0x':
return int(value[2:], 16)
elif value[:1] == '0':
return int(value, 8)
return int(value, 10)
except ValueError:
self.fail('%s is not a valid integer' % value, param, ctx)
BASED_INT = BasedIntParamType()
As you can see, a subclass needs to implement the ParamType.convert() method and optionally provide the ParamType.name attribute. The latter can be used for documentation purposes.
Adding options to commands can be accomplished by the option() decorator. Since options can come in various different versions, there are a ton of parameters to configure their behavior. Options in click are distinct from positional arguments.
The most basic option is a value option. These options accept one argument which is a value. If no type is provided, the type of the default value is used. If no default value is provided, the type is assumed to be STRING. By default, the name of the parameter is the first long option defined; otherwise the first short one is used.
@click.command()
@click.option('--n', default=1)
def dots(n):
click.echo('.' * n)
And on the command line:
$ dots --n=2
..
In this case the option is of type INT because the default value is an integer.
Sometimes, you have options that take more than one argument. For options, only a fixed number of arguments is supported. This can be configured by the nargs parameter. The values are then stored as a tuple.
@click.command()
@click.option('--pos', nargs=2, type=float)
def findme(pos):
click.echo('%s / %s' % pos)
And on the command line:
$ findme --pos 2.0 3.0
2.0 / 3.0
Similarly to nargs, there is also the case of wanting to support a parameter being provided multiple times to and have all values recorded – not just the last one. For instance, git commit -m foo -m bar would record two lines for the commit message: foo and bar. This can be accomplished with the multiple flag:
Example:
@click.command()
@click.option('--message', '-m', multiple=True)
def commit(message):
click.echo('\n'.join(message))
And on the command line:
$ commit -m foo -m bar
foo
bar
In some very rare circumstances, it is interesting to use the repetition of options to count an integer up. This can be used for verbosity flags, for instance:
@click.command()
@click.option('-v', '--verbose', count=True)
def log(verbose):
click.echo('Verbosity: %s' % verbose)
And on the command line:
$ log -vvv
Verbosity: 3
Boolean flags are 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. (If a slash is in an option string, Click automatically knows that it’s a boolean flag and will pass is_flag=True implicitly.) Click always wants you to provide an enable and disable flag so that you can change the default later.
Example:
import os
@click.command()
@click.option('--shout/--no-shout', default=False)
def info(shout):
rv = os.uname()[0]
if shout:
rv = rv.upper() + '!!!!111'
click.echo(rv)
And on the command line:
$ info --shout
LINUX!!!!111
$ info --no-shout
Linux
If you really don’t want an off-switch, you can just define one and manually inform Click that something is a flag:
import os
@click.command()
@click.option('--shout', is_flag=True)
def info(shout):
rv = os.uname()[0]
if shout:
rv = rv.upper() + '!!!!111'
click.echo(rv)
And on the command line:
$ info --shout
LINUX!!!!111
Note that if a slash is contained in your option already (for instance, if you use Windows-style parameters where / is the prefix character), you can alternatively split the parameters through ; instead:
@click.command()
@click.option('/debug;/no-debug')
def log(debug):
click.echo('debug=%s' % debug)
if __name__ == '__main__':
log()
In addition to boolean flags, there are also feature switches. These are implemented by setting multiple options to the same parameter name and defining a flag value. Note that by providing the flag_value parameter, Click will implicitly set is_flag=True.
To set a default flag, assign a value of True to the flag that should be the default.
import os
@click.command()
@click.option('--upper', 'transformation', flag_value='upper',
default=True)
@click.option('--lower', 'transformation', flag_value='lower')
def info(transformation):
click.echo(getattr(os.uname()[0], transformation)())
And on the command line:
$ info --upper
LINUX
$ info --lower
linux
$ info
LINUX
Sometimes, you want to have a parameter be a choice of a list of values. In that case you can use Choice type. It can be instantiated with a list of valid values.
Example:
@click.command()
@click.option('--hash-type', type=click.Choice(['md5', 'sha1']))
def digest(hash_type):
click.echo(hash_type)
What it looks like:
$ digest --hash-type=md5
md5
$ digest --hash-type=foo
Usage: digest [OPTIONS]
Error: Invalid value for "--hash-type": invalid choice: foo. (choose from md5, sha1)
$ digest --help
Usage: digest [OPTIONS]
Options:
--hash-type [md5|sha1]
--help Show this message and exit.
In some cases, you want parameters that can be provided from the command line, but if not provided, ask for user input instead. This can be implemented with Click by defining a prompt string.
Example:
@click.command()
@click.option('--name', prompt=True)
def hello(name):
click.echo('Hello %s!' % name)
And what it looks like:
$ hello --name=John
Hello John!
$ hello
Name: John
Hello John!
If you are not happy with the default prompt string, you can ask for a different one:
@click.command()
@click.option('--name', prompt='Your name please')
def hello(name):
click.echo('Hello %s!' % name)
What it looks like:
$ hello
Your name please: John
Hello John!
Click also supports hidden prompts and asking for confirmation. This is useful for password input:
@click.command()
@click.option('--password', prompt=True, hide_input=True,
confirmation_prompt=True)
def encrypt(password):
click.echo('Encrypting password to %s' % password.encode('rot13'))
What it looks like:
$ encrypt
Password:
Repeat for confirmation:
Encrypting password to frperg
Because this combination of parameters is quite common, this can also be replaced with the password_option() decorator:
@click.command()
@click.password_option()
def encrypt(password):
click.echo('Encrypting password to %s' % password.encode('rot13'))
Sometimes, you want a parameter to completely change the execution flow. For instance, this is the case when you want to have a --version parameter that prints out the version and then exits the application.
In such cases, you need two concepts: eager parameters and a callback. An eager parameter is a parameter that is handled before others, and a callback is what executes after the parameter is handled. The eagerness is necessary so that an earlier required parameter does not produce an error message. For instance, if --version was not eager and a parameter --foo was required and defined before, you would need to specify it for --version to work. For more information, see Callback Evaluation Order.
A callback is a function that is invoked with two parameters: the current Context and the value. The context provides some useful features such as quitting the application and gives access to other already processed parameters.
Here an example for a --version flag:
def print_version(ctx, param, value):
if not value or ctx.resilient_parsing:
return
click.echo('Version 1.0')
ctx.exit()
@click.command()
@click.option('--version', is_flag=True, callback=print_version,
expose_value=False, is_eager=True)
def hello():
click.echo('Hello World!')
The expose_value parameter prevents the pretty pointless version parameter from being passed to the callback. If that was not specified, a boolean would be passed to the hello script. The resilient_parsing flag is applied to the context if Click wants to parse the command line without any destructive behavior that would change the execution flow. In this case, because we would exit the program, we instead do nothing.
What it looks like:
$ hello
Hello World!
$ hello --version
Version 1.0
Callback Signature Changes
In Click 2.0 the signature for callbacks changed. For more information about these changes see Upgrading to 2.0.
For dangerous operations, it’s very useful to be able to ask a user for confirmation. This can be done by adding a boolean --yes flag and asking for confirmation if the user did not provide it and to fail in a callback:
def abort_if_false(ctx, param, value):
if not value:
ctx.abort()
@click.command()
@click.option('--yes', is_flag=True, callback=abort_if_false,
expose_value=False,
prompt='Are you sure you want to drop the db?')
def dropdb():
click.echo('Dropped all tables!')
And what it looks like on the command line:
$ dropdb
Are you sure you want to drop the db? [y/N]: n
Aborted!
$ dropdb --yes
Dropped all tables!
Because this combination of parameters is quite common, this can also be replaced with the confirmation_option() decorator:
@click.command()
@click.confirmation_option(help='Are you sure you want to drop the db?')
def dropdb():
click.echo('Dropped all tables!')
Callback Signature Changes
In Click 2.0 the signature for callbacks changed. For more information about these changes see Upgrading to 2.0.
A very useful feature of Click is the ability to accept parameters from environment variables in addition to regular parameters. This allows tools to be automated much easier. For instance, you might want to pass a configuration file with a --config parameter but also support exporting a TOOL_CONFIG=hello.cfg key-value pair for a nicer development experience.
This is supported by Click in two ways. One is to automatically build environment variables which is supported for options only. To enable this feature, the auto_envvar_prefix parameter needs to be passed to the script that is invoked. Each command and parameter is then added as an uppercase underscore-separated variable. If you have a subcommand called foo taking an option called bar and the prefix is MY_TOOL, then the variable is MY_TOOL_FOO_BAR.
Example usage:
@click.command()
@click.option('--username')
def greet(username):
click.echo('Hello %s!' % username)
if __name__ == '__main__':
greet(auto_envvar_prefix='GREETER')
And from the command line:
$ export GREETER_USERNAME=john
$ greet
Hello john!
The second option is to manually pull values in from specific environment variables by defining the name of the environment variable on the option.
Example usage:
@click.command()
@click.option('--username', envvar='USERNAME')
def greet(username):
click.echo('Hello %s!' % username)
if __name__ == '__main__':
greet()
And from the command line:
$ export USERNAME=john
$ greet
Hello john!
In that case it can also be a list of different environment variables where the first one is picked.
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 for those on every colon (:), and for Windows, on every semicolon (;).
Example usage:
@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()
And from the command line:
$ export PATHS=./foo/bar:./test
$ perform
./foo/bar
./test
Click can deal with alternative prefix characters other than - for options. This is for instance useful if you want to handle slashes as parameters / or something similar. Note that this is strongly discouraged in general because Click wants developers to stay close to POSIX semantics. However in certain situations this can be useful:
@click.command()
@click.option('+w/-w')
def chmod(w):
click.echo('writable=%s' % w)
if __name__ == '__main__':
chmod()
And from the command line:
$ chmod +w
writable=True
$ chmod -w
writable=False
Note that if you are using / as prefix character and you want to use a boolean flag you need to separate it with ; instead of /:
@click.command()
@click.option('/debug;/no-debug')
def log(debug):
click.echo('debug=%s' % debug)
if __name__ == '__main__':
log()
A special mention should go to the IntRange type, which works very similarly to the INT type, but restricts the value to fall into a specific range (inclusive on both edges). It has two modes:
Example:
@click.command()
@click.option('--count', type=click.IntRange(0, 20, clamp=True))
@click.option('--digit', type=click.IntRange(0, 10))
def repeat(count, digit):
click.echo(str(digit) * count)
if __name__ == '__main__':
repeat()
And from the command line:
$ repeat --count=1000 --digit=5
55555555555555555555
$ repeat --count=1000 --digit=12
Usage: repeat [OPTIONS]
Error: Invalid value for "--digit": 12 is not in the valid range of 0 to 10.
If you pass None for any of the edges, it means that the range is open at that side.
Changed in version 2.0.
If you want to apply custom validation logic, you can do this in the parameter callbacks. These callbacks can both modify values as well as raise errors if the validation does not work.
In Click 1.0, you can only raise the UsageError but starting with Click 2.0, you can also raise the BadParameter error, which has the added advantage that it will automatically format the error message to also contain the parameter name.
Example:
def validate_rolls(ctx, param, value):
try:
rolls, dice = map(int, value.split('d', 2))
return (dice, rolls)
except ValueError:
raise click.BadParameter('rolls need to be in format NdM')
@click.command()
@click.option('--rolls', callback=validate_rolls, default='1d6')
def roll(rolls):
click.echo('Rolling a %d-sided dice %d time(s)' % rolls)
if __name__ == '__main__':
roll()
And what it looks like:
$ roll --rolls=42
Usage: roll [OPTIONS]
Error: Invalid value for "--rolls": rolls need to be in format NdM
$ roll --rolls=2d12
Rolling a 12-sided dice 2 time(s)
Arguments work similarly to options but are positional. They also only support a subset of the features of options due to their syntactical nature. Click will also not attempt to document arguments for you and wants you to document them manually in order to avoid ugly help pages.
The most basic option is a simple string argument of one value. If no type is provided, the type of the default value is used, and if no default value is provided, the type is assumed to be STRING.
Example:
@click.command()
@click.argument('filename')
def touch(filename):
click.echo(filename)
And what it looks like:
$ touch foo.txt
foo.txt
The second most common version is variadic arguments where a specific (or unlimited) number of arguments is accepted. This can be controlled with the nargs parameter. If it is set to -1, then an unlimited number of arguments is accepted.
The value is then passed as a tuple. Note that only one argument can be set to nargs=-1, as it will eat up all arguments.
Example:
@click.command()
@click.argument('src', nargs=-1)
@click.argument('dst', nargs=1)
def copy(src, dst):
for fn in src:
click.echo('move %s to folder %s' % (fn, dst))
And what it looks like:
$ copy foo.txt bar.txt my_folder
move foo.txt to folder my_folder
move bar.txt to folder my_folder
Note that this is not how you would write this application. The reason for this is that in this particular example the arguments are defined as strings. Filenames, however, are not strings! They might be on certain operating systems, but not necessarily on all. For better ways to write this, see the next sections.
Note on Non-Empty Variadic Arguments
If you come from argparse, you might be missing support for setting nargs to + to indicate that at least one argument is required.
This is supported by setting required=True. However, this should not be used if you can avoid it as we believe scripts should gracefully degrade into becoming noops if a variadic argument is empty. The reason for this is that very often, scripts are invoked with wildcard inputs from the command line and they should not error out if the wildcard is empty.
Since all the examples have already worked with filenames, it makes sense to explain how to deal with files properly. Command line tools are more fun if they work with files the Unix way, which is to accept - as a special file that refers to stdin/stdout.
Click supports this through the click.File type which intelligently handles files for you. It also deals with Unicode and bytes correctly for all versions of Python so your script stays very portable.
Example:
@click.command()
@click.argument('input', type=click.File('rb'))
@click.argument('output', type=click.File('wb'))
def inout(input, output):
while True:
chunk = input.read(1024)
if not chunk:
break
output.write(chunk)
And what it does:
$ inout - hello.txt
hello
^D
$ inout hello.txt -
hello
In the previous example, the files were opened immediately. But what if we just want the filename? The naïve way is to use the default string argument type. However, remember that Click is Unicode-based, so the string will always be a Unicode value. Unfortunately, filenames can be Unicode or bytes depending on which operating system is being used. As such, the type is insufficient.
Instead, you should be using the Path type, which automatically handles this ambiguity. Not only will it return either bytes or Unicode depending on what makes more sense, but it will also be able to do some basic checks for you such as existence checks.
Example:
@click.command()
@click.argument('f', type=click.Path(exists=True))
def touch(f):
click.echo(click.format_filename(f))
And what it does:
$ touch hello.txt
hello.txt
$ touch missing.txt
Usage: touch [OPTIONS] F
Error: Invalid value for "f": Path "missing.txt" does not exist.
The FileType type has one problem it needs to deal with, and that is to decide when to open a file. The default behavior is to be “intelligent” about it. What this means is that it will open stdin/stdout and files opened for reading immediately. This will give the user direct feedback when a file cannot be opened, but it will only open files for writing the first time an IO operation is performed by automatically wrapping the file in a special wrapper.
This behavior can be forced by passing lazy=True or lazy=False to the constructor. If the file is opened lazily, it will fail its first IO operation by raising an FileError.
Since files opened for writing will typically immediately empty the file, the lazy mode should only be disabled if the developer is absolutely sure that this is intended behavior.
Forcing lazy mode is also very useful to avoid resource handling confusion. If a file is opened in lazy mode, it will receive a close_intelligently method that can help figure out if the file needs closing or not. This is not needed for parameters, but is necessary for manually prompting with the prompt() function as you do not know if a stream like stdout was opened (which was already open before) or a real file that needs closing.
Starting with Click 2.0, it is also possible to open files in atomic mode by passing atomic=True. In atomic mode, all writes go into a separate file in the same folder, and upon completion, the file will be moved over to the original location. This is useful if a file regularly read by other users is modified.
Like options, arguments can also grab values from an environment variable. Unlike options, however, this is only supported for explicitly named environment variables.
Example usage:
@click.command()
@click.argument('src', envvar='SRC', type=click.File('r'))
def echo(src):
click.echo(src.read())
And from the command line:
$ export SRC=hello.txt
$ echo
Hello World!
In that case, it can also be a list of different environment variables where the first one is picked.
Generally, this feature is not recommended because it can cause the user a lot of confusion.
Sometimes, you want to process arguments that look like options. For instance, imagine you have a file named -foo.txt. If you pass this as an argument in this manner, Click will treat it as an option.
To solve this, Click does what any POSIX style command line script does, and that is to accept the string -- as a separator for options and arguments. After the -- marker, all further parameters are accepted as arguments.
Example usage:
@click.command()
@click.argument('files', nargs=-1, type=click.Path())
def touch(files):
for filename in files:
click.echo(filename)
And from the command line:
$ touch -- -foo.txt bar.txt
-foo.txt
bar.txt
The most important feature of Click is the concept of arbitrarily nesting command line utilities. This is implemented through the Command and Group (actually MultiCommand).
For a regular command, the callback is executed whenever the command runs. If the script is the only command, it will always fire (unless a parameter callback prevents it. This for instance happens if someone passes --help to the script).
For groups and multi commands, the situation looks different. In this case, the callback fires whenever a subcommand fires (unless this behavior is changed). What this means in practice is that an outer command runs when an inner command runs:
@click.group()
@click.option('--debug/--no-debug', default=False)
def cli(debug):
click.echo('Debug mode is %s' % ('on' if debug else 'off'))
@cli.command()
def sync():
click.echo('Synching')
Here is what this looks like:
$ tool.py
Usage: tool.py [OPTIONS] COMMAND [ARGS]...
Options:
--debug / --no-debug
--help Show this message and exit.
Commands:
sync
$ tool.py --debug sync
Debug mode is on
Synching
Click strictly separates parameters between commands and subcommands. What this means is that options and arguments for a specific command have to be specified after the command name itself, but before any other command names.
This behavior is already observable with the predefined --help option. Suppose we have a program called tool.py, containing a subcommand called sub.
As you can see from the earlier example, the basic command group accepts a debug argument which is passed to its callback, but not to the sync command itself. The sync command only accepts its own arguments.
This allows tools to act completely independent of each other, but how does one command talk to a nested one? The answer to this is the Context.
Each time a command is invoked, a new context is created and linked with the parent context. Normally, you can’t see these contexts, but they are there. Contexts are passed to parameter callbacks together with the value automatically. Commands can also ask for the context to be passed by marking themselves with the pass_context() decorator. In that case, the context is passed as first argument.
The context can also carry a program specified object that can be used for the program’s purposes. What this means is that you can build a script like this:
@click.group()
@click.option('--debug/--no-debug', default=False)
@click.pass_context
def cli(ctx, debug):
ctx.obj['DEBUG'] = debug
@cli.command()
@click.pass_context
def sync(ctx):
click.echo('Debug is %s' % (ctx.obj['DEBUG'] and 'on' or 'off'))
if __name__ == '__main__':
cli(obj={})
If the object is provided, each context will pass the object onwards to its children, but at any level a context’s object can be overridden. To reach to a parent, context.parent can be used.
In addition to that, instead of passing an object down, nothing stops the application from modifying global state. For instance, you could just flip a global DEBUG variable and be done with it.
As you have seen in the earlier example, a decorator can change how a command is invoked. What actually happens behind the scenes is that callbacks are always invoked through the Context.invoke() method which automatically invokes a command correctly (by either passing the context or not).
This is very useful when you want to write custom decorators. For instance, a common pattern would be to configure an object representing state and then storing it on the context and then to use a custom decorator to find the most recent object of this sort and pass it as first argument.
For instance, the pass_obj() decorator can be implemented like this:
from functools import update_wrapper
def pass_obj(f):
@click.pass_context
def new_func(ctx, *args, **kwargs):
return ctx.invoke(f, ctx.obj, *args, **kwargs)
return update_wrapper(new_func, f)
The Context.invoke() command will automatically invoke the function in the correct way, so the function will either be called with f(ctx, obj) or f(obj) depending on whether or not it itself is decorated with with_context().
This is a very powerful context that can be used to build very complex nested applications; see Complex Applications for more information.
By default, a group or multi command is not invoked unless a subcommand is passed. In fact, not providing a command automatically passes --help by default. This behavior can be changed by passing invoke_without_command=True to a group. In that case, the callback is always invoked instead of showing the help page. The context object also includes information about whether or not the invocation would go to a subcommand.
Example:
@click.group(invoke_without_command=True)
@click.pass_context
def cli(ctx):
if ctx.invoked_subcommand is None:
click.echo('I was invoked without subcommand')
else:
click.echo('I am about to invoke %s' % ctx.invoked_subcommand)
@cli.command()
def sync():
click.echo('The subcommand')
And how it works in practice:
$ tool
I was invoked without subcommand
$ tool sync
I am about to invoke sync
The subcommand
In addition to using click.group(), you can also build your own custom multi commands. This is useful when you want to support commands being loaded lazily from plugins.
A custom multi command just needs to implement a list and load method:
import click
import os
plugin_folder = os.path.join(os.path.dirname(__file__), 'commands')
class MyCLI(click.MultiCommand):
def list_commands(self, ctx):
rv = []
for filename in os.listdir(plugin_folder):
if filename.endswith('.py'):
rv.append(filename[:-3])
rv.sort()
return rv
def get_command(self, ctx, name):
ns = {}
fn = os.path.join(plugin_folder, name + '.py')
with open(fn) as f:
code = compile(f.read(), fn, 'exec')
eval(code, ns, ns)
return ns['cli']
cli = MyCLI(help='This tool\'s subcommands are loaded from a '
'plugin folder dynamically.')
if __name__ == '__main__':
cli()
These custom classes can also be used with decorators:
@click.command(cls=MyCLI)
def cli():
pass
In addition to implementing custom multi commands, it can also be interesting to merge multiple together into one script. While this is generally not as recommended as it nests one below the other, the merging approach can be useful in some circumstances for a nicer shell experience.
The default implementation for such a merging system is the CommandCollection class. It accepts a list of other multi commands and makes the commands available on the same level.
Example usage:
import click
@click.group()
def cli1():
pass
@cli1.command()
def cmd1():
"""Command on cli1"""
@click.group()
def cli2():
pass
@cli2.command()
def cmd2():
"""Command on cli2"""
cli = click.CommandCollection(sources=[cli1, cli2])
if __name__ == '__main__':
cli()
And what it looks like:
$ cli --help
Usage: cli [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
cmd1 Command on cli1
cmd2 Command on cli2
In case a command exists in more than one source, the first source wins.
New in version 3.0.
Sometimes it is useful to be allowed to invoke more than one subcommand in one go. For instance if you have installed a setuptools package before ouy might be familiar with the setup.py sdist bdist_wheel upload command chain which invokes dist before bdist_wheel before upload. Starting with Click 3.0 this is very simple to implement. All you have to do is to pass chain=True to your multicommand:
@click.group(chain=True)
def cli():
pass
@cli.command('sdist')
def sdist():
click.echo('sdist called')
@cli.command('bdist_wheel')
def bdist_wheel():
click.echo('bdist_wheel called')
Now you can invoke it like this:
$ setup.py sdist bdist_wheel
sdist called
bdist_wheel called
When using multi command chaining you can only have one command (the last) use nargs=-1 on an argument. Other than that there are no restrictions on how they work. They can accept options and arguments as normal.
Another note: the Context.invoked_subcommand attribute is a bit useless for multi commands as it will give '*' as value if more than one command is invoked. This is necessary because the handling of subcommands happens one after another so the exact subcommands that will be handled are not yet available when the callback fires.
New in version 3.0.
A very common usecase of multi command chaining is to have one command process the result of the previous command. There are various ways in which this can be facilitated. The most obvious way is to store a value on the context object and process it from function to function. This works by decorating a function with pass_context() after which the context object is provided and a subcommand can store it’s data there.
Another way to accomplish this is to setup pipelines by returning processing functions. Think of it like this: when a subcommand gets invoked it processes all of it’s parameters and comes up with a plan of how to do it’s processing. At that point it then returns a processing function and returns.
Where do the returned functions go? The chained multicommand can register a callback with MultiCommand.resultcallback() that goes over all these functions and then invoke them.
To make this a bit more concrete consider this example:
@click.group(chain=True, invoke_without_command=True)
@click.option('-i', '--input', type=click.File('r'))
def cli(input):
pass
@cli.resultcallback()
def process_pipeline(processors, input):
iterator = (x.rstrip('\r\n') for x in input)
for processor in processors:
iterator = processor(iterator)
for item in iterator:
click.echo(item)
@cli.command('uppercase')
def make_uppercase():
def processor(iterator):
for line in iterator:
yield line.upper()
return processor
@cli.command('lowercase')
def make_lowercase():
def processor(iterator):
for line in iterator:
yield line.lower()
return processor
@cli.command('strip')
def make_strip():
def processor(iterator):
for line in iterator:
yield line.strip()
return processor
That’s a lot in one go, so let’s go through it step by step.
After that point we can register as many subcommands as we want and each subcommand can return a processor function to modify the stream of lines.
One important thing of note is that Click shuts down the context after each callback has been run. This means that for instance file types cannot be accessed in the processor functions as the files will already be closed there. This limitation is unlikely to change because it would make resource handling much more complicated. For such it’s recommended to not use the file type and manually open the file through open_file().
For a more complex example that also improves upon handling of the pipelines have a look at the imagepipe multi command chaining demo in the Click repository. It implements a pipeline based image editing tool that has a nice internal structure for the pipelines.
By default, the default value for a parameter is pulled from the default flag that is provided when it’s defined, but that’s not the only place defaults can be loaded from. The other place is the Context.default_map (a dictionary) on the context. This allows defaults to be loaded from a configuration file to override the regular defaults.
This is useful if you plug in some commands from another package but you’re not satisfied with the defaults.
The default map can be nested arbitrarily for each subcommand and provided when the script is invoked. Alternatively, it can also be overriden at any point by commands. For instance, a top-level command could load the defaults from a configuration file.
Example usage:
import click
@click.group()
def cli():
pass
@cli.command()
@click.option('--port', default=8000)
def runserver(port):
click.echo('Serving on http://127.0.0.1:%d/' % port)
if __name__ == '__main__':
cli(default_map={
'runserver': {
'port': 5000
}
})
And in action:
$ cli runserver
Serving on http://127.0.0.1:5000/
New in version 2.0.
Starting with Click 2.0 you can override defaults for contexts not just when calling your script, but also in the decorator that declares a command. For instance given the previous example which defines a custom default_map this can also be accomplished in the decorator now.
This example does the same as the previous example:
import click
CONTEXT_SETTINGS = dict(
default_map={'runserver': {'port': 5000}}
)
@click.group(context_settings=CONTEXT_SETTINGS)
def cli():
pass
@cli.command()
@click.option('--port', default=8000)
def runserver(port):
click.echo('Serving on http://127.0.0.1:%d/' % port)
if __name__ == '__main__':
cli()
And again the example in action:
$ cli runserver
Serving on http://127.0.0.1:5000/
New in version 3.0.
One of the new introductions in Click 3.0 is the full support for return values from command callbacks. This enables a whole range of features that were previously hard to implement.
In essence any command callback can now return a value. This return value is bubbled to certain receivers. One usecase for this has already been show in the example of Multi Command Chaining where it has been demonstrated that chained multi commands can have callbacks that process all return values.
When working with command return values in Click, this is what you need to know:
Click supports prompts in two different places. The first is automated prompts when the parameter handling happens, and the second is to ask for prompts at a later point independently.
This can be accomplished with the prompt() function, which asks for valid input according to a type, or the confirm() function, which asks for confirmation (yes/no).
Option prompts are integrated into the option interface. See Prompting for more information. Internally, it automatically calls either prompt() or confirm() as necessary.
To manually ask for user input, you can use the prompt() function. By default, it accepts any Unicode string, but you can ask for any other type. For instance, you can ask for a valid integer:
value = click.prompt('Please enter a valid integer', type=int)
Additionally, the type will be determined automatically if a default value is provided. For instance, the following will only accept floats:
value = click.prompt('Please enter a number', default=42.0)
To ask if a user wants to continue with an action, the confirm() function comes in handy. By default, it returns the result of the prompt as a boolean value:
if click.confirm('Do you want to continue?'):
click.echo('Well done!')
There is also the option to make the function automatically abort the execution of the program if it does not return True:
click.confirm('Do you want to continue?', abort=True)
Click makes it very easy to document your command line tools. First of all, it automatically generates help pages for you. While these are currently not customizable in terms of their layout, all of the text can be changed.
Commands and options accept help arguments. In the case of commands, the docstring of the function is automatically used if provided.
Simple example:
@click.command()
@click.option('--count', default=1, help='number of greetings')
@click.argument('name')
def hello(count, name):
"""This script prints hello NAME COUNT times."""
for x in range(count):
click.echo('Hello %s!' % name)
And what it looks like:
$ hello --help
Usage: hello [OPTIONS] NAME
This script prints hello NAME COUNT times.
Options:
--count INTEGER number of greetings
--help Show this message and exit.
Arguments cannot be documented this way. This is to follow the general convention of Unix tools of using arguments for only the most necessary things and to document them in the introduction text by referring to them by name.
The default behavior of Click is to rewrap text based on the width of the terminal. In some circumstances, this can become a problem. The main issue is when showing code examples, where newlines are significant.
Rewrapping can be disabled on a per-paragraph basis by adding a line with solely the \b escape marker in it. This line will be removed from the help text and rewrapping will be disabled.
Example:
@click.command()
def cli():
"""First paragraph.
This is a very long second paragraph and as you
can see wrapped very early in the source text
but will be rewrapped to the terminal width in
the final output.
\b
This is
a paragraph
without rewrapping.
And this is a paragraph
that will be rewrapped again.
"""
And what it looks like:
$ cli --help
Usage: cli [OPTIONS]
First paragraph.
This is a very long second paragraph and as you can see wrapped very early
in the source text but will be rewrapped to the terminal width in the
final output.
This is
a paragraph
without rewrapping.
And this is a paragraph that will be rewrapped again.
Options:
--help Show this message and exit.
Options and parameters accept a metavar argument that can change the meta variable in the help page. The default version is the parameter name in uppercase with underscores, but can be annotated differently if desired. This can be customized at all levels:
@click.command(options_metavar='<options>')
@click.option('--count', default=1, help='number of greetings',
metavar='<int>')
@click.argument('name', metavar='<name>')
def hello(count, name):
"""This script prints hello <name> <int> times."""
for x in range(count):
click.echo('Hello %s!' % name)
Example:
$ hello --help
Usage: hello <options> <name>
This script prints hello <name> <int> times.
Options:
--count <int> number of greetings
--help Show this message and exit.
For commands, a short help snippet is generated. By default, it’s the first sentence of the help message of the command, unless it’s too long. This can also be overridden:
@click.group()
def cli():
"""A simple command line tool."""
@cli.command('init', short_help='init the repo')
def init():
"""Initializes the repository."""
@cli.command('delete', short_help='delete the repo')
def delete():
"""Deletes the repository."""
And what it looks like:
$ repo.py
Usage: repo.py [OPTIONS] COMMAND [ARGS]...
A simple command line tool.
Options:
--help Show this message and exit.
Commands:
delete delete the repo
init init the repo
New in version 2.0.
The help parameter is implemented in Click in a very special manner. Unlike regular parameters it’s automatically added by Click for any command and it performs automatic conflict resolution. By default it’s called --help, but this can be changed. If a command itself implements a parameter with the same name, the default help parameter stops accepting it. There is a context setting that can be used to override the names of the help parameters called help_option_names.
This example changes the default parameters to -h and --help instead of just --help:
CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])
@click.command(context_settings=CONTEXT_SETTINGS)
def cli():
pass
And what it looks like:
$ cli -h
Usage: cli [OPTIONS]
Options:
-h, --help Show this message and exit.
Click is designed to assist with the creation of complex and simple CLI tools alike. However, the power of its design is the ability to arbitrarily nest systems together. For instance, if you have ever used Django, you will have realized that it provides a command line utility, but so does Celery. When using Celery with Django, there are two tools that need to interact with each other and be cross-configured.
In a theoretical world of two separate Click command line utilities, they could solve this problem by nesting one inside the other. For instance, the web framework could also load the commands for the message queue framework.
To understand how this works, you need to understand two concepts: contexts and the calling convention.
Whenever a Click command is executed, a Context object is created which holds state for this particular invocation. It remembers parsed parameters, what command created it, which resources need to be cleaned up at the end of the function, and so forth. It can also optionally hold an application-defined object.
Context objects build a linked list until they hit the top one. Each context is linked to a parent context. This allows a command to work below another command and store its own information there without having to be afraid of altering up the state of the parent command.
Because the parent data is available, however, it is possible to navigate to it if needed.
Most of the time, you do not see the context object, but when writing more complex applications it comes in handy. This brings us to the next point.
When a Click command callback is executed, it’s passed all the non-hidden parameters as keyword arguments. Notably absent is the context. However, a callback can opt into being passed to the context object by marking itself with pass_context().
So how do you invoke a command callback if you don’t know if it should receive the context or not? The answer is that the context itself provides a helper function (Context.invoke()) which can do this for you. It accepts the callback as first argument and then invokes the function correctly.
In this example, we want to build a command line tool that resembles a version control system. Systems like Git usually provide one over-arching command that already accepts some parameters and configuration, and then have extra subcommands that do other things.
At the top level, we need a group that can hold all our commands. In this case, we use the basic click.group() which allows us to register other Click commands below it.
For this command, we also want to accept some parameters that configure the state of our tool:
import os
import click
class Repo(object):
def __init__(self, home=None, debug=False):
self.home = os.path.abspath(home or '.')
self.debug = debug
@click.group()
@click.option('--repo-home', envvar='REPO_HOME', default='.repo')
@click.option('--debug/--no-debug', default=False,
envvar='REPO_DEBUG')
@click.pass_context
def cli(ctx, repo_home, debug):
ctx.obj = Repo(repo_home, debug)
Let’s understand what this does. We create a group command which can have subcommands. When it is invoked, it will create an instance of a Repo class. This holds the state for our command line tool. In this case, it just remembers some parameters, but at this point it could also start loading configuration files and so on.
This state object is then remembered by the context as obj. This is a special attribute where commands are supposed to remember what they need to pass on to their children.
In order for this to work, we need to mark our function with pass_context(), because otherwise, the context object would be entirely hidden from us.
Let’s add our first child command to it, the clone command:
@cli.command()
@click.argument('src')
@click.argument('dest', required=False)
def clone(src, dest):
pass
So now we have a clone command, but how do we get access to the repo? As you can imagine, one way is to use the pass_context() function which again will make our callback also get the context passed on which we memorized the repo. However, there is a second version of this decorator called pass_obj() which will just pass the stored object, (in our case the repo):
@cli.command()
@click.argument('src')
@click.argument('dest', required=False)
@click.pass_obj
def clone(repo, src, dest):
pass
While not relevant for the particular program we want to build, there is also quite good support for interleaving systems. Imagine for instance that there was a super cool plugin for our version control system that needed a lot of configuration and wanted to store its own configuration as obj. If we would then attach another command below that, we would all of a sudden get the plugin configuration instead of our repo object.
One obvious way to remedy this is to store a reference to the repo in the plugin, but then a command needs to be aware that it’s attached below such a plugin.
There is a much better system that can built by taking advantage of the linked nature of contexts. We know that the plugin context is linked to the context that created our repo. Because of that, we can start a search for the last level where the object stored by the context was a repo.
Built-in support for this is provided by the make_pass_decorator() factory, which will create decorators for us that find objects (it internally calls into Context.find_object()). In our case, we know that we want to find the closest Repo object, so let’s make a decorator for this:
pass_repo = click.make_pass_decorator(Repo)
If we now use pass_repo instead of pass_obj, we will always get a repo instead of something else:
@cli.command()
@click.argument('src')
@click.argument('dest', required=False)
@pass_repo
def clone(repo, src, dest):
pass
The above example only works if there was an outer command that created a Repo object and stored it in the context. For some more advanced use cases, this might become a problem. The default behavior of make_pass_decorator() is to call Context.find_object() which will find the object. If it can’t find the object, it will raise an error. The alternative behavior is to use Context.ensure_object() which will find the object, and if it cannot find it, will create one and store it in the innermost context. This behavior can also be enabled for make_pass_decorator() by passing ensure=True:
pass_repo = click.make_pass_decorator(Repo, ensure=True)
In this case, the innermost context gets an object created if it is missing. This might replace objects being placed there earlier. In this case, the command stays executable, even if the outer command does not run. For this to work, the object type needs to have a constructor that accepts no arguments.
As such it runs standalone:
@click.command()
@pass_repo
def cp(repo):
click.echo(repo)
As you can see:
$ cp
<Repo object at 0x7fe7c5908ad0>
In addition to common functionality that is implemented in the library itself, there are countless patterns that can be implemented by extending Click. This page should give some insight into what can be accomplished.
Many tools support aliases for commands. For instance, you can configure git to accept git ci as alias for git commit. Other tools also support auto-discovery for aliases by automatically shortening them.
Click does not support this out of the box, but it’s very easy to customize the Group or any other MultiCommand to provide this functionality.
As explained in Custom Multi Commands, a multi command can provide two methods: list_commands() and get_command(). In this particular case, you only need to override the latter as you generally don’t want to enumerate the aliases on the help page in order to avoid confusion.
This following example implements a subclass of Group that accepts a prefix for a command. If there were a command called push, it would accept pus as an alias (so long as it was unique):
class AliasedGroup(click.Group):
def get_command(self, ctx, cmd_name):
rv = click.Group.get_command(self, ctx, cmd_name)
if rv is not None:
return rv
matches = [x for x in self.list_commands(ctx)
if x.startswith(cmd_name)]
if not matches:
return None
elif len(matches) == 1:
return click.Group.get_command(self, ctx, matches[0])
ctx.fail('Too many matches: %s' % ', '.join(sorted(matches)))
And it can then be used like this:
@click.command(cls=AliasedGroup)
def cli():
pass
@cli.command()
def push():
pass
@cli.command()
def pop():
pass
Parameters (options and arguments) are forwarded to the command callbacks as you have seen. One common way to prevent a parameter from being passed to the callback is the expose_value argument to a parameter which hides the parameter entirely. The way this works is that the Context object has a params attribute which is a dictionary of all parameters. Whatever is in that dictionary is being passed to the callbacks.
This can be used to make up addition parameters. Generally this pattern is not recommended but in some cases it can be useful. At the very least it’s good to know that the system works this way.
import urllib
def open_url(ctx, param, value):
if value is not None:
ctx.params['fp'] = urllib.urlopen(value)
return value
@click.command()
@click.option('--url', callback=open_url)
def cli(url, fp=None):
if fp is not None:
click.echo('%s: %s' % (url, fp.code))
In this case the callback returns the URL unchanged but also passes a second fp value to the callback. What’s more recommended is to pass the information in a wrapper however:
import urllib
class URL(object):
def __init__(self, url, fp):
self.url = url
self.fp = fp
def open_url(ctx, param, value):
if value is not None:
return URL(value, urllib.urlopen(value))
@click.command()
@click.option('--url', callback=open_url)
def cli(url):
if url is not None:
click.echo('%s: %s' % (url.url, url.fp.code))
New in version 2.0.
Starting with Click 2.0, it’s possible to provide a function that is used for normalizing tokens. Tokens are option names, choice values, or command values. This can be used to implement case insensitive options, for instance.
In order to use this feature, the context needs to be passed a function that performs the normalization of the token. For instance, you could have a function that converts the token to lowercase:
CONTEXT_SETTINGS = dict(token_normalize_func=lambda x: x.lower())
@click.command(context_settings=CONTEXT_SETTINGS)
@click.option('--name', default='Pete')
def cli(name):
click.echo('Name: %s' % name)
And how it works on the command line:
$ cli --NAME=Pete
Name: Pete
Sometimes, it might be interesting to invoke one command from another command. This is a pattern that is generally discouraged with Click, but possible nonetheless. For this, you can use the Context.invoke() or Context.forward() methods.
They work similarly, but the difference is that Context.invoke() merely invokes another command with the arguments you provide as a caller, whereas Context.forward() fills in the arguments from the current command. Both accept the command as the first argument and everything else is passed onwards as you would expect.
Example:
cli = click.Group()
@cli.command()
@click.option('--count', default=1)
def test(count):
click.echo('Count: %d' % count)
@cli.command()
@click.option('--count', default=1)
@click.pass_context
def dist(ctx, count):
ctx.forward(test)
ctx.invoke(test, count=42)
And what it looks like:
$ cli dist
Count: 1
Count: 42
Click works a bit differently than some other command line parsers in that it attempts to reconcile the order of arguments as defined by the programmer with the order of arguments as defined by the user before invoking any callbacks.
This is an important concept to understand when porting complex patterns to Click from optparse or other systems. A parameter callback invocation in optparse happens as part of the parsing step, whereas a callback invocation in Click happens after the parsing.
The main difference is that in optparse, callbacks are invoked with the raw value as it happens, whereas a callback in Click is invoked after the value has been fully converted.
Generally, the order of invocation is driven by the order in which the user provides the arguments to the script; if there is an option called --foo and an option called --bar and the user calls it as --bar --foo, then the callback for bar will fire before the one for foo.
There are three exceptions to this rule which are important to know:
An option can be set to be “eager”. All eager parameters are evaluated before all non-eager parameters, but again in the order as they were provided on the command line by the user.
This is important for parameters that execute and exit like --help and --version. Both are eager parameters, but whatever parameter comes first on the command line will win and exit the program.
If an option or argument is split up on the command line into multiple places because it is repeated – for instance, --exclude foo --include baz --exclude bar – the callback will fire based on the position of the first option. In this case, the callback will fire for exclude and it will be passed both options (foo and bar), then the callback for include will fire with baz only.
Note that even if a parameter does not allow multiple versions, Click will still accept the position of the first, but it will ignore every value except the last. The reason for this is to allow composability through shell aliases that set defaults.
Most of the time you do not need to be concerned about any of this, but it is important to know how it works for some advanced cases.
In some situations it is interesting to be able to accept all unknown options for further manual processing. Click can generally do that as of Click 4.0, but it has some limitations that lie in the nature of the problem. The support for this is provided through a parser flag called ignore_unknown_options which will instruct the parser to collect all unknown options and to put them to the leftover argument instead of triggering a parsing error.
This can generally be activated in two different ways:
For most situations the easiest solution is the second. Once the behavior is changed something needs to pick up those leftover options (which at this point are considered arguments). For this again you have two options:
In the end you end up with something like this:
import sys
from subprocess import call
@click.command(context_settings=dict(
ignore_unknown_options=True,
))
@click.option('-v', '--verbose', is_flag=True, help='Enables verbose mode')
@click.argument('timeit_args', nargs=-1, type=click.UNPROCESSED)
def cli(verbose, timeit_args):
"""A wrapper around Python's timeit."""
cmdline = ['python', '-mtimeit'] + list(timeit_args)
if verbose:
click.echo('Invoking: %s' % ' '.join(cmdline))
call(cmdline)
And what it looks like:
$ cli --help
Usage: cli [OPTIONS] [TIMEIT_ARGS]...
A wrapper around Python's timeit.
Options:
-v, --verbose Enables verbose mode
--help Show this message and exit.
$ cli -n 100 "a = 1; b = 2; a * b"
100 loops, best of 3: 0.0787 usec per loop
$ cli -v "a = 1; b = 2; a * b"
Invoking: python -mtimeit a = 1; b = 2; a * b
10000000 loops, best of 3: 0.0669 usec per loop
As you can see the verbosity flag is handled by Click, everything else ends up in the timeit_args variable for further processing which then for instance, allows invoking a subprocess. There are a few things that are important to know about how this ignoring of unhandled flag happens:
Generally though the combinated handling of options and arguments from your own commands and commands from another application are discouraged and if you can avoid it, you should. It’s a much better idea to have everything below a subcommand be forwarded to another application than to handle some arguments yourself.
For basic testing, Click provides the click.testing module which provides test functionality that helps you invoke command line applications and check their behavior.
These tools should really only be used for testing as they change the entire interpreter state for simplicity and are not in any way thread-safe!
The basic functionality for testing Click applications is the CliRunner which can invoke commands as command line scripts. The CliRunner.invoke() method runs the command line script in isolation and captures the output as both bytes and binary data.
The return value is a Result object, which has the captured output data, exit code, and optional exception attached.
Example:
import click
from click.testing import CliRunner
def test_hello_world():
@click.command()
@click.argument('name')
def hello(name):
click.echo('Hello %s!' % name)
runner = CliRunner()
result = runner.invoke(hello, ['Peter'])
assert result.exit_code == 0
assert result.output == 'Hello Peter!\n'
For basic command line tools that want to operate with the file system, the CliRunner.isolated_filesystem() method comes in useful which sets up an empty folder and changes the current working directory to.
Example:
import click
from click.testing import CliRunner
def test_cat():
@click.command()
@click.argument('f', type=click.File())
def cat(f):
click.echo(f.read())
runner = CliRunner()
with runner.isolated_filesystem():
with open('hello.txt') as f:
f.write('Hello World!')
result = runner.invoke(cat, ['hello.txt'])
assert result.exit_code == 0
assert result.output == 'Hello World!\n'
The test wrapper can also be used to provide input data for the input stream (stdin). This is very useful for testing prompts, for instance:
import click
from click.testing import CliRunner
def test_prompts():
@click.command()
@click.option('--foo', prompt=True)
def test(foo):
click.echo('foo=%s' % foo)
runner = CliRunner()
result = runner.invoke(test, input='wau wau\n')
assert not result.exception
assert result.output == 'Foo: wau wau\nfoo=wau wau\n'
Note that prompts will be emulated so that they write the input data to the output stream as well. If hidden input is expected then this obviously does not happen.
Besides the functionality that Click provides to interface with argument parsing and handling, it also provides a bunch of addon functionality that is useful for writing command line utilities.
The most obvious helper is the echo() function, which in many ways works like the Python print statement or function. The main difference is that it works the same in Python 2 and 3, it intelligently detects misconfigured output streams, and it will never fail (except in Python 3; for more information see Python 3 Limitations).
Example:
import click
click.echo('Hello World!')
Most importantly, it can print both Unicode and binary data, unlike the built-in print function in Python 3, which cannot output any bytes. It will, however, emit a trailing newline by default, which needs to be suppressed by passing nl=False:
click.echo(b'\xe2\x98\x83', nl=False)
New in version 3.0.
Starting with Click 3.0 you can also easily print to standard error by passing err=True:
click.echo('Hello World!', err=True)
New in version 2.0.
Starting with Click 2.0, the echo() function gained extra functionality to deal with ANSI colors and styles. Note that on Windows, this functionality is only available if colorama is installed. If it is installed, then ANSI codes are intelligently handled.
Primarily this means that:
Note for colorama support: Click will automatically detect when colorama is available and use it. Do not call colorama.init()!
To install colorama, run this command:
$ pip install colorama
For styling a string, the style() function can be used:
import click
click.echo(click.style('Hello World!', fg='green'))
click.echo(click.style('Some more text', bg='blue', fg='white'))
click.echo(click.style('ATTENTION', blink=True, bold=True))
The combination of echo() and style() is also available in a single function called secho():
click.secho('Hello World!', fg='green')
click.secho('Some more text', bg='blue', fg='white')
click.secho('ATTENTION', blink=True, bold=True)
In some situations, you might want to show long texts on the terminal and let a user scroll through it. This can be achieved by using the echo_via_pager() function which works similarly to the echo() function, but always writes to stdout and, if possible, through a pager.
Example:
@click.command()
def less():
click.echo_via_pager('\n'.join('Line %d' % idx
for idx in range(200)))
New in version 2.0.
To clear the terminal screen, you can use the clear() function that is provided starting with Click 2.0. It does what the name suggests: it clears the entire visible screen in a platform-agnostic way:
import click
click.clear()
New in version 2.0.
Normally, when reading input from the terminal, you would read from standard input. However, this is buffered input and will not show up until the line has been terminated. In certain circumstances, you might not want to do that and instead read individual characters as they are being written.
For this, Click provides the getchar() function which reads a single character from the terminal buffer and returns it as a Unicode character.
Note that this function will always read from the terminal, even if stdin is instead a pipe.
Example:
import click
click.echo('Continue? [yn] ', nl=False)
c = click.getchar()
click.echo()
if c == 'y':
click.echo('We will go on')
elif c == 'n':
click.echo('Abort!')
else:
click.echo('Invalid input :(')
Note that this reads raw input, which means that things like arrow keys will show up in the platform’s native escape format. The only characters translated are ^C and ^D which are converted into keyboard interrupts and end of file exceptions respectively. This is done because otherwise, it’s too easy to forget about that and to create scripts that cannot be properly exited.
New in version 2.0.
Sometimes, it’s useful to pause until the user presses any key on the keyboard. This is especially useful on Windows where cmd.exe will close the window at the end of the command execution by default, instead of waiting.
In click, this can be accomplished with the pause() function. This function will print a quick message to the terminal (which can be customized) and wait for the user to press a key. In addition to that, it will also become a NOP (no operation instruction) if the script is not run interactively.
Example:
import click
click.pause()
New in version 2.0.
Click supports launching editors automatically through edit(). This is very useful for asking users for multi-line input. It will automatically open the user’s defined editor or fall back to a sensible default. If the user closes the editor without saving, the return value will be None otherwise the entered text.
Example usage:
import click
def get_commit_message():
MARKER = '# Everything below is ignored\n'
message = click.edit('\n\n' + MARKER)
if message is not None:
return message.split(MARKER, 1)[0].rstrip('\n')
Alternatively, the function can also be used to launch editors for files by a specific filename. In this case, the return value is always None.
Example usage:
import click
click.edit(filename='/etc/passwd')
New in version 2.0.
Click supports launching applications through launch(). This can be used to open the default application assocated with a URL or filetype. This can be used to launch web browsers or picture viewers, for instance. In addition to this, it can also launch the file manager and automatically select the provided file.
Example usage:
click.launch('http://click.pocoo.org/')
click.launch('/my/downloaded/file.txt', locate=True)
Because filenames might not be Unicode, formatting them can be a bit tricky. Generally, this is easier in Python 2 than on 3, as you can just write the bytes to stdout with the print function, but in Python 3, you will always need to operate in Unicode.
The way this works with click is through the format_filename() function. It does a best-effort conversion of the filename to Unicode and will never fail. This makes it possible to use these filenames in the context of a full Unicode string.
Example:
click.echo('Path: %s' % click.format_filename(b'foo.txt'))
For command line utilities, it’s very important to get access to input and output streams reliably. Python generally provides access to these streams through sys.stdout and friends, but unfortunately, there are API differences between 2.x and 3.x, especially with regards to how these streams respond to Unicode and binary data.
Because of this, click provides the get_binary_stream() and get_text_stream() functions, which produce consistent results with different Python versions and for a wide variety pf terminal configurations.
The end result is that these functions will always return a functional stream object (except in very odd cases in Python 3; see Python 3 Limitations).
Example:
import click
stdin_text = click.get_text_stream('stdin')
stdout_binary = click.get_binary_stream('stdout')
New in version 3.0.
Starting with Click 3.0 the logic for opening files from the File type is exposed through the open_file() function. It can intelligently open stdin/stdout as well as any other file.
Example:
import click
stdout = click.open_file('-', 'w')
test_file = click.open_file('test.txt', 'w')
If stdin or stdout are returned, the return value is wrapped in a special file where the context manager will prevent the closing of the file. This makes the handling of standard streams transparent and you can always use it like this:
with click.open_file(filename, 'w') as f:
f.write('Hello World!\n')
New in version 2.0.
Very often, you want to open a configuration file that belongs to your application. However, different operating systems store these configuration files in different locations depending on their standards. Click provides a get_app_dir() function which returns the most appropriate location for per-user config files for your application depending on the OS.
Example usage:
import os
import click
import ConfigParser
APP_NAME = 'My Application'
def read_config():
cfg = os.path.join(click.get_app_dir(APP_NAME), 'config.ini')
parser = ConfigParser.RawConfigParser()
parser.read([cfg])
rv = {}
for section in parser.sections():
for key, value in parser.items(section):
rv['%s.%s' % (section, key)] = value
return rv
New in version 2.0.
Sometimes, you have command line scripts that need to process a lot of data, but you want to quickly show the user some progress about how long that will take. Click supports simple progress bar rendering for that through the progressbar() function.
The basic usage is very simple: the idea is that you have an iterable that you want to operate on. For each item in the iterable it might take some time to do processing. So say you have a loop like this:
for user in all_the_users_to_process:
modify_the_user(user)
To hook this up with an automatically updating progress bar, all you need to do is to change the code to this:
import click
with click.progressbar(all_the_users_to_process) as bar:
for user in bar:
modify_the_user(user)
Click will then automatically print a progress bar to the terminal and calculate the remaining time for you. The calculation of remaining time requires that the iterable has a length. If it does not have a length but you know the length, you can explicitly provide it:
with click.progressbar(all_the_users_to_process,
length=number_of_users) as bar:
for user in bar:
modify_the_user(user)
Another useful feature is to associate a label with the progress bar which will be shown preceding the progress bar:
with click.progressbar(all_the_users_to_process,
label='Modifying user accounts',
length=number_of_users) as bar:
for user in bar:
modify_the_user(user)
New in version 2.0.
As of Click 2.0, there is built-in support for Bash completion for any Click script. There are certain restrictions on when this completion is available, but for the most part it should just work.
Bash completion is only available if a script has been installed properly, and not executed through the python command. For information about how to do that, see Setuptools Integration. Also, Click currently only supports completion for Bash.
Currently, Bash completion is an internal feature that is not customizable. This might be relaxed in future versions.
Generally, the Bash completion support will complete subcommands and parameters. Subcommands are always listed whereas parameters only if at least a dash has been provided. Example:
$ repo <TAB><TAB>
clone commit copy delete setuser
$ repo clone -<TAB><TAB>
--deep --help --rev --shallow -r
In order to activate Bash completion, you need to inform Bash that completion is available for your script, and how. Any Click application automatically provides support for that. The general way this works is through a magic environment variable called _<PROG_NAME>_COMPLETE, where <PROG_NAME> is your application executable name in uppercase with dashes replaced by underscores.
If your tool is called foo-bar, then the magic variable is called _FOO_BAR_COMPLETE. By exporting it with the source value it will spit out the activation script which can be trivally activated.
For instance, to enable Bash completion for your foo-bar script, this is what you would need to put into your .bashrc:
eval "$(_FOO_BAR_COMPLETE=source foo-bar)"
From this point onwards, your script will have Bash completion enabled.
The above activation example will always invoke your application on startup. This might be slowing down the shell activation time significantly if you have many applications. Alternatively, you could also ship a file with the contents of that, which is what Git and other systems are doing.
This can be easily accomplished:
_FOO_BAR_COMPLETE=source foo-bar > foo-bar-complete.sh
And then you would put this into your bashrc instead:
. /path/to/foo-bar-complete.sh
Click internally uses exceptions to signal various error conditions that the user of the application might have caused. Primarily this is things like incorrect usage.
Click’s main error handling is happening in BaseCommand.main(). In there it handles all subclasses of ClickException as well as the standard EOFError and KeyboardInterrupt exceptions. The latter are internally translated into a Abort.
The logic applied is the following:
Generally you always have the option to invoke the invoke() method yourself. For instance if you have a Command you can invoke it manually like this:
ctx = command.make_context('command-name', ['args', 'go', 'here'])
with ctx:
result = command.invoke(ctx)
In this case exceptions will not be handled at all and bubbled up as you would expect.
Starting with Click 3.0 you can also use the Command.main() method but disable the standalone mode which will do two things: disable exception handling and disable the implicit sys.exit() at the end.
So you can do something like this:
command.main(['command-name', 'args', 'go', 'here'],
standalone_mode=False)
Click has two exception bases: ClickException which is raised for all exceptions that Click wants to signal to the user and Abort which is used to instruct Click to abort the execution.
A ClickException has a show() method which can render an error message to stderr or the given file object. If you want to use the exception yourself for doing something check the API docs about what else they provide.
The following common subclasses exist:
Click supports Python 3, but like all other command line utility libraries, it suffers from the Unicode text model in Python 3. All examples in the documentation were written so that they could run on both Python 2.x and Python 3.3 or higher.
At the moment, it is strongly recommended is to use Python 2 for Click utilities unless Python 3 is a hard requirement.
At the moment, Click suffers from a few problems with Python 3:
The command line in Unix traditionally is in bytes, and not Unicode. While there are encoding hints for all of this, there are generally some situations where this can break. The most common one is SSH connections to machines with different locales.
Misconfigured environments can currently cause a wide range of Unicode problems in Python 3 due to the lack of support for roundtripping surrogate escapes. This will not be fixed in Click itself!
For more information see Python 3 Surrogate Handling.
Standard input and output in Python 3 is opened in Unicode mode by default. Click has to reopen the stream in binary mode in certain situations. Because there is no standardized way to do this, this might not always work. Primarily this can become a problem when testing command-line applications.
This is not supported:
sys.stdin = io.StringIO('Input here')
sys.stdout = io.StringIO()
Instead you need to do this:
input = 'Input here'
in_stream = io.BytesIO(input.encode('utf-8'))
sys.stdin = io.TextIOWrapper(in_stream, encoding='utf-8')
out_stream = io.BytesIO()
sys.stdout = io.TextIOWrapper(out_stream, encoding='utf-8')
Remember that in that case, you need to use out_stream.getvalue() and not sys.stdout.getvalue() if you want to access the buffer contents as the wrapper will not forward that method.
Click attempts to minimize the differences between Python 2 and Python 3 by following the best practices for both languages.
In Python 2, the following is true:
In Python 3, the following is true:
sys.stdin, sys.stdout and sys.stderr are by default text-based. When Click needs a binary stream, it attempts to discover the underlying binary stream. See Python 3 Limitations for how this works.
sys.argv is always Unicode-based. This also means that the native type for input values to the types in Click is Unicode, and not bytes.
This causes problems when the terminal is incorrectly set and Python does not figure out the encoding. In that case, the Unicode string will contain error bytes encoded as surrogate escapes.
When dealing with files, Click will always use the Unicode file system API calls by using the operating system’s reported or guessed filesystem encoding. Surrogates are supported for filenames, so it should be possible to open files through the File type even if the environment is misconfigured.
Click in Python 3 does all the Unicode handling in the standard library and is subject to its behavior. In Python 2, Click does all the Unicode handling itself, which means there are differences in error behavior.
The most glaring difference is that in Python 2, Unicode will “just work”, while in Python 3, it requires extra care. The reason for this is that on Python 3, the encoding detection is done in the interpreter and on Linux and certain other operating systems its encoding handling is problematic.
The biggest source of frustration is that Click scripts invoked by init systems (sysvinit, upstart, systemd, etc.), deployment tools (salt, puppet), or cron jobs (cron) will refuse to work unless a Unicode locale is exported.
If Click encounters such an environment it will prevent further execution to force you to set a locale. This is done because Click cannot know about the state of the system once it’s invoked and restore the values before Python’s Unicode handling kicked in.
If you see something like this error in Python 3:
Traceback (most recent call last):
...
RuntimeError: Click will abort further execution because Python 3 was
configured to use ASCII as encoding for the environment. Either switch
to Python 2 or consult for http://click.pocoo.org/python3/
mitigation steps.
You are dealing with an environment where Python 3 thinks you are restricted to ASCII data. The solution to these problems is different depending on which locale your computer is running in.
For instance, if you have a German Linux machine, you can fix the problem by exporting the locale to de_DE.utf-8:
export LC_ALL=de_DE.utf-8
export LANG=de_DE.utf-8
If you are on a US machine, en_EN.utf-8 is the encoding of choice. On some newer Linux systems, you could also try C.UTF-8 as the locale:
export LC_ALL=C.UTF-8
export LANG=C.UTF-8
You need to do this before you invoke your Python script. If you are curious about the reasons for this, you can join the discussions in the Python 3 bug tracker:
If you are looking for information on a specific function, class, or method, this part of the documentation is for you.
This part of the documentation lists the full API reference of all public classes and functions.
Creates a new Command and uses the decorated function as callback. This will also automatically attach all decorated option()s and argument()s as parameters to the command.
The name of the command defaults to the name of the function. If you want to change that, you can pass the intended name as the first argument.
All keyword arguments are forwarded to the underlying command class.
Once decorated the function turns into a Command instance that can be invoked as a command line utility or be attached to a command Group.
| Parameters: |
|
|---|
Creates a new Group with a function as callback. This works otherwise the same as command() just that the cls parameter is set to Group.
Attaches an option to the command. All positional arguments are passed as parameter declarations to Argument; all keyword arguments are forwarded unchanged. This is equivalent to creating an Option instance manually and attaching it to the Command.params list.
Attaches an option to the command. All positional arguments are passed as parameter declarations to Option; all keyword arguments are forwarded unchanged. This is equivalent to creating an Option instance manually and attaching it to the Command.params list.
Shortcut for password prompts.
This is equivalent to decorating a function with option() with the following parameters:
@click.command()
@click.option('--password', prompt=True, confirmation_prompt=True,
hide_input=True)
def changeadmin(password):
pass
Shortcut for confirmation prompts that can be ignored by passing --yes as parameter.
This is equivalent to decorating a function with option() with the following parameters:
def callback(ctx, param, value):
if not value:
ctx.abort()
@click.command()
@click.option('--yes', is_flag=True, callback=callback,
expose_value=False, prompt='Do you want to continue?')
def dropdb():
pass
Adds a --version option which immediately ends the program printing out the version number. This is implemented as an eager option that prints the version and exits the program in the callback.
| Parameters: |
|
|---|
Adds a --help option which immediately ends the program printing out the help page. This is usually unnecessary to add as this is added by default to all commands unless suppressed.
Like version_option(), this is implemented as eager option that prints in the callback and exits.
All arguments are forwarded to option().
Marks a callback as wanting to receive the current context object as first argument.
Similar to pass_context(), but only pass the object on the context onwards (Context.obj). This is useful if that object represents the state of a nested system.
Given an object type this creates a decorator that will work similar to pass_obj() but instead of passing the object of the current context, it will find the innermost context of type object_type().
This generates a decorator that works roughly like this:
from functools import update_wrapper
def decorator(f):
@pass_context
def new_func(ctx, *args, **kwargs):
obj = ctx.find_object(object_type)
return ctx.invoke(f, obj, *args, **kwargs)
return update_wrapper(new_func, f)
return decorator
| Parameters: |
|
|---|
Prints a message plus a newline to the given file or stdout. On first sight, this looks like the print function, but it has improved support for handling Unicode and binary data that does not fail no matter how badly configured the system is.
Primarily it means that you can print binary data as well as Unicode data on both 2.x and 3.x to the given file in the most appropriate way possible. This is a very carefree function as in that it will try its best to not fail.
In addition to that, if colorama is installed, the echo function will also support clever handling of ANSI codes. Essentially it will then do the following:
Changed in version 2.0: Starting with version 2.0 of Click, the echo function will work with colorama if it’s installed.
New in version 3.0: The err parameter was added.
Changed in version 4.0: Added the color flag.
| Parameters: |
|
|---|
This function takes a text and shows it via an environment specific pager on stdout.
Changed in version 3.0: Added the color flag.
| Parameters: |
|
|---|
Prompts a user for input. This is a convenience function that can be used to prompt a user for input later.
If the user aborts the input by sending a interrupt signal, this function will catch it and raise a Abort exception.
New in version 4.0: Added the err parameter.
| Parameters: |
|
|---|
Prompts for confirmation (yes/no question).
If the user aborts the input by sending a interrupt signal this function will catch it and raise a Abort exception.
New in version 4.0: Added the err parameter.
| Parameters: |
|
|---|
This function creates an iterable context manager that can be used to iterate over something while showing a progress bar. It will either iterate over the iterable or length items (that are counted up). While iteration happens, this function will print a rendered progress bar to the given file (defaults to stdout) and will attempt to calculate remaining time and more. By default, this progress bar will not be rendered if the file is not a terminal.
The context manager creates the progress bar. When the context manager is entered the progress bar is already displayed. With every iteration over the progress bar, the iterable passed to the bar is advanced and the bar is updated. When the context manager exits, a newline is printed and the progress bar is finalized on screen.
No printing must happen or the progress bar will be unintentionally destroyed.
Example usage:
with progressbar(items) as bar:
for item in bar:
do_something_with(item)
New in version 2.0.
New in version 4.0: Added the color parameter.
| Parameters: |
|
|---|
Clears the terminal screen. This will have the effect of clearing the whole visible space of the terminal and moving the cursor to the top left. This does not do anything if not connected to a terminal.
New in version 2.0.
Styles a text with ANSI styles and returns the new string. By default the styling is self contained which means that at the end of the string a reset code is issued. This can be prevented by passing reset=False.
Examples:
click.echo(click.style('Hello World!', fg='green'))
click.echo(click.style('ATTENTION!', blink=True))
click.echo(click.style('Some things', reverse=True, fg='cyan'))
Supported color names:
New in version 2.0.
| Parameters: |
|
|---|
Removes ANSI styling information from a string. Usually it’s not necessary to use this function as Click’s echo function will automatically remove styling if necessary.
New in version 2.0.
| Parameters: | text – the text to remove style information from. |
|---|
This function combines echo() and style() into one call. As such the following two calls are the same:
click.secho('Hello World!', fg='green')
click.echo(click.style('Hello World!', fg='green'))
All keyword arguments are forwarded to the underlying functions depending on which one they go with.
New in version 2.0.
Edits the given text in the defined editor. If an editor is given (should be the full path to the executable but the regular operating system search path is used for finding the executable) it overrides the detected editor. Optionally, some environment variables can be used. If the editor is closed without changes, None is returned. In case a file is edited directly the return value is always None and require_save and extension are ignored.
If the editor cannot be opened a UsageError is raised.
Note for Windows: to simplify cross-platform usage, the newlines are automatically converted from POSIX to Windows and vice versa. As such, the message here will have \n as newline markers.
| Parameters: |
|
|---|
This function launches the given URL (or filename) in the default viewer application for this file type. If this is an executable, it might launch the executable in a new session. The return value is the exit code of the launched application. Usually, 0 indicates success.
Examples:
click.launch('http://click.pocoo.org/')
click.launch('/my/downloaded/file', locate=True)
New in version 2.0.
| Parameters: |
|
|---|
Fetches a single character from the terminal and returns it. This will always return a unicode character and under certain rare circumstances this might return more than one character. The situations which more than one character is returned is when for whatever reason multiple characters end up in the terminal buffer or standard input was not actually a terminal.
Note that this will always read from the terminal, even if something is piped into the standard input.
New in version 2.0.
| Parameters: | echo – if set to True, the character read will also show up on the terminal. The default is to not show it. |
|---|
This command stops execution and waits for the user to press any key to continue. This is similar to the Windows batch “pause” command. If the program is not run through a terminal, this command will instead do nothing.
New in version 2.0.
New in version 4.0: Added the err parameter.
| Parameters: |
|
|---|
Returns the current size of the terminal as tuple in the form (width, height) in columns and rows.
Returns a system stream for byte processing. This essentially returns the stream from the sys module with the given name but it solves some compatibility issues between different Python versions. Primarily this function is necessary for getting binary streams on Python 3.
| Parameters: | name – the name of the stream to open. Valid names are 'stdin', 'stdout' and 'stderr' |
|---|
Returns a system stream for text processing. This usually returns a wrapped stream around a binary stream returned from get_binary_stream() but it also can take shortcuts on Python 3 for already correctly configured streams.
| Parameters: |
|
|---|
This is similar to how the File works but for manual usage. Files are opened non lazy by default. This can open regular files as well as stdin/stdout if '-' is passed.
If stdin/stdout is returned the stream is wrapped so that the context manager will not close the stream accidentally. This makes it possible to always use the function like this without having to worry to accidentally close a standard stream:
with open_file(filename) as f:
...
New in version 3.0.
| Parameters: |
|
|---|
Returns the config folder for the application. The default behavior is to return whatever is most appropriate for the operating system.
To give you an idea, for an app called "Foo Bar", something like the following folders could be returned:
New in version 2.0.
| Parameters: |
|
|---|
Formats a filename for user display. The main purpose of this function is to ensure that the filename can be displayed at all. This will decode the filename to unicode if necessary in a way that it will not fail. Optionally, it can shorten the filename to not include the full path to the filename.
| Parameters: |
|
|---|
The base command implements the minimal API contract of commands. Most code will never use this as it does not implement a lot of useful functionality but it can act as the direct subclass of alternative parsing methods that do not depend on the Click parser.
For instance, this can be used to bridge Click and other systems like argparse or docopt.
Because base commands do not implement a lot of the API that other parts of Click take for granted, they are not supported for all operations. For instance, they cannot be used with the decorators usually and they have no built-in callback system.
Changed in version 2.0: Added the context_settings parameter.
| Parameters: |
|
|---|
the default for the Context.allow_extra_args flag.
the default for the Context.allow_interspersed_args flag.
an optional dictionary with defaults passed to the context.
the default for the Context.ignore_unknown_options flag.
Given a context, this invokes the command. The default implementation is raising a not implemented error.
This is the way to invoke a script with all the bells and whistles as a command line application. This will always terminate the application after a call. If this is not wanted, SystemExit needs to be caught.
This method is also available by directly calling the instance of a Command.
New in version 3.0: Added the standalone_mode flag to control the standalone mode.
| Parameters: |
|
|---|
This function when given an info name and arguments will kick off the parsing and create a new Context. It does not invoke the actual command callback though.
| Parameters: |
|
|---|
the name the command thinks it has. Upon registering a command on a Group the group will default the command name with this information. You should instead use the Context‘s info_name attribute.
Given a context and a list of arguments this creates the parser and parses the arguments, then modifies the context as necessary. This is automatically invoked by make_context().
Commands are the basic building block of command line interfaces in Click. A basic command handles command line parsing and might dispatch more parsing to commands nested below it.
Changed in version 2.0: Added the context_settings parameter.
| Parameters: |
|
|---|
the callback to execute when the command fires. This might be None in which case nothing happens.
Returns all the pieces that go into the usage line and returns it as a list of strings.
Writes the epilog into the formatter if it exists.
Writes the help into the formatter if it exists.
This calls into the following methods:
Writes the help text to the formatter if it exists.
Writes all the options into the formatter if they exist.
Writes the usage line into the formatter.
Formats the help into a string and returns it. This creates a formatter and will call into the following formatting methods:
Returns the help option object.
Returns the names for the help option.
Given a context, this invokes the attached callback (if it exists) in the right way.
Creates the underlying option parser for this command.
the list of parameters for this command in the order they should show up in the help page and execute. Eager parameters will automatically be handled before non eager ones.
A multi command is the basic implementation of a command that dispatches to subcommands. The most common version is the Command.
| Parameters: |
|
|---|
Extra format methods for multi methods that adds all the commands after the options.
Given a context and a command name, this returns a Command object if it exists or returns None.
Returns a list of subcommand names in the order they should appear.
The result callback that is stored. This can be set or overridden with the resultcallback() decorator.
Adds a result callback to the chain command. By default if a result callback is already registered this will chain them but this can be disabled with the replace parameter. The result callback is invoked with the return value of the subcommand (or the list of return values from all subcommands if chaining is enabled) as well as the parameters as they would be passed to the main callback.
Example:
@click.group()
@click.option('-i', '--input', default=23)
def cli(input):
return 42
@cli.resultcallback()
def process_result(result, input):
return result + input
New in version 3.0.
| Parameters: | replace – if set to True an already existing result callback will be removed. |
|---|
A group allows a command to have subcommands attached. This is the most common way to implement nesting in Click.
| Parameters: | commands – a dictionary of commands. |
|---|
Registers another Command with this group. If the name is not provided, the name of the command is used.
A shortcut decorator for declaring and attaching a command to the group. This takes the same arguments as command() but immediately registers the created command with this instance by calling into add_command().
the registered subcommands by their exported names.
A shortcut decorator for declaring and attaching a group to the group. This takes the same arguments as group() but immediately registers the created command with this instance by calling into add_command().
A command collection is a multi command that merges multiple multi commands together into one. This is a straightforward implementation that accepts a list of different multi commands as sources and provides all the commands for each of them.
Adds a new multi command to the chain dispatcher.
The list of registered multi commands.
A parameter to a command comes in two versions: they are either Options or Arguments. Other subclasses are currently not supported by design as some of the internals for parsing are intentionally not finalized.
Some settings are supported by both options and arguments.
Changed in version 2.0: Changed signature for parameter callback to also be passed the parameter. In Click 2.0, the old callback format will still work, but it will raise a warning to give you change to migrate the code easier.
| Parameters: |
|
|---|
Given a context variable this calculates the default value.
Given a value and context this runs the logic to convert the value as necessary.
Given a value this runs it properly through the type system. This automatically handles things like nargs and multiple.
Options are usually optional values on the command line and have some extra features that arguments don’t have.
All other parameters are passed onwards to the parameter constructor.
| Parameters: |
|
|---|
Arguments are positional parameters to a command. They generally provide fewer features than options but can have infinite nargs and are required by default.
All parameters are passed onwards to the parameter constructor.
The context is a special internal object that holds state relevant for the script execution at every single level. It’s normally invisible to commands unless they opt-in to getting access to it.
The context is useful as it can pass internal objects around and can control special execution features such as reading data from environment variables.
A context can be used as context manager in which case it will call close() on teardown.
New in version 2.0: Added the resilient_parsing, help_option_names, token_normalize_func parameters.
New in version 3.0: Added the allow_extra_args and allow_interspersed_args parameters.
New in version 4.0: Added the color, ignore_unknown_options, and max_content_width parameters.
| Parameters: |
|
|---|
Aborts the script.
Indicates if the context allows extra args or if it should fail on parsing.
New in version 3.0.
Indicates if the context allows mixing of arguments and options or not.
New in version 3.0.
the leftover arguments.
This decorator remembers a function as callback that should be executed when the context tears down. This is most useful to bind resource handling to the script execution. For instance, file objects opened by the File type will register their close callbacks here.
| Parameters: | f – the function to execute on teardown. |
|---|
Invokes all close callbacks.
Controls if styling output is wanted or not.
The computed command path. This is used for the usage information on the help page. It’s automatically created by combining the info names of the chain of contexts to the root.
Like find_object() but sets the innermost object to a new instance of object_type if it does not exist.
Exits the application with a given exit code.
Aborts the execution of the program with a specific error message.
| Parameters: | message – the error message to fail with. |
|---|
Finds the closest object of a given type.
Finds the outermost context.
Similar to invoke() but fills in default keyword arguments from the current context if the other command expects it. This cannot invoke callbacks directly, only other commands.
Helper method to get formatted help page for the current context and command.
Helper method to get formatted usage string for the current context and command.
The names for the help options.
Instructs click to ignore options that a command does not understand and will store it on the context for later processing. This is primarily useful for situations where you want to call into external programs. Generally this pattern is strongly discouraged because it’s not possibly to losslessly forward all arguments.
New in version 4.0.
the descriptive information name
Invokes a command callback in exactly the way it expects. There are two ways to invoke this method:
Note that before Click 3.2 keyword arguments were not properly filled in against the intention of this code and no context was created. For more information about this change and why it was done in a bugfix release see Upgrading to 3.2.
This flag indicates if a subcommand is going to be executed. A group callback can use this information to figure out if it’s being executed directly or because the execution flow passes onwards to a subcommand. By default it’s None, but it can be the name of the subcommand to execute.
If chaining is enabled this will be set to '*' in case any commands are executed. It is however not possible to figure out which ones. If you require this knowledge you should use a resultcallback().
Looks up the default for a parameter name. This by default looks into the default_map if available.
Creates the formatter for the help and usage output.
The maximum width of formatted content (None implies a sensible default which is 80 for most things).
the user object stored.
the parsed parameters except if the value is hidden in which case it’s not remembered.
the parent context or None if none exists.
Indicates if resilient parsing is enabled. In that case Click will do its best to not cause any failures.
The width of the terminal (None is autodetection).
An optional normalization function for tokens. This is options, choices, commands etc.
A unicode string parameter type which is the implicit default. This can also be selected by using str as type.
An integer parameter. This can also be selected by using int as type.
A floating point value parameter. This can also be selected by using float as type.
A boolean parameter. This is the default for boolean flags. This can also be selected by using bool as a type.
A UUID parameter.
A dummy parameter type that just does nothing. From a user’s perspective this appears to just be the same as STRING but internally no string conversion takes place. This is necessary to achieve the same bytes/unicode behavior on Python 2/3 in situations where you want to not convert argument types. This is usually useful when working with file paths as they can appear in bytes and unicode.
For path related uses the Path type is a better choice but there are situations where an unprocessed type is useful which is why it is is provided.
New in version 4.0.
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).
Files can be opened for reading or writing. The special value - indicates stdin or stdout depending on the mode.
By default, the file is opened for reading text data, but it can also be opened in binary mode or for writing. The encoding parameter can be used to force a specific encoding.
The lazy flag controls if the file should be opened immediately or upon first IO. The default is to be non lazy for standard input and output streams as well as files opened for reading, lazy otherwise.
Starting with Click 2.0, files can also be opened atomically in which case all writes go into a separate file in the same folder and upon completion the file will be moved over to the original location. This is useful if a file regularly read by other users is modified.
See File Arguments for more information.
The path type is similar to the File type but it performs different checks. First of all, instead of returning a open file handle it returns just the filename. Secondly, it can perform various basic checks about what the file or directory should be.
| Parameters: |
|
|---|
The choice type allows a value to checked against a fixed set of supported values. All of these values have to be strings.
See Choice Options for an example.
A parameter that works similar to click.INT but restricts the value to fit into a range. The default behavior is to fail if the value falls outside the range, but it can also be silently clamped between the two edges.
See Range Options for an example.
Helper for converting values through types. The following is necessary for a valid type:
Converts the value. This is not invoked for values that are None (the missing value).
if a list of this type is expected and the value is pulled from a string environment variable, this is what splits it up. None means any whitespace. For all parameters the general rule is that whitespace splits them up. The exception are paths and files which are split by os.path.pathsep by default (”:” on Unix and ”;” on Windows).
Helper method to fail with an invalid value message.
Returns the metavar default for this param if it provides one.
Optionally might return extra information about a missing parameter.
New in version 2.0.
the descriptive name of this type
Given a value from an environment variable this splits it up into small chunks depending on the defined envvar list splitter.
If the splitter is set to None, which means that whitespace splits, then leading and trailing whitespace is ignored. Otherwise, leading and trailing splitters usually lead to empty items being included.
An exception that Click can handle and show to the user.
An internal signalling exception that signals Click to abort.
An internal exception that signals a usage error. This typically aborts any further handling.
| Parameters: |
|
|---|
An exception that formats out a standardized error message for a bad parameter. This is useful when thrown from a callback or type as Click will attach contextual information to it (for instance, which parameter it is).
New in version 2.0.
| Parameters: |
|
|---|
Raised if a file cannot be opened.
Raised if click attempted to handle an option that does not exist.
New in version 4.0.
Raised if an option is generally supplied but the use of the option was incorrect. This is for instance raised if the number of arguments for an option is not correct.
New in version 4.0.
This class helps with formatting text-based help pages. It’s usually just needed for very special internal cases, but it’s also exposed so that developers can write their own fancy outputs.
At present, it always writes into memory.
| Parameters: |
|
|---|
Decreases the indentation.
Returns the buffer contents.
Increases the indentation.
A context manager that increases the indentation.
Helpful context manager that writes a paragraph, a heading, and the indents.
| Parameters: | name – the section name that is written as heading. |
|---|
Writes a unicode string into the internal buffer.
Writes a definition list into the buffer. This is how options and commands are usually formatted.
| Parameters: |
|
|---|
Writes a heading into the buffer.
Writes a paragraph into the buffer.
Writes re-indented text into the buffer. This rewraps and preserves paragraphs.
Writes a usage line into the buffer.
| Parameters: |
|
|---|
A helper function that intelligently wraps text. By default, it assumes that it operates on a single paragraph of text but if the preserve_paragraphs parameter is provided it will intelligently handle paragraphs (defined by two empty lines).
If paragraphs are handled, a paragraph can be prefixed with an empty line containing the \b character (\x08) to indicate that no rewrapping should happen in that block.
| Parameters: |
|
|---|
The option parser is an internal class that is ultimately used to parse options and arguments. It’s modelled after optparse and brings a similar but vastly simplified API. It should generally not be used directly as the high level Click classes wrap it for you.
It’s not nearly as extensible as optparse or argparse as it does not implement features that are implemented on a higher level (such as types or defaults).
| Parameters: | ctx – optionally the Context where this parser should go with. |
|---|
Adds a positional argument named dest to the parser.
The obj can be used to identify the option in the order list that is returned from the parser.
Adds a new option named dest to the parser. The destination is not inferred (unlike with optparse) and needs to be explicitly provided. Action can be any of store, store_const, append, appnd_const or count.
The obj can be used to identify the option in the order list that is returned from the parser.
This controls how the parser deals with interspersed arguments. If this is set to False, the parser will stop on the first non-option. Click uses this to implement nested subcommands safely.
This tells the parser how to deal with unknown options. By default it will error out (which is sensible), but there is a second mode where it will ignore it and continue processing after shifting all the unknown options into the resulting args.
Parses positional arguments and returns (values, args, order) for the parsed options and arguments as well as the leftover arguments if there are any. The order is a list of objects as they appear on the command line. If arguments appear multiple times they will be memorized multiple times as well.
The CLI runner provides functionality to invoke a Click command line script for unittesting purposes in a isolated environment. This only works in single-threaded systems without any concurrency as it changes the global interpreter state.
| Parameters: |
|
|---|
Given a command object it will return the default program name for it. The default is the name attribute or "root" if not set.
Invokes a command in an isolated environment. The arguments are forwarded directly to the command line script, the extra keyword arguments are passed to the main() function of the command.
This returns a Result object.
New in version 3.0: The catch_exceptions parameter was added.
Changed in version 3.0: The result object now has an exc_info attribute with the traceback if available.
| Parameters: |
|
|---|
A context manager that creates a temporary folder and changes the current working directory to it for isolated filesystem tests.
A context manager that sets up the isolation for invoking of a command line tool. This sets up stdin with the given input data and os.environ with the overrides from the given dictionary. This also rebinds some internals in Click to be mocked (like the prompt functionality).
This is automatically done in the invoke() method.
| Parameters: |
|
|---|
Returns the environment overrides for invoking a script.
Holds the captured result of an invoked CLI script.
The traceback
The exception that happend if one did.
The exit code as integer.
The output as unicode string.
The output as bytes.
The runner that created the result
This contains all major version changes between Click releases.
(codename to be selected, release date to be decided)
(bugfix release, released on September 8th 2014)
(bugfix release, released on August 22nd 2014)
(bugfix release, released on August 13th 2014)
(codename “clonk clonk”, released on August 12th 2014)
(bugfix release, released on August 11th 2014)
(bugfix release, released on July 28th 2014)
(bugfix release, released on July 4th 2014)
(bugfix release, released on July 3rd 2014)
(bugfix release, released on June 26th 2014)
(bugfix release, released on June 14th 2014)
(codename “tap tap tap”, released on June 6th 2014)
(bugfix release, released on May 23rd 2014)
Click attempts the highest level of backwards compatibility but sometimes this is not entirely possible. In case we need to break backwards compatibility this document gives you information about how to upgrade or handle backwards compatibility properly.
Click 3.2 had to perform two changes to multi commands which were triggered by a change between Click 2 and Click 3 that had bigger consequences than anticipated.
Click 3.2 contains a fix for the Context.invoke() function when used with other commands. The original intention of this function was to invoke the other command as as if it came from the command line when it was passed a context object instead of a function. This use was only documented in a single place in the documentation before and there was no proper explanation for the method in the API documentation.
The core issue is that before 3.2 this call worked against intentions:
ctx.invoke(other_command, 'arg1', 'arg2')
This was never intended to work as it does not allow Click to operate on the parameters. Given that this pattern was never documented and ill intended the decision was made to change this behavior in a bugfix release before it spreads by accident and developers depend on it.
The correct invocation for the above command is the following:
ctx.invoke(other_command, name_of_arg1='arg1', name_of_arg2='arg2')
This also allowed us to fix the issue that defaults were not handled properly by this function.
Click 3 introduced multicommand chaning. This required a change in how Click internally dispatches. Unfortunately this change was not correctly implemented and it appeared that it was possible to provide an API that can inform the super command about all the subcommands that will be invoked.
This assumption however does not work with one of the API guarantees that have been given in the past. As such this functionality has been removed in 3.2 as it was already broken. Instead the accidentally broken functionality of the Context.invoked_subcommand attribute was restored.
If you do require the know which exact commands will be invoked there are different ways to cope with this. The first one is to let the subcommands all return functions and then to invoke the functions in a Context.resultcallback().
Click 2.0 has one breaking change which is the signature for parameter callbacks. Before 2.0, the callback was invoked with (ctx, value) whereas now it’s (ctx, param, value). This change was necessary as it otherwise made reusing callbacks too complicated.
To ease the transition Click will still accept old callbacks. Starting with Click 3.0 it will start to issue a warning to stderr to encourage you to upgrade.
In case you want to support both Click 1.0 and Click 2.0, you can make a simple decorator that adjusts the signatures:
import click
from functools import update_wrapper
def compatcallback(f):
# Click 1.0 does not have a version string stored, so we need to
# use getattr here to be safe.
if getattr(click, '__version__', '0.0') >= '2.0':
return f
return update_wrapper(lambda ctx, value: f(ctx, None, value), f)
With that helper you can then write something like this:
@compatcallback
def callback(ctx, param, value):
return value.upper()
Note that because Click 1.0 did not pass a parameter, the param argument here would be None, so a compatibility callback could not use that argument.
Click is licensed under a three-clause BSD License. It basically means: do whatever you want with it as long as the copyright in Click sticks around, the conditions are not modified and the disclaimer is present. Furthermore, you must not use the names of the authors to promote derivatives of the software without written consent.
Copyright (c) 2014 by Armin Ronacher.
Click uses parts of optparse written by Gregory P. Ward and maintained by the Python software foundation. This is limited to code in the parser.py module:
Copyright (c) 2001-2006 Gregory P. Ward. All rights reserved. Copyright (c) 2002-2006 Python Software Foundation. All rights reserved.
Some rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- The names of the contributors may not be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.