kdeldycke / click-extra Goto Github PK

A ready-to-use wrapper for Click, the Python CLI framework.

It is a drop-in replacement with good defaults that saves lots of boilerplate code and frustration. It also comes with workarounds and patches that have not reached upstream yet (or are unlikely to).

It transforms this vanilla click CLI:

Into this:

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

• Configuration file loader for:
  • TOML
  • YAML
  • JSON, with inline and block comments (Python-style # and Javascript-style //)
  • 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 files 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
• 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
• Click parameters introspection
• Colorization of help screens at the semantic-level of options, parameters, subheadings, choices, metavars and defaults
• 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
• Platform recognition utilities (macOS, Linux, Windows, UNIX, *BSD, …)
• New conditional markers for pytest:
  • @skip_linux, @skip_macos and @skip_windows
  • @unless_linux, @unless_macos and @unless_windows
• .. click:example:: and .. click:run:: Sphinx directives to document CLI source code and their execution
• Inline testing of CLI examples in documentation
• ANSI-capable Pygments lexers for shell session and console output
• Fixes 40+ bugs from other Click-related projects
• Rely on Cloup to add:
  • option groups
  • constraints
  • subcommands sections
  • aliases
  • command suggestion (Did you mean <subcommand>?)

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.
• 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.

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