{"id":32139213,"url":"https://github.com/hamdanal/rich-argparse","last_synced_at":"2026-02-21T10:32:02.247Z","repository":{"id":39167200,"uuid":"496777561","full_name":"hamdanal/rich-argparse","owner":"hamdanal","description":"A rich help formatter for argparse","archived":false,"fork":false,"pushed_at":"2026-01-25T10:47:11.000Z","size":329,"stargazers_count":191,"open_issues_count":3,"forks_count":15,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-26T01:16:37.532Z","etag":null,"topics":["argparse","cli","click","optparse","python","rich","rich-argparse","syntax-highlighting","typer"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/rich-argparse/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hamdanal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-05-26T21:31:58.000Z","updated_at":"2026-01-25T10:47:13.000Z","dependencies_parsed_at":"2023-10-15T09:16:19.861Z","dependency_job_id":"e2451c5a-935c-4432-869a-8495ea8dcb03","html_url":"https://github.com/hamdanal/rich-argparse","commit_stats":{"total_commits":155,"total_committers":9,"mean_commits":17.22222222222222,"dds":"0.19999999999999996","last_synced_commit":"8c2c2cf861cfacfdd8a25384870c8a7ec9e02f9f"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/hamdanal/rich-argparse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamdanal%2Frich-argparse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamdanal%2Frich-argparse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamdanal%2Frich-argparse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamdanal%2Frich-argparse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hamdanal","download_url":"https://codeload.github.com/hamdanal/rich-argparse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamdanal%2Frich-argparse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29679049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T09:33:50.764Z","status":"ssl_error","status_checked_at":"2026-02-21T09:33:19.949Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argparse","cli","click","optparse","python","rich","rich-argparse","syntax-highlighting","typer"],"created_at":"2025-10-21T05:30:22.625Z","updated_at":"2026-02-21T10:32:02.242Z","avatar_url":"https://github.com/hamdanal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rich-argparse\n\n![python -m rich_argparse](\nhttps://github.com/hamdanal/rich-argparse/assets/93259987/5eb719ce-9865-4654-a5c6-04950a86d40d)\n\n[![tests](https://github.com/hamdanal/rich-argparse/actions/workflows/tests.yml/badge.svg)\n](https://github.com/hamdanal/rich-argparse/actions/workflows/tests.yml)\n[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/hamdanal/rich-argparse/main.svg)\n](https://results.pre-commit.ci/latest/github/hamdanal/rich-argparse/main)\n[![Downloads](https://img.shields.io/pypi/dm/rich-argparse)](https://pypistats.org/packages/rich-argparse)\n[![Python Version](https://img.shields.io/pypi/pyversions/rich-argparse)\n![Release](https://img.shields.io/pypi/v/rich-argparse)\n](https://pypi.org/project/rich-argparse/)\n\nFormat argparse and optparse help using [rich](https://pypi.org/project/rich).\n\n*rich-argparse* improves the look and readability of argparse's help while requiring minimal\nchanges to the code.\n\n## Table of contents\n\n* [Installation](#installation)\n* [Usage](#usage)\n* [Output styles](#output-styles)\n  * [Customizing colors](#customize-the-colors)\n  * [Group name formatting](#customize-the-group-name-format)\n  * [Special text highlighting](#special-text-highlighting)\n  * [Customizing `usage`](#colors-in-the-usage)\n  * [Console markup](#disable-console-markup)\n  * [Colors in `--version`](#colors-in---version)\n  * [Rich renderables](#rich-descriptions-and-epilog)\n* [Working with subparsers](#working-with-subparsers)\n* [Documenting your CLI](#generate-help-preview)\n* [Additional formatters](#additional-formatters)\n* [Django support](#django-support)\n* [Optparse support](#optparse-support) (experimental)\n* [Legacy Windows](#legacy-windows-support)\n\n## Installation\n\nInstall from PyPI with pip or your favorite tool.\n\n```sh\npip install rich-argparse\n```\n\n## Usage\n\nSimply pass `formatter_class` to the argument parser\n```python\nimport argparse\nfrom rich_argparse import RichHelpFormatter\n\nparser = argparse.ArgumentParser(..., formatter_class=RichHelpFormatter)\n...\n```\n\n*rich-argparse* defines equivalents to all [argparse's standard formatters](\nhttps://docs.python.org/3/library/argparse.html#formatter-class):\n\n| `rich_argparse` formatter           | equivalent in `argparse`        |\n|-------------------------------------|---------------------------------|\n| `RichHelpFormatter`                 | `HelpFormatter`                 |\n| `RawDescriptionRichHelpFormatter`   | `RawDescriptionHelpFormatter`   |\n| `RawTextRichHelpFormatter`          | `RawTextHelpFormatter`          |\n| `ArgumentDefaultsRichHelpFormatter` | `ArgumentDefaultsHelpFormatter` |\n| `MetavarTypeRichHelpFormatter`      | `MetavarTypeHelpFormatter`      |\n\nAdditional formatters are available in the `rich_argparse.contrib` [module](#additional-formatters).\n\n## Output styles\n\nThe default styles used by *rich-argparse* are carefully chosen to work in different light and dark\nthemes.\n\n### Customize the colors\n\nYou can customize the colors of the output by modifying the `styles` dictionary on the formatter\nclass. You can use any rich style as defined [here](https://rich.readthedocs.io/en/latest/style.html).\n*rich-argparse* defines and uses the following styles:\n\n```python\n{\n    'argparse.args': 'cyan',  # for positional-arguments and --options (e.g \"--help\")\n    'argparse.groups': 'dark_orange',  # for group names (e.g. \"positional arguments\")\n    'argparse.help': 'default',  # for argument's help text (e.g. \"show this help message and exit\")\n    'argparse.metavar': 'dark_cyan',  # for metavariables (e.g. \"FILE\" in \"--file FILE\")\n    'argparse.prog': 'grey50',  # for %(prog)s in the usage (e.g. \"foo\" in \"Usage: foo [options]\")\n    'argparse.syntax': 'bold',  # for highlights of back-tick quoted text (e.g. \"`some text`\")\n    'argparse.text': 'default',  # for descriptions, epilog, and --version (e.g. \"A program to foo\")\n    'argparse.default': 'italic',  # for %(default)s in the help (e.g. \"Value\" in \"(default: Value)\")\n}\n```\n\nFor example, to make the description and epilog *italic*, change the `argparse.text` style:\n\n```python\nRichHelpFormatter.styles[\"argparse.text\"] = \"italic\"\n```\n\n### Customize the group name format\n\nYou can change how the names of the groups (like `'positional arguments'` and `'options'`) are\nformatted by setting the `RichHelpFormatter.group_name_formatter` which is set to `str.title` by\ndefault. Any callable that takes the group name as an input and returns a str works:\n\n```python\nRichHelpFormatter.group_name_formatter = str.upper  # Make group names UPPERCASE\n```\n\n### Special text highlighting\n\nYou can [highlight patterns](https://rich.readthedocs.io/en/stable/highlighting.html) in the\narguments help and the description and epilog using regular expressions. By default,\n*rich-argparse* highlights patterns of `--options-with-hyphens` using the `argparse.args` style\nand patterns of `` `back tick quoted text` `` using the `argparse.syntax` style. You can control\nwhat patterns are highlighted by modifying the `RichHelpFormatter.highlights` list. To disable all\nhighlights, you can clear this list using `RichHelpFormatter.highlights.clear()`.\n\nYou can also add custom highlight patterns and styles. The following example highlights all\noccurrences of `pyproject.toml` in green:\n\n```python\n# Add a style called `pyproject` which applies a green style (any rich style works)\nRichHelpFormatter.styles[\"argparse.pyproject\"] = \"green\"\n# Add the highlight regex (the regex group name must match an existing style name)\nRichHelpFormatter.highlights.append(r\"\\b(?P\u003cpyproject\u003epyproject\\.toml)\\b\")\n# Pass the formatter class to argparse\nparser = argparse.ArgumentParser(..., formatter_class=RichHelpFormatter)\n...\n```\n\n### Colors in the `usage`\n\nThe usage **generated by the formatter** is colored using the `argparse.args` and `argparse.metavar`\nstyles. If you use a custom `usage` message in the parser, it will be treated as \"plain text\" and\nwill **not** be colored by default. You can enable colors in user defined usage message through\n[console markup](https://rich.readthedocs.io/en/stable/markup.html) by setting\n`RichHelpFormatter.usage_markup = True`. If you enable this option, make sure to [escape](\nhttps://rich.readthedocs.io/en/stable/markup.html#escaping) any square brackets in the usage text.\n\n### Disable console markup\n\nThe text of the descriptions and epilog is interpreted as\n[console markup](https://rich.readthedocs.io/en/stable/markup.html) by default. If this conflicts\nwith your usage of square brackets, make sure to [escape](\nhttps://rich.readthedocs.io/en/stable/markup.html#escaping) the square brackets or to disable\nmarkup globally with `RichHelpFormatter.text_markup = False`.\n\nSimilarly the help text of arguments is interpreted as markup by default. It can be disabled using\n`RichHelpFormatter.help_markup = False`.\n\n### Colors in `--version`\n\nIf you use the `\"version\"` action from argparse, you can use console markup in the `version` string:\n\n```python\nparser.add_argument(\n    \"--version\", action=\"version\", version=\"[argparse.prog]%(prog)s[/] version [i]1.0.0[/]\"\n)\n```\n\nNote that the `argparse.text` style is applied to the `version` string similar to the description\nand epilog.\n\n### Rich descriptions and epilog\n\nYou can use any rich renderable in the descriptions and epilog. This includes all built-in rich\nrenderables like `Table` and `Markdown` and any custom renderables defined using the\n[Console Protocol](https://rich.readthedocs.io/en/stable/protocol.html#console-protocol).\n\n```python\nimport argparse\nfrom rich.markdown import Markdown\nfrom rich_argparse import RichHelpFormatter\n\ndescription = \"\"\"\n# My program\n\nThis is a markdown description of my program.\n\n* It has a list\n* And a table\n\n| Column 1 | Column 2 |\n| -------- | -------- |\n| Value 1  | Value 2  |\n\"\"\"\nparser = argparse.ArgumentParser(\n    description=Markdown(description, style=\"argparse.text\"),\n    formatter_class=RichHelpFormatter,\n)\n...\n```\nCertain features are **disabled** for arbitrary renderables other than strings, including:\n\n* Syntax highlighting with `RichHelpFormatter.highlights`\n* Styling with the `\"argparse.text\"` style defined in `RichHelpFormatter.styles`\n* Replacement of `%(prog)s` with the program name\n\n## Working with subparsers\n\nSubparsers do not inherit the formatter class from the parent parser by default. You have to pass\nthe formatter class explicitly:\n\n```python\nsubparsers = parser.add_subparsers(...)\np1 = subparsers.add_parser(..., formatter_class=parser.formatter_class)\np2 = subparsers.add_parser(..., formatter_class=parser.formatter_class)\n```\n\n## Generate help preview\n\nYou can generate a preview of the help message for your CLI in SVG, HTML, or TXT formats using the\n`HelpPreviewAction` action. This is useful for including the help message in the documentation of\nyour app. The action uses the\n[rich exporting API](https://rich.readthedocs.io/en/stable/console.html#exporting) internally.\n\n```python\nimport argparse\nfrom rich.terminal_theme import DIMMED_MONOKAI\nfrom rich_argparse import HelpPreviewAction, RichHelpFormatter\n\nparser = argparse.ArgumentParser(..., formatter_class=RichHelpFormatter)\n...\nparser.add_argument(\n    \"--generate-help-preview\",\n    action=HelpPreviewAction,\n    path=\"help-preview.svg\",  # (optional) or \"help-preview.html\" or \"help-preview.txt\"\n    export_kwds={\"theme\": DIMMED_MONOKAI},  # (optional) keywords passed to console.save_... methods\n)\n```\nThis action is hidden, it won't show up in the help message or in the parsed arguments namespace.\n\nUse it like this:\n\n```sh\npython my_cli.py --generate-help-preview  # generates help-preview.svg (default path specified above)\n# or\npython my_cli.py --generate-help-preview my-help.svg  # generates my-help.svg\n# or\nCOLUMNS=120 python my_cli.py --generate-help-preview  # force the width of the output to 120 columns\n```\n\n## Additional formatters\n\n*rich-argparse* defines additional non-standard argparse formatters for some common use cases in\nthe `rich_argparse.contrib` module. They can be imported with the `from rich_argparse.contrib import`\nsyntax. The following formatters are available:\n\n* `ParagraphRichHelpFormatter`: A formatter similar to `RichHelpFormatter` that preserves paragraph\n  breaks. A paragraph break is defined as two consecutive newlines (`\\n\\n`) in the help or\n  description text. Leading and trailing trailing whitespace are stripped similar to\n  `RichHelpFormatter`.\n\n_More formatters will be added in the future._\n\n## Django support\n\n*rich-argparse* provides support for django's custom help formatter. You can instruct django to use\n*rich-argparse* with all built-in, extension libraries, and user defined commands in a django\nproject by adding these two lines to the `manage.py` file:\n\n```diff\ndiff --git a/manage.py b/manage.py\n def main():\n     \"\"\"Run administrative tasks.\"\"\"\n     os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'my_project.settings')\n     try:\n         from django.core.management import execute_from_command_line\n     except ImportError as exc:\n         raise ImportError(\n             \"Couldn't import Django. Are you sure it's installed and \"\n             \"available on your PYTHONPATH environment variable? Did you \"\n             \"forget to activate a virtual environment?\"\n         ) from exc\n+    from rich_argparse.django import richify_command_line_help\n+    richify_command_line_help()\n     execute_from_command_line(sys.argv)\n```\n\nAlternatively, you can use the `DjangoRichHelpFormatter` class directly in your commands:\n\n```diff\ndiff --git a/my_app/management/commands/my_command.py b/my_app/management/commands/my_command.py\n from django.core.management.base import BaseCommand\n+from rich_argparse.django import DjangoRichHelpFormatter\n\n class Command(BaseCommand):\n     def add_arguments(self, parser):\n+        parser.formatter_class = DjangoRichHelpFormatter\n         parser.add_argument(\"--option\", action=\"store_true\", help=\"An option\")\n         ...\n```\n\n## Optparse support\n\n*rich-argparse* now ships with experimental support for [optparse](\nhttps://docs.python.org/3/library/optparse.html).\n\nImport optparse help formatters from `rich_argparse.optparse`:\n\n```python\nimport optparse\nfrom rich_argparse.optparse import IndentedRichHelpFormatter  # or TitledRichHelpFormatter\n\nparser = optparse.OptionParser(formatter=IndentedRichHelpFormatter())\n...\n```\n\nYou can also generate a more helpful usage message by passing `usage=GENERATE_USAGE` to the\nparser. This is similar to the default behavior of `argparse`.\n\n```python\nfrom rich_argparse.optparse import GENERATE_USAGE, IndentedRichHelpFormatter\n\nparser = optparse.OptionParser(usage=GENERATE_USAGE, formatter=IndentedRichHelpFormatter())\n```\n\nSimilar to `argparse`, you can customize the styles used by the formatter by modifying the\n`RichHelpFormatter.styles` dictionary. These are the same styles used by `argparse` but with\nthe `optparse.` prefix instead:\n\n```python\nRichHelpFormatter.styles[\"optparse.metavar\"] = \"bold magenta\"\n```\n\nSyntax highlighting works the same as with `argparse`.\n\nColors in the `usage` are only supported when using `GENERATE_USAGE`.\n\n## Legacy Windows support\n\nWhen used on legacy Windows versions like *Windows 7*, colors are disabled unless\n[colorama](https://pypi.org/project/colorama/) is used:\n\n```python\nimport argparse\nimport colorama\nfrom rich_argparse import RichHelpFormatter\n\ncolorama.init()\nparser = argparse.ArgumentParser(..., formatter_class=RichHelpFormatter)\n...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamdanal%2Frich-argparse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhamdanal%2Frich-argparse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamdanal%2Frich-argparse/lists"}