Pythonic参数解析器，让你微笑
项目描述
docopt 创建 漂亮的 命令行界面
关于 docopt 的视频介绍： PyCon UK 2012：用Python创建 *漂亮的* 命令行界面
0.6.1版本中的新特性
修复问题 #85，该问题导致当[options]快捷方式出现多次时处理不当。
0.6.0版本中的新特性
新参数 options_first，不允许选项和参数交错。如果您将 options_first=True 传递给 docopt，它将在第一个位置参数之后将所有参数解释为位置参数。
如果带有参数的选项可以重复，其默认值将解释为空格分隔的列表。例如，带有 [默认：./here ./there] 将解释为 ['./here', './there']。
破坏性更改
[options]快捷方式的含义略有变化。以前它意味着 “任何已知选项”。现在它意味着 “不在用法模式中的任何选项”。这避免了选项无意中重复允许的情况。
默认情况下，argv 是 None，而不是 sys.argv[1:]。这允许 docopt 总是使用最新的 sys.argv，而不是导入时的 sys.argv。
不是吗？optparse 和 argparse 基于您的代码生成帮助信息真是太棒了！
绝对不是！ 您知道什么才是最棒的吗？当选项解析器是基于您自己编写的漂亮的帮助信息生成的时！这样您就不需要编写这种愚蠢的重复性解析器代码，而只需编写帮助信息——按照您想要的任何方式。
docopt 可以帮助您轻松地创建最漂亮的命令行界面
"""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__':
arguments = docopt(__doc__, version='Naval Fate 2.0')
print(arguments)看看这个！选项解析器是根据传递给 docopt 函数的上述文档字符串生成的。 docopt 解析使用模式（"用法： ..."）和选项描述（以短横线“-”开头的行）并确保程序调用与使用模式匹配；根据这些解析选项、参数和命令。基本思想是，一个好的帮助信息应该包含创建解析器所需的所有必要信息。
此外，PEP 257 建议在模块文档字符串中放置帮助信息。
安装
使用 pip 或 easy_install
pip install docopt==0.6.2
或者，您可以将 docopt.py 文件放入您的项目中——它是自包含的。
docopt 在 Python 2.5、2.6、2.7、3.2、3.3 和 PyPy 上进行了测试。
API
from docopt import docoptdocopt(doc, argv=None, help=True, version=None, options_first=False)docopt 需要 1 个必需参数和 4 个可选参数
doc 可以是模块文档字符串（__doc__）或包含一个将用于创建选项解析器的 帮助信息 的其他字符串。如何编写这样的帮助信息的简单规则将在下一节中给出。下面是一个这样的字符串的快速示例
"""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
"""argv 是一个可选的参数向量；默认情况下，docopt 使用传递给您的程序的参数向量（sys.argv[1:]）。或者，您可以提供如 ['--verbose', '-o', 'hai.txt'] 这样的字符串列表。
help，默认为 True，指定解析器是否应自动打印帮助信息（作为 doc 提供的）并在遇到 -h 或 --help 选项时终止（选项应存在于使用模式中，下面将详细介绍）。如果您想手动处理 -h 或 --help 选项（如其他选项），请将 help=False。
version，默认为 None，是一个可选参数，用于指定您程序的版本。如果提供，则在（假设使用模式中提到了 --version 选项）解析器遇到 --version 选项时，它将打印提供的版本并终止。 version 可以是任何可打印的对象，但最可能是字符串，例如 "2.1.0rc1"。
注意，当 docopt 设置为自动处理 -h、--help 和 --version 选项时，您仍然需要在用法模式中提及它们，以便这些选项能够正常工作。并且让您的用户了解它们。
options_first 默认为 False。如果设置为 True，将不允许混合选项和位置参数。即第一个位置参数之后，所有参数都将被解释为位置参数，即使它们看起来像选项。这可以用于与 POSIX 严格兼容，或者如果您想将参数传递给其他程序。
返回值是一个简单的字典，以选项、参数和命令作为键，与帮助信息中拼写完全一致。选项的长版本具有优先权。例如，如果您以以下方式调用顶级示例
naval_fate.py ship Guardian move 100 150 --speed=15
返回字典将是
{'--drifting': False, 'mine': False,
'--help': False, 'move': True,
'--moored': False, 'new': False,
'--speed': '15', 'remove': False,
'--version': False, 'set': False,
'<name>': ['Guardian'], 'ship': True,
'<x>': '100', 'shoot': False,
'<y>': '150'}帮助信息格式
帮助信息由两部分组成
用法模式，例如：
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。然而，如果您希望选项具有参数、默认值或指定选项的简称/长称（请参阅下一节关于选项描述），则您需要指定选项描述。
commands 是不遵循上述 --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]（区分大小写）任何选项的快捷方式。如果您想指定使用模式可以提供以下选项描述中定义的任何选项，而不想在用法模式中列举它们，请使用它。- “[--]”。双横线“--”按照惯例用于分隔可能被误认为是选项的位置参数。为了支持这一惯例，请在您的用法模式中添加“[--]”。- “[-]”。单横线“-”按照惯例用于表示使用标准输入而不是文件。为了支持这一惯例，请在您的用法模式中添加“[-]”。“-”作为普通命令。
如果您的模式允许匹配不带参数的选项（标志）多次
Usage: my_program.py [-v | -vv | -vvv]
那么选项出现的次数将被计算。即 args['-v'] 将是 2 如果程序被调用为 my_program -vv。同样适用于命令。
如果您的用法模式允许匹配具有参数或位置参数的相同名称的选项多次，匹配的参数将被收集到一个列表中
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 "-"
要指定选项有一个参数，请将描述该参数的单词放在空格后（或等于“=”符号）如下所示。遵循选项参数的尖括号或大写字母惯例。如果您想分隔选项，请使用逗号。在下面的示例中，两行都是有效的，但建议您坚持一种风格。
-o FILE --output=FILE # without comma, with "=" sign -i <file>, --input <file> # with comma, wihtout "=" sing
使用两个空格来分隔选项及其非正式描述
--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: ./]
如果选项不可重复，则[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 的所有功能方面。[链接](https://github.com/docopt/docopt/tree/master/examples) 请尝试它们，如有疑问请阅读源代码。
子解析器、多层帮助和 大型 应用程序（如git）
如果您想将使用模式拆分成几个，实现多层帮助（为每个子命令提供单独的帮助屏幕），想与不使用 docopt 的现有脚本接口，或者您正在构建下一个“git”，则需要新的 options_first 参数（在上面的API部分中描述）。为了快速入门，我们实现了一个git命令行界面的子集作为示例：[链接](https://github.com/docopt/docopt/tree/master/examples/git)
数据验证
docopt 只做一件事，并且做得很好：实现您的命令行界面。然而，它不验证输入数据。另一方面，有一些库如 python schema 可以轻松地验证数据。请查看 [validation_example.py](https://github.com/docopt/docopt/tree/master/examples/validation_example.py) ，它使用 schema 验证数据并向用户报告错误。
开发
我们非常愿意听到您对我们 docopt 的看法，请在我们的 [问题页面](http://github.com/docopt/docopt/issues) 上发表意见。
创建拉取请求，报告错误，提出建议并讨论 docopt。您也可以直接发邮件到 <vladimir@keleshev.com>。
将 docopt 移植到其他语言
我们认为 docopt 非常好，我们希望将它分享到 Python 社区之外！
以下是一些可用的端口
但您始终可以为您的首选语言创建一个端口！我们鼓励您使用 Python 版本作为参考实现。一个语言无关的测试套件包含在 [Python 实现](http://github.com/docopt/docopt) 中。
端口讨论在 [问题页面](http://github.com/docopt/docopt/issues) 上。
变更日志
docopt 遵循 语义版本控制。第一个具有稳定API的发布将是 1.0.0（即将推出）。在此之前，您鼓励在依赖工具中明确指定版本，例如。
pip install docopt==0.6.2
0.6.2 Wheel 支持。
0.6.1 错误修复发布。
0.6.0 options_first 参数。 破坏性变更：修正了 [options] 的含义。 argv 默认为 None。
0.5.0 重复的选项/命令将被计数或累加到列表中。
0.4.2 错误修复发布。
0.4.0 选项描述成为可选，支持“--”和“-”命令。
0.3.0 支持（子）命令如 git remote add。引入 [options] 快捷方式用于任何选项。 破坏性变更： docopt 返回字典。
0.2.0 使用模式匹配。基于使用模式的定位参数解析。 破坏性变更： docopt 返回命名空间（用于参数），而不是列表。使用模式被形式化。
0.1.0 首次发布。仅选项解析（基于选项描述）。
