click-extra 7.15.0

🌈 Drop-in replacement for Click to make user-friendly and colorful CLI

What is Click Extra?

It should be easy to write a good CLI in Python. Click makes it so. But there is still hundrends of tweaks to implement by yourself to have a user-friendly CLI.

Click Extra is a ready-to-use wrapper around Click to make your CLI look good and behave well. It is a drop-in replacement with good defaults that saves lots of boilerplate code and frustration by making all parts working together.

It also comes with workarounds and patches that have not reached upstream yet (or are unlikely to).

Who is this for?

Anyone building a CLI who doesn't have time to assemble the pieces from scratch:

• You use Click and want professional defaults without the boilerplate.
• You're a security researcher turning a proof-of-concept into a presentable tool to hand off, demo, or attach to an advisory.
• You're a DevOps engineer or sysadmin whose one-off script grew into a team tool and needs --help, --verbose, --config, and colored output.

Click Extra's defaults-first design means one decorator gets you there. See the 30-second quick start.

Demo

You can try Click Extra right now in your terminal, without installing any dependency or virtual env thanks to uvx:

$ uvx click-extra

This is a great way to play with Click Extra and check that it runs fine on your system, and renders properly in your terminal.

Example

It transforms this vanilla click CLI:

Into this:

To undestrand how we ended up with the result above, go read the tutorial.

Features

• Configuration file loader for:
  • TOML
  • YAML
  • JSON, JSON5, JSONC and HJSON
  • INI, with extended interpolation, multi-level sections and non-native types (list, set, …)
  • XML
• Automatic inference of the configuration file structure from your CLI's options
• Remote loading of configuration from URLs
• Optional strict validation of configuration
• Respect the default application path on each platform (XDG spec. on Linux)
• Glob search patterns for configuration files
• A --no-config option to disable configuration file loading
• Respect of CLI > Configuration > Environment > Defaults precedence
• Normalization and discoverability of environment variables
• --show-params option to debug parameters defaults, values, environment variables and provenance
• show-params subcommand to introspect any external Click CLI's parameters
• Click parameters introspection
• CLI wrapper to apply help colorization to any Click CLI without modifying its source
• Colorization of help screens: options, choices, metavars, arguments, defaults, ranges, required labels, environment variables, subcommands and aliases all get distinct styles. Option names referenced in descriptions and docstrings are highlighted automatically.
• Global show_envvar option to display all environment variables in help screens
• -h/--help option names (see rant on other inconsistencies)
• --color/--no-color option flag
• --telemetry/--no-telemetry flag to opt-in/out of tracking code
• Recognize traditional environment variable conventions:
  • NO_COLOR from no-color.org
  • DO_NOT_TRACK from consoledonottrack.com
• Colored --version option
• Colored --verbosity option and logs
• --time/--no-time flag to measure duration of command execution
• Global show_choices to activate selection of choices on user input prompts
• Lazy-loading of subcommands from module paths to speed up CLI startup time
• click:source and click:run Sphinx directives in MyST Markdown and reStructuredText to document CLI source code and their execution
• Inline testing of CLI examples in documentation
• Render GitHub alerts into MyST admonitions
• ANSI-capable Pygments lexers for shell session and console output, with opt-in 24-bit true-color rendering
• MkDocs plugin for ANSI color rendering in code blocks
• Fixes 50+ bugs from other Click-related projects
• Rely on Cloup to add:
  • option groups
  • constraints
  • subcommands sections
  • aliases
  • command suggestion (Did you mean <subcommand>?)

Used in

Check these projects to get real-life examples of click-extra usage:

• Meta Package Manager - A unifying CLI for multiple package managers.
• Mail Deduplicate - A CLI to deduplicate similar emails.
• fireproxng - A rewrite of the fireprox tool.
• agent-catalog - Couchbase agent catalog.
• badger-proxy - An mDNS-based reverse proxy for naming services on a local network.

Feel free to send a PR to add your project in this list if you are relying on Click Extra in any way.