🌈 Extra colorization and configuration loading for Click.
Project description
Click Extra
What is Click Extra?
click-extra is a collection of helpers and utilities for
Click, the Python CLI framework.
It is a drop-in replacement with good defaults that saves you some boilerplate code. It also comes with some workarounds and patches that have not reached upstream yet (or are unlikely to).
Simple click example |
Same with click-extra |
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}!")
if __name__ == "__main__":
hello()
|
from click_extra 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}!")
if __name__ == "__main__":
hello()
|
 |
 |
This example demonstrate the all-in-one package with its default options. You are still free to pick-up some of these options one-by-one, as documented below.
Features
- configuration file loader for:
TOMLYAMLJSON, with inline and block comments (Python-style#and Javascript-style//)INI, with extended interpolation, multi-level sections and non-native types (list, sets, …)
- Respect of
CLI > Configuration > Environment > Defaultsprecedence - Colorization of help screens
--color/--no-coloroption flag- Colored
--versionoption - Colored
--verbosityoption and logs --time/--no-timeflag to measure duration of command execution- Platform recognition utilities (macOS, Linux and Windows)
- New conditional markers for
pytest:@skip_linux,@skip_macosand@skip_windows@unless_linux,@unless_macosand@unless_windows@destructiveand@non_destructive
Installation
Install click-extra with pip:
$ pip install click-extra
Configuration loader usage
The configuration loader source values according the following precedence:
CLI parameters > Configuration file > Environment variables > Defaults.
The structure of the configuration file is automaticcaly derived from the parameters of the CLI. There is no need to manually produce a configuration data structure to mirror the CLI.
INI configuration files are allowed to use ExtendedInterpolation by default.
TOML configuration
Given this CLI in a my_cli.py file:
import click
from click_extra.config import config_option
@click.group(context_settings={"show_default": True})
@click.option("--dummy-flag/--no-flag")
@click.option("--my-list", multiple=True)
@config_option()
def my_cli(dummy_flag, my_list):
click.echo(f"dummy_flag is {dummy_flag!r}")
click.echo(f"my_list is {my_list!r}")
@my_cli.command()
@click.option("--int-param", type=int, default=10)
def subcommand(int_param):
click.echo(f"int_parameter is {int_param!r}")
if __name__ == "__main__":
my_cli()
It produces the following help screens:
$ python ./my_cli.py
Usage: my_cli.py [OPTIONS] COMMAND [ARGS]...
Options:
--dummy-flag / --no-flag [default: no-flag]
--my-list TEXT
-C, --config CONFIG_PATH Location of the configuration file. Supports both
local path and remote URL. [default:
~/.my_cli.py/config.{toml,yaml,yml,json,ini,config,conf}]
--help Show this message and exit.
Commands:
subcommand
A bare call returns:
$ ./my_cli.py subcommand
dummy_flag is False
my_list is ()
int_parameter is 10
Now we will change the default CLI output by creating a TOML file at
~/.my_cli.py/config.toml which contains:
# My default configuration file.
top_level_param = "is_ignored"
[my-cli]
extra_value = "is ignored too"
dummy_flag = true # New boolean default.
my_list = ["item 1", "item #2", "Very Last Item!"]
[garbage]
# An empty random section that will be skipped
[my-cli.subcommand]
int_param = 3
random_stuff = "will be ignored"
In the file above, pay attention to:
- the configuration's folder (
~/.my_cli.py/) which correspond to the script's name (my_cli.py); - the top-level config section (
[my-cli]), that is derived from the CLI's group ID (def my_cli()); - all the extra comments, sections and values that will be silently ignored.
Now we can verify the TOML file is read automatticaly and change the defaults:
$ ./my_cli.py subcommand
dummy_flag is True
my_list is ('item 1', 'item #2', 'Very Last Item!')
int_parameter is 3
Still, any inline parameter is allowedal to ovverides the configuration defaults:
$ ./my_cli.py subcommand --int-param 555
dummy_flag is True
my_list is ('item 1', 'item #2', 'Very Last Item!')
int_parameter is 555
YAML configuration
Same example as above is working as-is with YAML.
Just replace the TOML file with the following configuration at
~/.my_cli.py/config.yaml:
# My default configuration file.
top_level_param: is_ignored
my-cli:
extra_value: is ignored too
dummy_flag: true # New boolean default.
my_list:
- point 1
- 'point #2'
- Very Last Point!
subcommand:
int_param: 77
random_stuff: will be ignored
garbage: >
An empty random section that will be skipped
$ ./my_cli.py --config ~/.my_cli.py/config.yaml subcommand
dummy_flag is True
my_list is ('point 1', 'point #2', 'Very Last Point!')
int_parameter is 77
JSON configuration
Again, same for JSON:
{
"top_level_param": "is_ignored",
"garbage": {},
"my-cli": {
"dummy_flag": true,
"extra_value": "is ignored too",
"my_list": [
"item 1",
"item #2",
"Very Last Item!"
],
"subcommand": {
"int_param": 65,
"random_stuff": "will be ignored"
}
}
}
$ ./my_cli.py --config ~/.my_cli.py/config.json subcommand
dummy_flag is True
my_list is ('item 1', 'item #2', 'Very Last Item!')
int_parameter is 65
Remote configuration
Remote URL can be passed directly to the --config option:
$ ./my_cli.py --config https://example.com/dummy/configuration.yaml subcommand
dummy_flag is True
my_list is ('point 1', 'point #2', 'Very Last Point!')
int_parameter is 77
Colorization of help screen
Extend Cloup's own help formatter and theme to add colorization of:
- Options
- Choices
- Metavars
Used in
Check these projects to get real-life example of click-extra usage:
- Mail Deduplicate - A CLI to deduplicate similar emails.
- Meta Package Manager - A unifying CLI for multiple package managers.
Issues addressed by click-extra
Keep track of things to undo if they reach upstream.
#2111-Context.color = Falsedoesn't overridesecho(color=True)#2110-testing.CliRunner.invokecannot pass color forContextinstantiation
#9- Inquiry on Repo Status#8- Exclude some options from config file#2- Order of configuration file and environment variable value
#30- Add ano-coloroption, method or parameter to disable colouring globally#29- Log level is leaking between invokations: hack to force-reset it#24- Add missing string interpolation in error message#18- Add trailing dot to help text
#98- Add support for option groups oncloup.Group#97- Styling metavars, default values, env var, choices#95- Highlights options, choices and metavars#96- Add loading of options from a TOML configuration file
Dependencies
Here is a graph of Python package dependencies:
Development
Development guidelines
are the same as
parent project mpm, from
which click-extra originated.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file click-extra-1.9.0.tar.gz.
File metadata
- Download URL: click-extra-1.9.0.tar.gz
- Upload date:
- Size: 31.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.0 CPython/3.9.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 23f9946d6d9ab65789439130a7f262f9981e8e4c66f4d5824d681b9101f63100 |
|
| MD5 | 9fd7df453e34f8382001f5e436641c34 |
|
| BLAKE2b-256 | 1dd176515031c80eabab9ab86daec7bdf07032fe06360f6adcbf4c55a0684e59 |
File details
Details for the file click_extra-1.9.0-py3-none-any.whl.
File metadata
- Download URL: click_extra-1.9.0-py3-none-any.whl
- Upload date:
- Size: 43.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.0 CPython/3.9.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 15110dc7a77c4b59f0f434c8d4026d197a62699094307d392c773c4a99488677 |
|
| MD5 | 25ebc66d92c128eb9d7e00959d204ed4 |
|
| BLAKE2b-256 | 261d5bb3716394b526a593feb8e585ece59e24b02cf53c8775ceb97b74143fb8 |
