Tutorial¶
This tutorial details how we transformed the canonical click example:
Into this:
All bells and whistles¶
The canonical click example is implemented that way:
from click import command, echo, option
@command
@option("--count", default=1, help="Number of greetings.")
@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 _ in range(count):
echo(f"Hello, {name}!")
Whose help screen renders as:
$ hello --help
Usage: hello [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.
To augment the simple example above with all the bells and whistles click-extra has in store, you just need to replace the base command decorator with its extra_-prefixed variant:
from click_extra import extra_command, echo, option
@extra_command
@option("--count", default=1, help="Number of greetings.")
@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 _ in range(count):
echo(f"Hello, {name}!")
And now you get:
$ hello --help
Usage: hello [OPTIONS]
Simple program that greets NAME for a total of COUNT times.
Options:
--count INTEGER Number of greetings. [default: 1]
--name TEXT The person to greet.
--time / --no-time Measure and print elapsed execution time. [default:
no-time]
--color, --ansi / --no-color, --no-ansi
Strip out all colors and all ANSI codes from output.
[default: color]
-C, --config CONFIG_PATH Location of the configuration file. Supports glob
pattern of local path and remote URL. [default:
~/.config/hello/*.{toml,yaml,yml,json,ini,xml}]
--show-params Show all CLI parameters, their provenance, defaults
and value, then exit.
-v, --verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
--version Show the version and exit.
-h, --help Show this message and exit.
That’s it!
Here is a diff highlight of the simple changes between the two versions:
-from click import command, echo, option
+from click_extra import extra_command, echo, option
-@command
+@extra_command
@option("--count", default=1, help="Number of greetings.")
@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 _ in range(count):
echo(f"Hello, {name}!")
Tip
As you can see above, click_extra is proxy-ing the whole click namespace, so you can use it as a drop-in replacement.
Standalone options¶
If you do not like the opiniated way the @extra_command decorator is built with all its defaults options, you are still free to pick them up independently.
If, for example, you’re only interested in using the --config option, nothing prevents you to use it with a standard click CLI:
from click import command, echo, option
from click_extra import config_option
@command
@option("--count", default=1, help="Number of greetings.")
@option("--name", prompt="Your name", help="The person to greet.")
@config_option
def hello(count, name):
"""Simple program that greets NAME for a total of COUNT times."""
for _ in range(count):
echo(f"Hello, {name}!")
Which now renders to:
$ hello --help
Usage: hello [OPTIONS]
Simple program that greets NAME for a total of COUNT times.
Options:
--count INTEGER Number of greetings.
--name TEXT The person to greet.
-C, --config CONFIG_PATH Location of the configuration file. Supports glob
pattern of local path and remote URL.
--help Show this message and exit.
This option itself behave like any Click option and can be customized easily:
from click import command, echo, option
from click_extra import config_option
@command
@option("--count", default=1, help="Number of greetings.")
@option("--name", prompt="Your name", help="The person to greet.")
@config_option("--hello-conf", metavar="CONF_FILE", help="Loads CLI config.")
def hello(count, name):
"""Simple program that greets NAME for a total of COUNT times."""
for _ in range(count):
echo(f"Hello, {name}!")
$ hello --help
Usage: hello [OPTIONS]
Simple program that greets NAME for a total of COUNT times.
Options:
--count INTEGER Number of greetings.
--name TEXT The person to greet.
--hello-conf CONF_FILE Loads CLI config.
--help Show this message and exit.
Click Extra’s options are sub-classes of Cloup’s and supports all its features, like option groups:
from click import echo
from cloup import command, option, option_group
from cloup.constraints import RequireAtLeast
from click_extra import config_option
@command()
@option("--count", default=1, help="Number of greetings.")
@option("--name", prompt="Your name", help="The person to greet.")
@option_group(
"Cool options",
option("--foo", help="The option that starts it all."),
option("--bar", help="Another important option."),
config_option("--hello-conf", metavar="CONF_FILE", help="Loads CLI config."),
constraint=RequireAtLeast(1),
)
def hello(count, name, foo, bar, hello_conf):
"""Simple program that greets NAME for a total of COUNT times."""
for _ in range(count):
echo(f"Hello, {name}!")
See how the configuration option is grouped with others:
$ hello --help
Usage: hello [OPTIONS]
Simple program that greets NAME for a total of COUNT times.
Cool options: [at least 1 required]
--foo TEXT The option that starts it all.
--bar TEXT Another important option.
--hello-conf CONF_FILE Loads CLI config.
Other options:
--count INTEGER Number of greetings.
--name TEXT The person to greet.
--help Show this message and exit.
Caution
Notice in the example above how the @command() decorator from Cloup is used with parenthesis. Contrary to Click and Click Extra, Cloup requires parenthesis on its decorators.
See also
Click Extra provides these additional options: