Metadata-Version: 2.1
Name: rich-click
Version: 1.7.4
Summary: Format click help output nicely with rich
Home-page: https://github.com/ewels/rich-click
Author: Phil Ewels
Author-email: phil@ewels.co.uk
Maintainer: Phil Ewels
Maintainer-email: phil@ewels.co.uk
License: MIT
Project-URL: Documentation, https://github.com/ewels/rich-click
Project-URL: Source Code, https://github.com/ewels/rich-click
Project-URL: Issue Tracker, https://github.com/ewels/rich-click/issues/
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click >=7
Requires-Dist: rich >=10.7.0
Requires-Dist: typing-extensions
Requires-Dist: importlib-metadata ; python_version < "3.8"
Provides-Extra: dev
Requires-Dist: mypy ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: flake8 ; extra == 'dev'
Requires-Dist: flake8-docstrings ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: packaging ; extra == 'dev'
Requires-Dist: types-setuptools ; extra == 'dev'
Richly rendered command line interfaces in click.
---
**rich-click** is a shim around [click](https://click.palletsprojects.com/) that renders help output nicely using [Rich](https://github.com/Textualize/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.
## Features
- 🌈 Rich command-line formatting of click help and error messages
- 💫 Nice styles be default, usage is simply `import rich_click as click`
- 💻 CLI tool to run on _other people's_ tools (prefix the command with `rich-click`)
- 🎁 Group commands and options into named panels
- ❌ Well formatted error messages
- 🔢 Easily give custom sort order for options and commands
- 🎨 Extensive customisation of styling and behaviour possible
## Examples
### Simple Example
To use rich-click in your code, replace `import click` with `import rich_click as click` in your existing click CLI:
```python
import rich_click as click
@click.command()
@click.option("--count", default=1, help="Number of greetings.")
@click.option("--name", prompt="Your name", help="The person to greet.")
def hello(count, name):
"""Simple program that greets NAME for a total of COUNT times."""
for _ in range(count):
click.echo(f"Hello, {name}!")
if __name__ == '__main__':
hello()
```
_Screenshot from [`examples/11_hello.py`](examples/11_hello.py)_
### More complex example
_Screenshot from [`examples/03_groups_sorting.py`](examples/03_groups_sorting.py)_
## Installation
You can install `rich-click` from the [Python Package Index (PyPI)](https://pypi.org/project/rich-click/) with `pip` or equivalent.
```bash
python -m pip install rich-click
```
Conda users can find `rich-click` on [conda forge](https://anaconda.org/conda-forge/rich-click).
Just set up conda to use conda-forge (see [docs](https://conda-forge.org/docs/user/introduction.html#how-can-i-install-packages-from-conda-forge)) then run:
```bash
conda install rich-click
```
Users on macOS can install `rich-click` via [MacPorts](https://ports.macports.org/port/py-rich-click/).
```bash
sudo port install py-rich-click
```
Note that rich-click requires `click>=7` but formatted subcommands (groups) only work with `click>=8`. With v7 the output simply reverts to default click output.
## Usage
### Import as click
To use `rich-click`, switch out your normal `click` import with `rich-click`, using the same namespace:
```python
import rich_click as click
```
That's it! ✨ Then continue to use `click` as you would normally.
> See [`examples/01_simple.py`](examples/01_simple.py) for an example.
The intention is to maintain most / all of the normal click functionality and arguments.
If you spot something that breaks or is missing once you start using the plugin, please create an issue about it.
### Declarative
If you prefer, you can `RichGroup` or `RichCommand` with the `cls` argument in your click usage instead.
This means that you can continue to use the unmodified `click` package in parallel.
> See [`examples/02_declarative.py`](examples/02_declarative.py) for an example.
### Command-line usage
`rich-click` comes with a CLI tool that allows you to format the click help output from _any_ package.
As long as that tool is using click and isn't already passing custom `cls` objects, it should work.
However, please consider it an experimental feature at this point.
To use, simply prefix to your normal command.
For example, to get richified click help text from a package called `awesometool`, you could run:
```console
$ rich-click awesometool --help
Usage: awesometool [OPTIONS]
..more richified output below..
```
### Patching
In some situations, you might be registering a command from another Click CLI that does not use Rich-Click:
```python
import rich_click as click
from some_library import another_cli
@click.group("my-cli")
def cli():
pass
# `another_cli` will NOT have Rich-Click markup. :(
cli.add_command(another_cli)
```
In this situation, `another_cli` retains its original behavior. In order to make `another_cli` work with Rich-Click, you need to patch `click` before you import `another_cli`. You can patch Click with `rich_click.cli.patch` like this:
```python
import rich_click as click
from rich_click.cli import patch
patch()
from some_library import another_cli # noqa: E402
@click.group("my-cli")
def cli():
pass
# `another_cli` will have Rich-Click markup. :)
cli.add_command(another_cli)
```
## Customisation
There are a large number of customisation options in rich-click.
These can be modified by changing variables in the `click.rich_click` namespace.
Note that most normal click options should still work, such as `show_default=True`, `required=True` and `hidden=True`.
> Note: All images below are auto-generated using another side-project of mine: [rich-codex](https://github.com/ewels/rich-codex). Pretty cool!
### Using Rich markup
In order to be as widely compatible as possible with a simple import, rich-click does _not_ parse rich formatting markup (eg. `[red]`) by default. You need to opt-in to this behaviour.
To use rich markup in your help texts, add the following:
```python
click.rich_click.USE_RICH_MARKUP = True
```
Or alternatively, with the `rich_config` and `RichHelpConfiguration`:
```python
@click.command()
@click.rich_config(help_config=click.RichHelpConfiguration(use_rich_markup=True))
def cli():
...
```
Remember that you'll need to escape any regular square brackets using a back slash in your help texts,
for example: `[dim]\[my-default: foo][\]`
> See [`examples/04_rich_markup.py`](examples/04_rich_markup.py) for an example.
### Using Markdown
If you prefer, you can use Markdown text.
You must choose either Markdown or rich markup. If you specify both, Markdown takes preference.
```python
click.rich_click.USE_MARKDOWN = True
```
Or alternatively, with the `RichHelpConfiguration`:
```python
@click.command()
@click.rich_config(help_config=click.RichHelpConfiguration(use_markdown=True))
def cli():
...
```
> See [`examples/05_markdown.py`](examples/05_markdown.py) for an example.
### Positional arguments
The default click behaviour is to only show positional arguments in the top usage string,
and not in the list below with the options.
If you prefer, you can tell rich-click to show arguments with `SHOW_ARGUMENTS`.
By default, they will get their own panel but you can tell rich-click to bundle them together with `GROUP_ARGUMENTS_OPTIONS`:
```python
click.rich_click.SHOW_ARGUMENTS = True
click.rich_click.GROUP_ARGUMENTS_OPTIONS = True
```
Or alternatively, with the `RichHelpConfiguration`:
```python
help_config = click.RichHelpConfiguration(
show_arguments=True,
group_arguments_options=True
)
@click.command()
@click.rich_config(help_config=help_config)
def cli():
...
```
> See [`examples/06_arguments.py`](examples/06_arguments.py) for an example.
### Metavars and option choices
Metavars are click's way of showing expected input types.
For example, if you have an option that must be an integer, the metavar is `INTEGER`.
If you have a choice, the metavar is a list of the possible values.
By default, rich-click shows metavars in their own column.
However, if you have a long list of choices, this column can be quite wide and result in a lot of white space:
It may look better to show metavars appended to the help text, instead of in their own column.
For this, use the following:
```python
click.rich_click.SHOW_METAVARS_COLUMN = False
click.rich_click.APPEND_METAVARS_HELP = True
```
```python
help_config = click.RichHelpConfiguration(
show_metavars_column=False,
append_metavars_help=True
)
@click.command()
@click.rich_config(help_config=help_config)
def cli():
...
```
> See [`examples/08_metavars.py`](examples/08_metavars.py) for an example.
### Error messages
By default, rich-click gives some nice formatting to error messages:
You can customise the _Try 'command --help' for help._ message with `ERRORS_SUGGESTION`
using rich-click though, and add some text after the error with `ERRORS_EPILOGUE`.
For example, from [`examples/07_custom_errors.py`](examples/07_custom_errors.py):
```python
click.rich_click.STYLE_ERRORS_SUGGESTION = "magenta italic"
click.rich_click.ERRORS_SUGGESTION = "Try running the '--help' flag for more information."
click.rich_click.ERRORS_EPILOGUE = "To find out more, visit [link=https://mytool.com]https://mytool.com[/link]"
```
> See [`examples/07_custom_errors.py`](examples/07_custom_errors.py) for an example.
### Help width
The default behaviour of rich-click is to use the full width of the terminal for output.
However, if you've carefully crafted your help texts for the default narrow click output, you may find that you now have a lot of whitespace at the side of the panels.
To limit the maximum width of the help output, regardless of the terminal size, set `WIDTH` in characters as follows:
```python
click.rich_click.WIDTH = 128
```
To still use the full width of the terminal up to a certain limit, set `MAX_WIDTH` in characters as follows:
```python
click.rich_click.MAX_WIDTH = 96
```
Setting `MAX_WIDTH` overrides the effect of `WIDTH`
### Styling
Most aspects of rich-click formatting can be customised, from colours to alignment.
For example, to print the option flags in a different colour, you can use:
```python
click.rich_click.STYLE_OPTION = "magenta"
```
To add a blank line between rows of options, you can use:
```python
click.rich_click.STYLE_OPTIONS_TABLE_LEADING = 1
click.rich_click.STYLE_OPTIONS_TABLE_BOX = "SIMPLE"
```
You can make some really ~horrible~ _colourful_ solutions using these styles if you wish:
> See [`examples/10_table_styles.py`](examples/10_table_styles.py) for an example.
See the [_Configuration options_](#configuration-options) section below for the full list of available options.
## Groups and sorting
`rich-click` gives functionality to list options and subcommands in groups, printed as separate panels.
It accepts a list of options / commands which means you can also choose a custom sorting order.
- For options (flags), set `click.rich_click.OPTION_GROUPS`
- For subcommands (groups), set `click.rich_click.COMMAND_GROUPS`
When grouping subcommands into more than one group (in above example: 'Main usage' and 'Configuration') you may find that the automatically calculated widths of different groups do not line up, due to varying option name lengths.
You can avoid this by enforcing the alignment of the help text across groups by setting `click.rich_click.STYLE_COMMANDS_TABLE_COLUMN_WIDTH_RATIO = (1, 2)`. This results in a fixed ratio of 1:2 for the width of command name and help text column.
> See [`examples/03_groups_sorting.py`](examples/03_groups_sorting.py) for a full example.
### Options
To group option flags into two sections with custom names, see the following example:
```python
click.rich_click.OPTION_GROUPS = {
"mytool": [
{
"name": "Simple options",
"options": ["--name", "--description", "--version", "--help"],
},
{
"name": "Advanced options",
"options": ["--force", "--yes", "--delete"],
},
]
}
```
If you omit `name` it will use `Commands` (can be configured with `OPTIONS_PANEL_TITLE`).
### Commands
Here 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.
```python
click.rich_click.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`).
### Multiple commands
If you use multiple nested subcommands, you can specify their commands using the top-level dictionary keys:
```python
click.rich_click.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"]}],
}
```
### Table styling
Typically you would style the option / command tables using the global config options.
However, if you wish you may style tables on a per-group basis using the `table_styles` key:
```python
click.rich_click.COMMAND_GROUPS = {
"mytool": [
{
"commands": ["sync", "auth"],
"table_styles": {
"show_lines": True,
"row_styles": ["magenta", "yellow", "cyan", "green"],
"border_style": "red",
"box": "DOUBLE",
},
},
],
}
```
The available keys are: `show_lines`, `leading`, `box`, `border_style`, `row_styles`, `pad_edge`, `padding`.
## Configuration options
Here is the full list of config options:
```python
# Default styles
STYLE_OPTION = "bold cyan"
STYLE_ARGUMENT = "bold cyan"
STYLE_COMMAND = "bold cyan"
STYLE_SWITCH = "bold green"
STYLE_METAVAR = "bold yellow"
STYLE_METAVAR_APPEND = "dim yellow"
STYLE_METAVAR_SEPARATOR = "dim"
STYLE_HEADER_TEXT = ""
STYLE_EPILOG_TEXT = ""
STYLE_FOOTER_TEXT = ""
STYLE_USAGE = "yellow"
STYLE_USAGE_COMMAND = "bold"
STYLE_DEPRECATED = "red"
STYLE_HELPTEXT_FIRST_LINE = ""
STYLE_HELPTEXT = "dim"
STYLE_OPTION_HELP = ""
STYLE_OPTION_DEFAULT = "dim"
STYLE_OPTION_ENVVAR = "dim yellow"
STYLE_REQUIRED_SHORT = "red"
STYLE_REQUIRED_LONG = "dim red"
STYLE_OPTIONS_PANEL_BORDER = "dim"
ALIGN_OPTIONS_PANEL = "left"
STYLE_OPTIONS_TABLE_SHOW_LINES = False
STYLE_OPTIONS_TABLE_LEADING = 0
STYLE_OPTIONS_TABLE_PAD_EDGE = False
STYLE_OPTIONS_TABLE_PADDING = (0, 1)
STYLE_OPTIONS_TABLE_BOX = ""
STYLE_OPTIONS_TABLE_ROW_STYLES = None
STYLE_OPTIONS_TABLE_BORDER_STYLE = None
STYLE_COMMANDS_PANEL_BORDER = "dim"
ALIGN_COMMANDS_PANEL = "left"
STYLE_COMMANDS_TABLE_SHOW_LINES = False
STYLE_COMMANDS_TABLE_LEADING = 0
STYLE_COMMANDS_TABLE_PAD_EDGE = False
STYLE_COMMANDS_TABLE_PADDING = (0, 1)
STYLE_COMMANDS_TABLE_BOX = ""
STYLE_COMMANDS_TABLE_ROW_STYLES = None
STYLE_COMMANDS_TABLE_BORDER_STYLE = None
STYLE_COMMANDS_TABLE_COLUMN_WIDTH_RATIO = (None, None)
STYLE_ERRORS_PANEL_BORDER = "red"
ALIGN_ERRORS_PANEL = "left"
STYLE_ERRORS_SUGGESTION = "dim"
STYLE_ERRORS_SUGGESTION_COMMAND = "blue"
STYLE_ABORTED = "red"
WIDTH = int(getenv("TERMINAL_WIDTH")) if getenv("TERMINAL_WIDTH") else None
MAX_WIDTH = int(getenv("TERMINAL_WIDTH")) if getenv("TERMINAL_WIDTH") else WIDTH
COLOR_SYSTEM = "auto" # Set to None to disable colors
FORCE_TERMINAL = True if getenv("GITHUB_ACTIONS") or getenv("FORCE_COLOR") or getenv("PY_COLORS") else None
# Fixed strings
HEADER_TEXT = None
FOOTER_TEXT = None
DEPRECATED_STRING = "(Deprecated) "
DEFAULT_STRING = "[default: {}]"
ENVVAR_STRING = "[env var: {}]"
REQUIRED_SHORT_STRING = "*"
REQUIRED_LONG_STRING = "[required]"
RANGE_STRING = " [{}]"
APPEND_METAVARS_HELP_STRING = "({})"
ARGUMENTS_PANEL_TITLE = "Arguments"
OPTIONS_PANEL_TITLE = "Options"
COMMANDS_PANEL_TITLE = "Commands"
ERRORS_PANEL_TITLE = "Error"
ERRORS_SUGGESTION = None # Default: Try 'cmd -h' for help. Set to False to disable.
ERRORS_EPILOGUE = None
ABORTED_TEXT = "Aborted."
# Behaviours
SHOW_ARGUMENTS = False # Show positional arguments
SHOW_METAVARS_COLUMN = True # Show a column with the option metavar (eg. INTEGER)
APPEND_METAVARS_HELP = False # Append metavar (eg. [TEXT]) after the help text
GROUP_ARGUMENTS_OPTIONS = False # Show arguments with options instead of in own panel
OPTION_ENVVAR_FIRST = False # Show env vars before option help text instead of avert
USE_MARKDOWN = False # Parse help strings as markdown
USE_MARKDOWN_EMOJI = True # Parse emoji codes in markdown :smile:
USE_RICH_MARKUP = False # Parse help strings for rich markup (eg. [red]my text[/])
COMMAND_GROUPS = {} # Define sorted groups of panels to display subcommands
OPTION_GROUPS = {} # Define sorted groups of panels to display options and arguments
USE_CLICK_SHORT_HELP = False # Use click's default function to truncate help text
```
Full type annotations of these config options are availble in `src/rich_click/rich_click.py`.
100% of these options are supported in the `RichHelpConfiguration` class, as well.
## Contributing
Contributions and suggestions for new features are welcome, as are bug reports!
Please create a new [issue](https://github.com/ewels/rich-click/issues)
or better still, dive right in with a pull-request.
### Local setup
1. Create a new venv with a python3.7+ interpreter using `python3 -m venv venv`
2. Activate the venv with `source venv/bin/activate`
3. Install our the package as an editable including all dev dependencies with `pip3 install -e ."[dev]"`
4. Install pre-commit with `pre-commit install`
#### Pre-commit
Our pre-commit hooks contain the following hooks:
- [Prettier](https://prettier.io/): formats our markdown and yaml files nicely.
- no relative imports: prevents you from using relative imports.
- [iSort](https://pycqa.github.io/isort/): will automatically sort the imports alphabetically.
- [black](https://black.readthedocs.io/): will automatically format your code to be according to standardized python format.
- [flake8](https://flake8.pycqa.org/): will do linting checks to make sure all your code is correctly styled and used.
- [mypy](http://mypy-lang.org/): static type checker which verifies you are not using objects incorrectly.
As mentioned, some of these tools automatically fix your code while other only highlight potential issues.
Sometimes it will be enough to try to commit a second time and it will pass, while other times it may require
manual changes to your code.
In rare cases it may be difficult or undesirable to change to code to pass the linting rules.
If this happens, it's ok to add a flake8 `# noqa` or mypy `# type: ignore` comment to skip that line.
For details of how to do this, please see the [flake8 docs](https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#in-line-ignoring-errors)
and [mypy docs](https://mypy.readthedocs.io/en/stable/common_issues.html#spurious-errors-and-locally-silencing-the-checker).
## Credits
This package was written by Phil Ewels ([@ewels](http://github.com/ewels/)),
based on initial code by Will McGugan ([@willmcgugan](https://github.com/willmcgugan)).
rich-click is co-maintained by [@dwreeves](http://github.com/dwreeves/).
Furthermore, these contributors helped make the package what it is today:
- [@BrutalSimplicity](https://github.com/BrutalSimplicity)
- [@harens](http://github.com/harens/)
- [@fridex](http://github.com/fridex/)
- [@pawamoy](http://github.com/pawamoy/)
- [@jorrick](http://github.com/harens/)
See the full list of contributors [here](https://github.com/ewels/rich-click/graphs/contributors).
