python docopt模块详解
python docopt模块详解
docopt 本质上是在 Python 中引入了一种针对命令行参数的形式语言,在代码的最开头使用 """ """文档注释的形式写出符合要求的文档,就会自动生成对应的parse
用法:
docopt的使用非常简单,以Qingchat为例,你只需要在代码最开头加入:
"""Qingchat CLI Usage: qingchat config ip <ip> qingchat config port <port> qingchat config login qingchat group list qingchat group choose <group_name>... qingchat group clean qingchat group send -t <content> qingchat group send -i <media> qingchat group send -f <file> [<delaytime>] Options: -h --help Show this screen. -v --version Show version. """
然后在执行代码中加入:
arguments = docopt(__doc__,version="Qingchat 0.3.2")
然后就会在程序中导入一个arguments字典,这个字典的内容为:
{ '-f': False, '-i': False, '-t': False, '<content>': None, '<file>': None, '<group_name>': [], '<ip>': '127.0.0.1', '<media>': None, '<port>': None, 'choose': False, 'clean': False, 'config': True, 'group': False, 'ip': True, 'list': False, 'login': False, 'port': False, 'send': False }
下面我们来详细介绍一下如何完成一个符合 docopt 要求的注释文档:
Usage
所有出现在Usage:(区分大小写)和一个空行之间的文本都会被识别为一个命令组合, Usage 后的第一个字母将会被识别为这个程序的名字,所有命令组合的每一个部分(空格分隔)都会成为字典中的一个key
参数
形如<argument> 或者 ARGUMENT的文本将会被识别为参数
在转化后的字典中的取值为True 或者False.
Usage:my_program <host> <port>
选项
形如-o 或者 --option 的文本将会被识别为选项
在转换后的字典中的取值为True或False
Usage:my_program -f <file>
Tips:
1. 短选项可以组合起来,比如 -abc 等价于 -a -b -c
2. 长选项需要的参数需要使用 = 或者空格来分隔, --input=ARG 等价于 --input ARG
3. 短选项可以不需要空格, -f FILE 等价于 -fFILE
命令
不满足 --options 或者 <arguments> 的文本将会被识别为(子)命令
在转化后的字典中取值为 True 或者 False
可选项
形如 [optional elements]的文本是可选项
elements包括上述的三种类型:参数,选项以及命令
在相同或者不同的括号中都是一样的:
Usage:my_program[command --option <argument>]
等价于
Usage:my_program[command][--option][<argument>]
必选项
形如(required elements)的文本是必选项
上述三种元素默认都是必填项, () 符号用在一些比较特殊的情形下,比如:
Usage:my_program(--either-this<and-that>|<or-this>)
选择项
形如element|another 的文本是选择项,可以从中选择一个值
Usage:my_program go (--up|--down|--left|--right)
列表项
形如element...的文本是列表项,可以输入多个参数
比如:
Usage:my_program open <file>...
然后可以通过 arguments['<file>']来访问这个列表
Option
option 部分用于指定某些特殊情形,例如:
1. 将某个短参数与长参数关联起来,比如 -i <file>, --input <file>
2. 某个选项有一个参数
3. 选项的默认值,比如 --coefficient=K The K coefficient [default: 2.95]