rich-argparse

使用rich格式化argparse和optparse的帮助。

rich-argparse通过最小程度修改代码，提升了argparse帮助的视觉效果和可读性。

目录

• 安装
• 用法
• 输出样式
  • 颜色
  • 组名
  • 突出显示模式
  • "用法"
  • 控制台标记
  • --version
  • 丰富的可渲染内容
• 子解析器
• 记录您的CLI
• 第三方格式化工具（例如：django）
• Optparse（实验性）
• 旧版Windows

安装

使用pip或您喜欢的工具从PyPI安装。

pip install rich-argparse

用法

只需将formatter_class传递给参数解析器

import argparse
from rich_argparse import RichHelpFormatter

parser = argparse.ArgumentParser(..., formatter_class=RichHelpFormatter)
...

rich-argparse定义了argparse所有内置格式化程序的等效程序

输出样式

rich-argparse 默认使用的样式经过精心挑选，可以在不同的浅色和深色主题下正常工作。

自定义颜色

您可以通过修改格式化类上的 styles 字典来自定义输出的颜色。您可以使用此处定义的任何丰富样式 （请参阅此处）。 rich-argparse 定义并使用了以下样式

{
    'argparse.args': 'cyan',  # for positional-arguments and --options (e.g "--help")
    'argparse.groups': 'dark_orange',  # for group names (e.g. "positional arguments")
    'argparse.help': 'default',  # for argument's help text (e.g. "show this help message and exit")
    'argparse.metavar': 'dark_cyan',  # for metavariables (e.g. "FILE" in "--file FILE")
    'argparse.prog': 'grey50',  # for %(prog)s in the usage (e.g. "foo" in "Usage: foo [options]")
    'argparse.syntax': 'bold',  # for highlights of back-tick quoted text (e.g. "`some text`")
    'argparse.text': 'default',  # for descriptions, epilog, and --version (e.g. "A program to foo")
    'argparse.default': 'italic',  # for %(default)s in the help (e.g. "Value" in "(default: Value)")
}

例如，要将描述和尾行设置为斜体，请更改 argparse.text 样式

RichHelpFormatter.styles["argparse.text"] = "italic"

自定义组名格式

您可以通过设置 RichHelpFormatter.group_name_formatter 来更改组名（如 '位置参数' 和 '选项'）的格式化方式，默认设置为 str.title。任何接受组名作为输入并返回字符串的可调用对象都适用

RichHelpFormatter.group_name_formatter = str.upper  # Make group names UPPERCASE

特殊文本高亮

您可以使用正则表达式在参数帮助、描述和尾行中 高亮显示模式。默认情况下，rich-argparse 使用 argparse.args 样式突出显示 --options-with-hyphens 模式，并使用 argparse.syntax 样式突出显示 `反引号引用文本` 模式。您可以通过修改 RichHelpFormatter.highlights 列表来控制突出显示的模式。要禁用所有突出显示，您可以使用 RichHelpFormatter.highlights.clear() 清空此列表。

您还可以添加自定义高亮模式和样式。以下示例将所有 pyproject.toml 发生位置突出显示为绿色

# Add a style called `pyproject` which applies a green style (any rich style works)
RichHelpFormatter.styles["argparse.pyproject"] = "green"
# Add the highlight regex (the regex group name must match an existing style name)
RichHelpFormatter.highlights.append(r"\b(?P<pyproject>pyproject\.toml)\b")
# Pass the formatter class to argparse
parser = argparse.ArgumentParser(..., formatter_class=RichHelpFormatter)
...

在 usage 中的颜色

格式化程序生成的 用法 使用 argparse.args 和 argparse.metavar 样式进行着色。如果您在解析器中使用了自定义的 usage 信息，它将被视为 "纯文本" 并默认 不 被着色。您可以通过设置 RichHelpFormatter.usage_markup = True 来启用用户定义的用法信息中的颜色。如果您启用此选项，请确保在使用文本中使用 控制台标记，并将方括号 转义。

禁用控制台标记

默认情况下，描述和尾行的文本被解释为 控制台标记。如果这与您对方括号的使用冲突，请确保将方括号 转义 或通过设置 RichHelpFormatter.text_markup = False 全局禁用标记。

类似地，参数的帮助文本默认也被解释为标记。您可以使用 RichHelpFormatter.help_markup = False 来禁用它。

在 --version 中的颜色

如果您使用了 argparse 的 "version" 操作，您可以在 version 字符串中使用控制台标记

parser.add_argument(
    "--version", action="version", version="[argparse.prog]%(prog)s[/] version [i]1.0.0[/]"
)

请注意，与描述和尾行类似，argparse.text 样式也应用于 version 字符串。

丰富的描述和尾行

您可以在描述和尾行中使用任何丰富的可渲染对象。这包括所有内置的丰富可渲染对象，如 Table 和 Markdown，以及使用 控制台协议 定义的任何自定义可渲染对象。

import argparse
from rich.markdown import Markdown
from rich_argparse import RichHelpFormatter

description = """
# My program

This is a markdown description of my program.

* It has a list
* And a table

| Column 1 | Column 2 |
| -------- | -------- |
| Value 1  | Value 2  |
"""
parser = argparse.ArgumentParser(
    description=Markdown(description, style="argparse.text"),
    formatter_class=RichHelpFormatter,
)
...

对于除字符串之外的任意可渲染对象，某些功能被 禁用，包括

• 使用 RichHelpFormatter.highlights 进行语法高亮
• 使用在 RichHelpFormatter.styles 中定义的 "argparse.text" 样式进行样式化
• 使用程序名称替换 %(prog)s

与子解析器一起工作

默认情况下，子解析器不会从父解析器继承格式化类。您必须显式传递格式化类。

subparsers = parser.add_subparsers(...)
p1 = subparsers.add_parser(..., formatter_class=parser.formatter_class)
p2 = subparsers.add_parser(..., formatter_class=parser.formatter_class)

生成帮助预览

您可以使用 HelpPreviewAction 动作以 SVG、HTML 或 TXT 格式生成 CLI 帮助消息的预览。这对于将帮助消息包含在您应用程序的文档中非常有用。该动作内部使用 rich 导出 API。

import argparse
from rich.terminal_theme import DIMMED_MONOKAI
from rich_argparse import HelpPreviewAction, RichHelpFormatter

parser = argparse.ArgumentParser(..., formatter_class=RichHelpFormatter)
...
parser.add_argument(
    "--generate-help-preview",
    action=HelpPreviewAction,
    path="help-preview.svg",  # (optional) or "help-preview.html" or "help-preview.txt"
    export_kwds={"theme": DIMMED_MONOKAI},  # (optional) keywords passed to console.save_... methods
)

此动作是隐藏的，它不会显示在帮助消息或解析的参数命名空间中。

使用方法如下

python my_cli.py --generate-help-preview  # generates help-preview.svg (default path specified above)
# or
python my_cli.py --generate-help-preview my-help.svg  # generates my-help.svg
# or
COLUMNS=120 python my_cli.py --generate-help-preview  # force the width of the output to 120 columns

与第三方格式化程序一起工作

rich-argparse 可以通过多重继承与其它自定义格式化程序一起使用。例如，django 为其内置命令、扩展库以及用户自定义命令定义了自定义帮助格式化程序。要在您的 django 项目中使用 rich-argparse，按以下方式修改您的 manage.py 文件

diff --git a/my_project/manage.py b/my_project/manage.py
index 7fb6855..5e5d48a 100755
--- a/my_project/manage.py
+++ b/my_project/manage.py
@@ -1,22 +1,38 @@
 #!/usr/bin/env python
 """Django's command-line utility for administrative tasks."""
 import os
 import sys


 def main():
     """Run administrative tasks."""
     os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'my_project.settings')
     try:
         from django.core.management import execute_from_command_line
     except ImportError as exc:
         raise ImportError(
             "Couldn't import Django. Are you sure it's installed and "
             "available on your PYTHONPATH environment variable? Did you "
             "forget to activate a virtual environment?"
         ) from exc
+
+    from django.core.management.base import BaseCommand, DjangoHelpFormatter
+    from rich_argparse import RichHelpFormatter
+
+    class DjangoRichHelpFormatter(DjangoHelpFormatter, RichHelpFormatter):  # django first
+        """A rich-based help formatter for django commands."""
+
+    original_create_parser = BaseCommand.create_parser
+
+    def create_parser(*args, **kwargs):
+        parser = original_create_parser(*args, **kwargs)
+        parser.formatter_class = DjangoRichHelpFormatter  # set the formatter_class
+        return parser
+
+    BaseCommand.create_parser = create_parser
+
     execute_from_command_line(sys.argv)


 if __name__ == '__main__':
     main()

现在，所有 python manage.py <COMMAND> --help 的输出都将被着色。

Optparse 支持

rich-argparse 现在提供了对 optparse 的实验性支持。

从 rich_argparse.optparse 导入 optparse 帮助格式化程序

import optparse
from rich_argparse.optparse import IndentedRichHelpFormatter  # or TitledRichHelpFormatter

parser = optparse.OptionParser(formatter=IndentedRichHelpFormatter())
...

您还可以通过将 usage=GENERATE_USAGE 传递给解析器来生成更详细的用法消息。这与 argparse 的默认行为类似。

from rich_argparse.optparse import GENERATE_USAGE, IndentedRichHelpFormatter

parser = optparse.OptionParser(usage=GENERATE_USAGE, formatter=IndentedRichHelpFormatter())

类似于 argparse，您可以通过修改 RichHelpFormatter.styles 字典来自定义格式化程序使用的样式。这些样式与 argparse 中使用的是相同的，但以 optparse. 前缀代替

RichHelpFormatter.styles["optparse.metavar"] = "bold magenta"

语法高亮与 argparse 的工作方式相同。

当使用 GENERATE_USAGE 时，仅支持在 usage 中使用颜色。

旧版 Windows 支持

在旧版 Windows 版本（如 Windows 7）上使用时，除非使用 colorama，否则颜色将关闭。

import argparse
import colorama
from rich_argparse import RichHelpFormatter

colorama.init()
parser = argparse.ArgumentParser(..., formatter_class=RichHelpFormatter)
...