make a beautiful click app with rich
Project description
Table of Contents
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
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
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
- Fork the Project
- Install the package and dev dependencies w/poetry(
cd click-rich-help; poetry install
) - Create your Feature Branch (
git checkout -b feat/AmazingFeature
) - Commit your Changes (
git commit -m 'Add some AmazingFeature'
) - Run the tests (
mypy click_rich_help; py.test tests
) - Push to the Branch (
git push origin feat/AmazingFeature
) - Open a Pull Request
Acknowledgments
Project details
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 click_rich_help-0.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6eeb8d1c74d7ca09e7c5132296ce6ec9bd14ef1cd2531d87955fdf3a83990c82 |
|
MD5 | 0d721e053501ae20fc88dc440ee72cd0 |
|
BLAKE2b-256 | acba74cc0ade14ebb15e98df675a1f94bbe036faf112f5b44b72e0b8b013cd8d |