Format click help output nicely with rich
Project description
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.
Which you choose will depend on your use-case and your personal disposition:
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. In fact, the whole thing can be done in just four lines:
import click
import rich_click
click.Group.format_help = rich_click.rich_format_help
click.Command.format_help = rich_click.rich_format_help
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.
Customisation
There isn't really much you can customise yet, but this is planned. I'm thinking:
- Colours
- Whether to print positional arguments or not
- Could maybe provide custom args to give help text to these
- The ability to break up commands and options into multiple named panels
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.
Project details
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
Hashes for rich_click-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1aa2be1a2d910912b7e0c5062132304647862a01a3d5d775bfd1d07766e56bf1 |
|
MD5 | ba29dd81153fb24f6774bdb22d8f21ea |
|
BLAKE2b-256 | 8ca43a3020d953008f2f081b8f3a3011f870b964148a264a834cf46b69329707 |