Jazzband维护的docopt分支，人性化的命令行参数解析器。
项目描述
docopt-ng 创建 美观 的命令行界面
docopt-ng 是 原始docopt 的分支，现在由 jazzband 项目维护。现在具有维护、类型提示和完整的测试覆盖率！
docopt-ng 帮助您创建美观的命令行界面
"""Naval Fate.
Usage:
naval_fate.py ship new <name>...
naval_fate.py ship <name> move <x> <y> [--speed=<kn>]
naval_fate.py ship shoot <x> <y>
naval_fate.py mine (set|remove) <x> <y> [--moored | --drifting]
naval_fate.py (-h | --help)
naval_fate.py --version
Options:
-h --help Show this screen.
--version Show version.
--speed=<kn> Speed in knots [default: 10].
--moored Moored (anchored) mine.
--drifting Drifting mine.
"""
from docopt import docopt
if __name__ == "__main__":
argv = ["ship", "Guardian", "move", "100", "150", "--speed=15"]
arguments = docopt(__doc__, argv)
print(arguments)
结果如下
{'--drifting': False,
'--help': False,
'--moored': False,
'--speed': '15',
'--version': False,
'<name>': ['Guardian'],
'<x>': '100',
'<y>': '150',
'mine': False,
'move': True,
'new': False,
'remove': False,
'set': False,
'ship': True,
'shoot': False}
Beat that！选项解析器是根据传递给 docopt 函数的上述文档字符串生成的。 docopt 解析使用模式（"Usage: ..."）和选项描述（以短横线 "-" 开头的行）并确保程序调用与使用模式匹配；它根据这些解析选项、参数和命令。基本思想是，一个好的帮助信息应包含所有必要信息以生成解析器。
此外，PEP 257 建议在模块文档字符串中放置帮助信息。
安装
使用 pip
python -m pip install docopt-ng
docopt-ng 已经与 Python 3.7+ 进行了测试。
API
def docopt(
docstring: str,
argv: list[str] | str | None = None,
default_help: bool = True,
version: Any = None,
options_first: bool = False,
) -> ParsedOptions:
docopt 接受一个文档字符串和 4 个可选参数
-
docstring是一个包含用于创建选项解析器的 帮助信息 的字符串。如何编写此类帮助信息的简单规则将在下一节中给出。通常，您只需使用__doc__。 -
argv是一个可选的参数向量；默认情况下，docopt使用传递给您的程序的参数向量（sys.argv[1:]）。或者，您可以提供一个字符串列表，例如["--verbose", "-o", "hai.txt"]，或者一个单独的字符串，该字符串将在空格处分割，例如"--verbose -o hai.txt"。 -
default_help，默认值为True，指定解析器是否在遇到-h或--help选项时自动打印帮助信息（作为doc提供）并终止。如果您想像其他选项一样手动处理-h或--help选项，请将help=False。 -
version，默认值为None，是一个可选参数，用于指定您程序的版本。如果提供，那么，假设在用法模式中提到了--version选项，当解析器遇到--version选项时，它将打印提供的版本并终止。version可以是任何可打印的对象，但最可能是字符串，例如"2.1.0rc1"。注意，当
docopt设置为自动处理-h、--help和--version选项时，您仍然需要在用法模式中提到它们，以便正常工作。另外，为了让您的用户了解它们。 -
options_first，默认值为False。如果设置为True，则不允许混合选项和位置参数。也就是说，在第一个位置参数之后，所有参数都将被解释为位置参数，即使它们看起来像选项。这可以用于与 POSIX 的严格兼容性，或者如果您想将您的参数调度到其他程序。
返回值是一个简单的字典，以选项、参数和命令作为键，拼写与您的帮助信息中完全一样。优先考虑选项的长版本。此外，支持点表示法，忽略前面的连字符（-）和周围的括号（<>），例如 arguments.drifting 或 arguments.x。
帮助信息格式
帮助信息由 2 部分组成
-
用法模式，例如
Usage: my_program.py [-hso FILE] [--quiet | --verbose] [INPUT ...] -
选项描述，例如
-h --help show this -s --sorted sorted output -o FILE specify output file [default: ./test.txt] --quiet print less text --verbose print more text
它们的格式将在下面进行说明；其他文本将被忽略。
用法模式格式
用法模式 是从 doc 开始的子字符串，以 usage:（不区分大小写）开头，并以一个 可见的 空行结束。最小示例
"""Usage: my_program.py
"""
在 usage: 之后的第一词被解释为您的程序名称。您可以通过指定您的程序名称多次来表示多个互斥模式
"""Usage: my_program.py FILE
my_program.py COUNT FILE
"""
每个模式可以由以下元素组成
- <arguments>、ARGUMENTS。参数指定为全部大写的单词，例如
my_program.py CONTENT-PATH或用尖括号包围的单词：my_program.py <content-path>。 - --options。选项是以连字符（
-）开头的单词，例如--output、-o。您可以堆叠多个单字母选项，例如-oiv，它将与-o -i -v相同。选项可以有参数，例如--input=FILE或-i FILE或甚至-iFILE。但是，如果您想使您的选项具有参数、默认值或指定选项的简称/长称（参见下一节关于选项描述），则必须指定选项描述。 - 命令是指不符合上述
--options或<arguments>或ARGUMENTS约定的单词，包括两个特殊命令：短横线-和双短横线--（见下文）。
使用以下结构来指定模式
- [ ]（括号）表示可选元素。例如：
my_program.py [-hvqo FILE] - ( )（括号）表示必需元素。所有没有放在[ ]中的元素也是必需的，例如：
my_program.py --path=<path> <file>...与my_program.py (--path=<path> <file>...)相同。（注意，“必需选项”可能不是为用户着想的好主意）。 - |（管道）表示互斥元素。如果其中一个互斥元素是必需的，请使用( )将它们分组：
my_program.py (--clockwise | --counter-clockwise) TIME。如果所有互斥元素都不是必需的，请使用[ ]将它们分组：my_program.py [--left | --right]。 - ...（省略号）表示一个或多个元素。为了指定可以接受任意数量的重复元素，请使用省略号（
...），例如：my_program.py FILE ...表示可以接受一个或多个FILE。如果您想接受零个或多个元素，请使用括号，例如：my_program.py [FILE ...]。省略号在表达式的左侧作为一元运算符。 - [options]（区分大小写）是任何选项的快捷方式。如果您想指定使用模式可以提供下面定义的任何选项，而不想在用法模式中列出所有选项，则可以使用它。
- "
[--]"。双短横线--传统上用于分隔可能被误认为是选项的位置参数。为了支持此约定，请在用法模式中添加"[--]"。 - "
[-]"。单短横线-传统上用于表示使用stdin而不是文件。为了支持此功能，请将"[-]"添加到您的用法模式中。"-"作为一个正常命令。
如果您的模式允许匹配无参数选项（标志）多次
Usage: my_program.py [-v | -vv | -vvv]
则选项出现的次数将被计数。也就是说，如果程序以my_program -vv的方式调用，则args["-v"]将为2。同样适用于命令。
如果您的用法模式允许匹配具有参数或位置参数的同名选项多次，则匹配的参数将被收集到一个列表中
Usage: my_program.py <file> <file> --path=<path>...
也就是说，以my_program.py file1 file2 --path=./here --path=./there的方式调用，返回的字典将包含args["<file>"] == ["file1", "file2"]和args["--path"] == ["./here", "./there"]。
选项描述格式
选项描述是一系列选项，您将其放在用法模式下方。
列出选项描述是必要的，以便指定
- 同义词简写和长选项
- 如果选项有一个参数
- 如果选项的参数有一个默认值
规则如下
-
在
doc中以-或--（不计空格）开头的每一行都被视为选项描述，例如Options: --verbose # GOOD -o FILE # GOOD Other: --bad # BAD, line does not start with dash "-" -
要指定选项有一个参数，请在空格（或等于
=符号）之后放置描述该参数的单词，如下所示。遵循<angular-brackets>或大写字母约定来表示选项参数。如果您想分隔选项，可以使用逗号。下面的两行都是有效的，但是建议您坚持使用单一的风格。-o FILE --output=FILE # without comma, with "=" sign -i <file>, --input <file> # with comma, without "=" sign -
使用两个空格来分隔选项及其非正式描述
--verbose More text. # BAD, will be treated as if verbose option had # an argument "More", so use 2 spaces instead -q Quit. # GOOD -o FILE Output file. # GOOD --stdout Use stdout. # GOOD, 2 spaces -
如果您想为具有参数的选项设置默认值，请将其放入选项描述中，形式为
[default: <my-default-value>]--coefficient=K The K coefficient [default: 2.95] --output=FILE Output file [default: test.txt] --directory=DIR Some directory [default: ./] -
如果选项不可重复，则
[默认: ...]内的值将被解释为字符串。如果是可重复的，它将被分割成一个基于空白符的列表。Usage: my_program.py [--repeatable=<arg> --repeatable=<arg>] [--another-repeatable=<arg>]... [--not-repeatable=<arg>] # will be ["./here", "./there"] --repeatable=<arg> [default: ./here ./there] # will be ["./here"] --another-repeatable=<arg> [default: ./here] # will be "./here ./there", because it is not repeatable --not-repeatable=<arg> [default: ./here ./there]
示例
我们有一个详尽的示例列表，涵盖了docopt-ng功能的各个方面。[示例链接](https://github.com/jazzband/docopt-ng/tree/master/examples)。尝试使用它们，如果有疑问，请阅读源代码。
开发
我们非常愿意听取您对我们docopt-ng的看法。[问题页面](https://github.com/jazzband/docopt-ng/issues)。提交拉取请求，报告错误，并提出建议。
要设置您的开发环境，请将此存储库Fork并本地克隆它。我们使用pdm来管理项目，因此首先安装它。
然后安装开发依赖项和包本身作为可编辑的，然后安装预提交钩子
pdm sync -d -G dev
pdm run pre-commit install
有用的测试、代码审查和格式化命令
pdm run pytest
pdm run black .
pdm run ruff .
下载文件
下载您平台上的文件。如果您不确定选择哪一个，请了解有关安装包的更多信息。