click-rich-help 0.3.0

make a beautiful click app with rich

click-rich-help

make a beautiful click app with rich

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Installation
3. Usage
4. Contributing
5. Acknowledgments

About The Project

I wanted a simple python package to make my click app's help more readable.

Click the on the cast below to see it in action!

Since writing this package the more opinionated rich-click has been written. If that output is more your speed, go check it out!

Getting Started

Installation

with pip:

pip install click-rich-help

with conda/mamba:

conda install -c conda-forge click-rich-help

(back to top)

Usage

There are currently (as of v0.3.0) several ways you can apply styles to your click app.

You apply the class to click groups or commands like so:

@click.group(
    cls=StyledGroup,
)
def cli():
    pass

Next you have several options for defining styles.

Pass named args to click.group or click.command.

@click.group(
    cls=StyledGroup,
    headers_style="green",
    options_style="yellow",
    metavar_style="red",
)
def cli():
    pass

Pass a dictionary containing the values with keys for each style:

@click.group(
    cls=StyledGroup,
    styles = {
      "headers":"green",
      "options":"yellow",
      "metavar":"red",
    }
)
def cli():
    pass

You can also provide a rich.theme.Theme and define the style itself in a separate file:

default.ini:

[styles]
headers="green"
options="yellow"
metavar="red"

@click.group(
    cls=StyledGroup,
    theme=Theme.read("default.ini")
)
def cli():
    pass

These options will be parsed in the order they are shown here. Meaning the precedence of styles is theme, styles, args.

For example the below command would have red headers.

@click.group(
    cls=StyledGroup,
    headers_style="green",
    styles={"headers":"yellow"}
    theme=Theme({"headers":"red"})
)
def cli():
    pass

In addition any string that would usually be passed to click will be parsed by rich to apply the needed colors and styles including any user defined styles.

This means you can use rich syntax in click.option() decorators as well as in docstrings of commands. For instance, you can have something like below.

@click.command(
    cls=StyledCommand,
    options_style="italic cyan",
    headers_style="bold yellow"
)
@click.option('--count', default=1, help='[red]Number[/red] of greetings.')
@click.option('--name', prompt='Your name',
              help='The person to greet.')
def hello(count, name):
    """Simple program that greets [options]NAME[/] for a total of [options]COUNT[/] times."""
    for x in range(count):
        click.echo(f"Hello {name}!")

if __name__ == '__main__':
    hello()

Lastly, there is also support for styling all doc/help strings with the doc_style attribute.

To preview the included example module in your own terminal you can use two methods:

W/o click-rich-help and w/ asciinema

asciinema play https://asciinema.org/a/iYiq7Xv2e8AgaSAMD1kEJHTkh

W/ click-rich-help and curl

curl -s https://raw.githubusercontent.com/daylinmorgan/click-rich-help/main/scripts/example.sh | bash

You can also run it yourself if you have installed click-rich-help. Which you should!

python -m click_rich_help.example -h

(back to top)

Contributing

To contribute please utilize poetry and pre-commit.

optionally manage python installation with conda:

conda create -p ./env python poetry

Then follow the below steps

1. Fork the Project
2. Install the package and dev dependencies w/poetry(cd click-rich-help; poetry install)
3. Create your Feature Branch (git checkout -b feat/AmazingFeature)
4. Commit your Changes (git commit -m 'Add some AmazingFeature')
5. Run the tests (mypy click_rich_help; py.test tests)
6. Push to the Branch (git push origin feat/AmazingFeature)
7. Open a Pull Request

(back to top)

Acknowledgments

• click
• rich
• click-help-colors

(back to top)