click-extra 1.4.1

🌈 Extra colorization and configuration file for Click.

Click Extra

What is Click Extra?

click-extra is a collection of helpers and utilities for Click, the Python CLI framework.

It provides boilerplate code and good defaults, as well as some workarounds and patches that have not reached upstream yet (or are unlikely to).

Features

• TOML and YAML configuration file loader
• Colorization of help screens
• --color/--no-color option flag
• Colored --version option
• Colored --verbosity option and logs
• --time/--no-time flag to measure duration of command execution
• Platform recognition utilities (macOS, Linux and Windows)
• New conditional markers for pytest:
  • @skip_linux, @skip_macos and @skip_windows
  • @unless_linux, @unless_macos and @unless_windows
  • @destructive and @non_destructive

Installation

Install click-extra with pip:

$ pip install click-extra

Configuration loader usage

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: s(dynamic)]
  --help                    Show this message and exit.  [default: False]

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

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.

click:

• #2111 - Context.color = False doesn't overrides echo(color=True)
• #2110 - testing.CliRunner.invoke cannot pass color for Context instantiation

click-config-file:

• #9 - Additional configuration providers

click-help-color:

• #17 - Highlighting of options, choices and metavars

click-log:

• #30 - Add a no-color option, 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

cli-helper:

• #79 -Replace local tabulate formats with those available upstream

cloup:

• #98 - Add support for option groups on cloup.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

python-tabulate:

• #151 - Add new {rounded,simple,double}_(grid,outline} formats

Dependencies

Here is a graph of Python package dependencies:

Development

Development guidelines are the same as parent project mpm, from which click-extra originated.