rich-click
Format click help output nicely with Rich.
- Click is a "Python package for creating beautiful command line interfaces".
- Rich is a "Python library for rich text and beautiful formatting in the terminal".
The intention of rich-click is to provide attractive help output from
click, formatted with rich, with minimal customisation required.
Screenshots
| Native click help | With rich-click |
|---|---|
 |
 |
Installation
You can install rich-click from the Python Package Index (PyPI) with pip or equivalent.
python -m pip install rich-click
Usage
There are two main ways to set up rich-click formatting for your tool:
monkey patching or declarative.
Which you choose will depend on your use-case and your personal disposition!
Note that the intention is to maintain most / all of the normal click functionality and arguments. If you spot something that is missing once you start using the plugin, please create an issue about it.
The path of least typing
Monkey patching is probably bad and you should only use this method if you are a Responsible Developer. It's also good if you're lazy, as it requires very little typing.
Assuming that you're already using click, you only need to add three lines:
import rich_click
click.Command.format_help = rich_click.rich_format_help
click.Group.format_help = rich_click.rich_format_help
(if you're not click groups, only 2 lines!)
This overwrites the default click methods with those from the rich-click package.
As such, no other changes are needed - just continue to use click as you would
normally and it will use these custom methods to print your help output.
The good and proper way
If using monkey-patching in your project makes your palms sweaty and your pulse race,
then you'll be pleased to know that you can also use rich-click in a nicely
declarative and verbose manner:
import click
import rich_click
class RichClickGroup(click.Group):
def format_help(self, ctx, formatter):
rich_click.rich_format_help(self, ctx, formatter)
class RichClickCommand(click.Command):
def format_help(self, ctx, formatter):
rich_click.rich_format_help(self, ctx, formatter)
@click.group(cls=RichClickGroup)
@click.option('--debug/--no-debug', default=False)
def cli(debug):
click.echo(f"Debug mode is {'on' if debug else 'off'}")
@cli.command(cls=RichClickCommand)
def sync():
click.echo('Syncing')
(example based on the click docs)
Here we are making new Group and Command child classes that are based on click.
We define our custom format_help() functions and then tell click to to use these classes with the cls argument.
Command groups and sorting
rich-click gives functionality to list subcommands in groups, printed as separate panels.
It accepts a list of commands which means you can also choose a custom sorting order.
For example, you can produce something that looks like this:
To do this, set rich_click.core.COMMAND_GROUPS.
In this example, we create two groups of commands for the base command of mytool.
Any subcommands not listed will automatically be printed in a panel at the end labelled "Commands" as usual.
rich_click.core.COMMAND_GROUPS = {
"mytool": [
{
"name": "Commands for uploading",
"commands": ["sync", "upload"],
},
{
"name": "Download data",
"commands": ["get", "fetch", "download"],
},
]
}
If you omit name it will use Commands (can be configured with COMMANDS_PANEL_TITLE, see below).
If you use nested subcommands, you can specify multiple base paths using the base dictionary keys:
rich_click.core.COMMAND_GROUPS = {
"mytool": ["commands": ["sync", "auth"]],
"mytool sync": [
{
"name": "Commands for uploading",
"commands": ["sync", "upload"],
},
{
"name": "Download data",
"commands": ["get", "fetch", "download"],
},
],
"mytool auth":[{"commands": ["login", "logout"]}],
}
Customisation
You can customise most things that are related to formatting.
For example, to limit the maximum width of the help output to 100 characters:
rich_click.core.MAX_WIDTH = 100
To print the option flags in a different colour, use:
rich_click.core.STYLE_OPTION = "magenta"
Full list of config options
# Default styles
STYLE_OPTION = "bold cyan"
STYLE_SWITCH = "bold green"
STYLE_METAVAR = "bold yellow"
STYLE_USAGE = "yellow"
STYLE_USAGE_COMMAND = "bold"
STYLE_DEPRECATED = "red"
STYLE_HELPTEXT_FIRST_LINE = ""
STYLE_HELPTEXT = "dim"
STYLE_METAVAR = "bold yellow"
STYLE_OPTION_HELP = ""
STYLE_OPTION_DEFAULT = "dim"
STYLE_REQUIRED_SHORT = "red"
STYLE_REQUIRED_LONG = "dim red"
STYLE_OPTIONS_PANEL_BORDER = "dim"
ALIGN_OPTIONS_PANEL = "left"
STYLE_COMMANDS_PANEL_BORDER = "dim"
ALIGN_COMMANDS_PANEL = "left"
MAX_WIDTH = None # Set to an int to limit to that many characters
# Fixed strings
DEPRECATED_STRING = "(Deprecated) "
DEFAULT_STRING = " [default: {}]"
REQUIRED_SHORT_STRING = "*"
REQUIRED_LONG_STRING = " [required]"
RANGE_STRING = " [{}]"
OPTIONS_PANEL_TITLE = "Options"
COMMANDS_PANEL_TITLE = "Commands"
# Behaviours
SHOW_ARGUMENTS = False
USE_MARKDOWN = False
USE_RICH_MARKUP = False
COMMAND_GROUPS = {}
OPTION_GROUPS = {}
Contributing
Contributions and suggestions for new features are welcome, as are bug reports! Please create a new issue or better still, dive right in with a pull-request.
Credits
This package was put together hastily by Phil Ewels (@ewels), but the hard work was really done by Will McGugan (@willmcgugan) who not only is the author of Rich but also wrote the original code that this package is based on.
1 maintainer
Metadata
1 maintainer
Release files for rich-click 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| rich-click-0.3.0.tar.gz | 9.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| rich_click-0.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 18.4 kB
Release files / rich-click-0.3.0.tar.gz
| Download URL | rich-click-0.3.0.tar.gz |
|---|---|
| Size | 9.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e00bd64f8ef1c9199db3bed9bbad4872310dbd814d0e137558c13f1bcb56c7a2
|
|
BLAKE2b-256 checksum How to use checksums |
d5d83dda185cb1c964dbffe8fac592f06213e446d9bcf9f9f6e78770c9a454b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.62.3 importlib-metadata/4.11.0 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.10
|
Release files / rich_click-0.3.0-py3-none-any.whl
| Download URL | rich_click-0.3.0-py3-none-any.whl |
|---|---|
| Size | 8.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
457a14270840a3d2e7a54e20457140d06abea77adb8bdab4800ad1e7bba3ee8f
|
|
BLAKE2b-256 checksum How to use checksums |
b5755f0bcf1b3702e5d4062af705b2daa4138b7d8b1fdb87a94ebbeacd54cbff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.62.3 importlib-metadata/4.11.0 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.10
|
