diff options
Diffstat (limited to 'venv/lib/python3.11/site-packages/rich_click-1.7.4.dist-info/METADATA')
| -rw-r--r-- | venv/lib/python3.11/site-packages/rich_click-1.7.4.dist-info/METADATA | 633 |
1 files changed, 633 insertions, 0 deletions
diff --git a/venv/lib/python3.11/site-packages/rich_click-1.7.4.dist-info/METADATA b/venv/lib/python3.11/site-packages/rich_click-1.7.4.dist-info/METADATA new file mode 100644 index 0000000..13b442a --- /dev/null +++ b/venv/lib/python3.11/site-packages/rich_click-1.7.4.dist-info/METADATA @@ -0,0 +1,633 @@ +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' + +<p align="center"> + <picture> + <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ewels/rich-click/main/docs/images/rich-click-logo-darkmode.png"> + <img alt="rich-click logo" src="https://raw.githubusercontent.com/ewels/rich-click/main/docs/images/rich-click-logo.png"> + </picture> +</p> +<p align="center"> + <em>Richly rendered command line interfaces in click.</em> +</p> +<p align="center"> + <img src="https://github.com/ewels/rich-click/workflows/Test%20Coverage/badge.svg" alt="Test Coverage badge"> + <img src="https://github.com/ewels/rich-click/workflows/Lint%20code/badge.svg" alt="Lint code badge"> +</p> + +--- + +**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: + +<!-- RICH-CODEX +extra_env: + TERMINAL_WIDTH: 160 +--> + + + +> 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). |