click-rich-help 0.2.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

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

(back to top)

Built With

• click
• rich

(back to top)

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

The syntax for usage is not much different than click-help-colors on which this project is based.

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

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

Note that the general context has changed from help colors to help styles. This was intentionally changed to reflect the addition of other ANSII styles, i.e. bold, italic.

This isn't the only significant change though! Now there is also support for coloring metavars. If no color is specified than they will default to the color of the options.

In addition any string that would usually be passed to click will be parsed by rich to apply the needed colors and 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.

import click
from click_rich_help import StyledCommand

@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 [b yellow]NAME[/b yellow] for a total of [b yellow]COUNT[/b yellow] times."""
    for x in range(count):
        click.echo(f"Hello {name}!")

if __name__ == '__main__':
    hello()

If you were to view the --help of the above command you should see the below output.

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/81psoVhEc6F568fZppb6qKBVb

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 -n rich_dev python=3.7 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. Push to the Branch (git push origin feat/AmazingFeature)
6. Open a Pull Request

(back to top)

Roadmap

• Integrated example module
• Implement Type checking
• Add option to color all help strings
• CI
  • test
  • pypi

Contact

Daylin Morgan - @tweetsbydaylin

Project Link: https://github.com/daylinmorgan/click-rich-help

(back to top)

Acknowledgments

• click
• rich
• click-help-colors

(back to top)