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, 0 insertions, 633 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 deleted file mode 100644 index 13b442a..0000000 --- a/venv/lib/python3.11/site-packages/rich_click-1.7.4.dist-info/METADATA +++ /dev/null @@ -1,633 +0,0 @@ -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). |