cligen

cligen是一个用于生成命令行解析代码的实用程序，从YAML规范中编写您的__main__.py。生成的代码需要Python 3.8+。

对于需要子命令left和right的命令行工具direction，其中子命令left可以具有选项--u-turn（假设您在道路的右侧驾驶），并且两个子命令都可以有--verbose选项，其外观将如下所示

!Cli 0:
- !Instance driving.Direction
- !Option [verbose, v, !Help increase verbosity level, !Action count]
- left:
  - !Help turning to the left
  - !Option [u-turn, U, !Type bool, !Help make a U-turn]
- right:
  - !H turning to the right

结果将是，当使用direction left -h时将显示

usage: direction left [-h] [--u-turn] [--verbose]

optional arguments:
  -h, --help     show this help message and exit
  --u-turn, -U   make a U-turn
  --verbose, -v  increase verbosity level

当从命令行调用direction left时，__main__.py中的代码将创建一个从driving.py导入的Direction类的实例，并将解析结果作为参数传递给初始化，然后调用该类的left_subcommand或方法left（按此顺序尝试）。cligen可以生成调用从Python文件导入的函数的代码，或者调用从YAML规范插入到__main__.py本身的代码（在这种情况下，不尝试..._subcommand，将解析的结果传递给函数）。

YAML 文档可以单独存放在文件 cli.yaml 中，或者，如果您想减少项目根目录的文件杂乱，它也可以存储在 __init__.py 中的变量 _cligen_data 中，这意味着在该文件中的以下两行之间

_cligen_data = """\
"""

YAML 文档使用各种标签，其中许多都有一个简写版本（例如，!H 等同于使用 !Help）。

将命令行选项和参数数据存储在类似于 YAML 的可编程可修改的格式中，使得检查或操作所有实用程序变得更加容易。例如，如果您想确保所有具有 --verbose 选项的实用程序也具有一个降低详细程度的 --quiet 选项。

功能列表

• 多个长选项（--date）和短选项（-D）可以与一个目标相关联。

• 额外的智能类型/操作。例如，类型为 'date' 的选项默认为 datetime.date.today()，您还可以指定类似 yesterday 或 -w-2（两周前）的参数。

• 默认值，其中可选地更新了来自配置文件（YAML/INI/PON）的一些默认值。

• 嵌套解析器用于子命令，子命令从其父命令继承选项。这允许您在子命令之前或之后插入父选项，而无需重新排列命令行。

• 可选默认子命令/解析器，用于处理未知选项/参数。

• 可选缩写形式，以替代可执行名称的形式出现，用于常用子命令和/或选项字符串。

• 除了 Python 标准库之外，没有任何依赖项，除非您的配置文件格式需要安装某些库（YAML -> ruamel.yaml）

• 允许使用 YAML 别名作为标签的标量值被其他标签使用

  - !Help &xhelp text1 text2 text3  # this is the same as: "&xhelp !Help text1 text2 text3"
  - !Prolog [*xhelp]                # xhelp is a tagged scalar, "!Prolog *xhelp" would error
                                    # the value for !Prolog is automatically un-sequenced
  

使用 !Config

在其最明确的形式中，标签 !Config 可以接受一个包含两个元素的序列作为值。第一个元素表示 类型（pon、yaml、ini、TBI: json），第二个表示文件的 路径。以波浪号（~）开头的路径将被展开。不以波浪号或（正）斜杠（/）开头的路径将被附加到您的用户配置目录。

如果 !Config 后跟一个看起来像路径的标量（即值的开始是 ~ 或包含一个 /），则该路径的扩展名被视为 类型。在其他情况下，假定 !Config 后跟一个 类型，基名是从包名称（_package_data['full_package_name']）派生的，在您的用户配置目录中。

用户配置目录基于 XDG 配置位置（在 Windows 上，配置信息预计在 %APPDATA% 下）

当指定 !Config 时，插入的代码将在命令行上检查 --config some_explicit_path 并从指定的路径加载配置数据。

配置文件格式

假设配置文件包含根级别的字典（对于类似 .ini 的格式，数据在加载期间转换为字典）。该字典包含与各种子解析器对应的键。一个 global 部分（或可选地，PON 中的 glbl 以防止使用保留关键字，在加载后重命名为 global），用于设置在子解析器之前出现的选项以及全局选项的默认值。每个部分由键值对组成，其中键对应于长选项（--verbose）或如果该选项不可用，则对应于短选项（-v），不带有前导破折号。

假设您有以下配置

!Cli 0:
- !Opt [verbose, v, !H increase verbosity, !Action count]
- !Config [pon, /usr/local/etc/myutil.pon]
- subp1: []

您的 myutil.pon 可以使用

dict(glbl=dict(verbose=2))

来设置详细程度（您可能想以更美观的方式格式化您的 PON）。

同样的，使用 YAML 文件

!Cli 0:
- !Opt [verbose, v, !H increase verbosity, !Action count]
- !Config YAML
- subp1: []

您的 ~/.config/your_util_name/your_util_name.yaml 将会是

global:
  verbose: 2

argparse

早期版本的cligen在__main__.py文件中生成argparse命令。当前的Python输出不再使用argparse，导致代码大小大约增加了两倍，但速度也提高了两倍。

可以通过提供--type argparse来调用旧的、不再维护的代码生成器。