Commands and Groups¶
The structure of a Click application is defined with Command
, which
defines an individual named command, and Group
, which defines a nested
collection of commands (or more groups) under a name.
Callback Invocation¶
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, the situation looks different. In this case, the callback fires whenever a subcommand fires. 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(f"Debug mode is {'on' if debug else 'off'}")
@cli.command() # @cli, not @click!
def sync():
click.echo('Syncing')
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
Syncing
Passing Parameters¶
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
.
tool.py --help
will return the help for the whole program (listing subcommands).tool.py sub --help
will return the help for thesub
subcommand.But
tool.py --help sub
will treat--help
as an argument for the main program. Click then invokes the callback for--help
, which prints the help and aborts the program before click can process the subcommand.
Nested Handling and Contexts¶
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):
# ensure that ctx.obj exists and is a dict (in case `cli()` is called
# by means other than the `if` block below)
ctx.ensure_object(dict)
ctx.obj['DEBUG'] = debug
@cli.command()
@click.pass_context
def sync(ctx):
click.echo(f"Debug is {'on' if ctx.obj['DEBUG'] else '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.
Decorating Commands¶
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
pass_context()
.
This is a very powerful concept that can be used to build very complex nested applications; see Complex Applications for more information.
Group Invocation Without Command¶
By default, a group 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.
@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(f"I am about to invoke {ctx.invoked_subcommand}")
@cli.command()
def sync():
click.echo('The subcommand')
$ tool
I was invoked without subcommand
$ tool sync
I am about to invoke sync
The subcommand
Custom Groups¶
You can customize the behavior of a group beyond the arguments it accepts by
subclassing click.Group
.
The most common methods to override are get_command()
and
list_commands()
.
The following example implements a basic plugin system that loads commands from Python files in a folder. The command is lazily loaded to avoid slow startup.
import importlib.util
import os
import click
class PluginGroup(click.Group):
def __init__(self, name=None, plugin_folder="commands", **kwargs):
super().__init__(name=name, **kwargs)
self.plugin_folder = plugin_folder
def list_commands(self, ctx):
rv = []
for filename in os.listdir(self.plugin_folder):
if filename.endswith(".py"):
rv.append(filename[:-3])
rv.sort()
return rv
def get_command(self, ctx, name):
path = os.path.join(self.plugin_folder, f"{name}.py")
spec = importlib.util.spec_from_file_location(name, path)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module.cli
cli = PluginGroup(
plugin_folder=os.path.join(os.path.dirname(__file__), "commands")
)
if __name__ == "__main__":
cli()
Custom classes can also be used with decorators:
@click.group(
cls=PluginGroup,
plugin_folder=os.path.join(os.path.dirname(__file__), "commands")
)
def cli():
pass
Command Chaining¶
It is useful to invoke more than one subcommand in one call. For example,
my-app validate build upload
would invoke validate
, then build
, then
upload
. To implement this, pass chain=True
when creating a group.
@click.group(chain=True)
def cli():
pass
@cli.command('validate')
def validate():
click.echo('validate')
@cli.command('build')
def build():
click.echo('build')
You can invoke it like this:
$ my-app validate build
validate
build
When using chaining, there are a few restrictions:
Only the last command may use
nargs=-1
on an argument, otherwise the parser will not be able to find further commands.It is not possible to nest groups below a chain group.
On the command line, options must be specified before arguments for each command in the chain.
The
Context.invoked_subcommand
attribute will be'*'
because the parser doesn’t know the full list of commands that will run yet.
Command Pipelines¶
When using chaining, a common pattern is to have each command process the result of the previous command.
A straightforward way to do this is to use make_pass_decorator()
to pass
a context object to each command, and store and read the data on that object.
pass_ns = click.make_pass_decorator(dict, ensure=True)
@click.group(chain=True)
@click.argument("name")
@pass_ns
def cli(ns, name):
ns["name"] = name
@cli.command
@pass_ns
def lower(ns):
ns["name"] = ns["name"].lower()
@cli.command
@pass_ns
def show(ns):
click.echo(ns["name"])
$ process Click show lower show
Click
click
Another way to do this is to collect data returned by each command, then process
it at the end of the chain. Use the group’s result_callback()
decorator to register a function that is called after the chain is finished. It
is passed the list of return values as well as any parameters registered on the
group.
A command can return anything, including a function. Here’s an example of that, where each subcommand creates a function that processes the input, then the result callback calls each function. The command takes a file, processes each line, then outputs it. If no subcommands are given, it outputs the contents of the file unchanged.
@click.group(chain=True, invoke_without_command=True)
@click.argument("fin", type=click.File("r"))
def cli(fin):
pass
@cli.result_callback()
def process_pipeline(processors, fin):
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("upper")
def make_uppercase():
def processor(iterator):
for line in iterator:
yield line.upper()
return processor
@cli.command("lower")
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.
The first thing is to make a
group()
that is chainable. In addition to that we also instruct Click to invoke even if no subcommand is defined. If this would not be done, then invoking an empty pipeline would produce the help page instead of running the result callbacks.The next thing we do is to register a result callback on our group. This callback will be invoked with an argument which is the list of all return values of all subcommands and then the same keyword parameters as our group itself. This means we can access the input file easily there without having to use the context object.
In this result callback we create an iterator of all the lines in the input file and then pass this iterator through all the returned callbacks from all subcommands and finally we print all lines to stdout.
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, see the imagepipe example in the Click repository. It implements a pipeline based image editing tool that has a nice internal structure.
Overriding Defaults¶
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:
default_map = {
"debug": True, # default for a top level option
"runserver": {"port": 5000} # default for a subcommand
}
The default map can be provided when the script is invoked, or overridden 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(f"Serving on http://127.0.0.1:{port}/")
if __name__ == '__main__':
cli(default_map={
'runserver': {
'port': 5000
}
})
And in action:
$ cli runserver
Serving on http://127.0.0.1:5000/
Context Defaults¶
Changelog
Added 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(f"Serving on http://127.0.0.1:{port}/")
if __name__ == '__main__':
cli()
And again the example in action:
$ cli runserver
Serving on http://127.0.0.1:5000/
Command Return Values¶
Changelog
Added 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 Command Chaining where it has been demonstrated that chained groups can have callbacks that process all return values.
When working with command return values in Click, this is what you need to know:
The return value of a command callback is generally returned from the
Command.invoke()
method. The exception to this rule has to do withGroup
s:In a group the return value is generally the return value of the subcommand invoked. The only exception to this rule is that the return value is the return value of the group callback if it’s invoked without arguments and
invoke_without_command
is enabled.If a group is set up for chaining then the return value is a list of all subcommands’ results.
Return values of groups can be processed through a
Group.result_callback
. This is invoked with the list of all return values in chain mode, or the single return value in case of non chained commands.
The return value is bubbled through from the
Context.invoke()
andContext.forward()
methods. This is useful in situations where you internally want to call into another command.Click does not have any hard requirements for the return values and does not use them itself. This allows return values to be used for custom decorators or workflows (like in the command chaining example).
When a Click script is invoked as command line application (through
Command.main()
) the return value is ignored unless thestandalone_mode
is disabled in which case it’s bubbled through.