python docopt模块详解

docopt 本质上是在 Python 中引入了一种针对命令行参数的形式语言，在代码的最开头使用 """ """文档注释的形式写出符合要求的文档，就会自动生成对应的parse

用法：

docopt的使用非常简单，以Qingchat为例，你只需要在代码最开头加入：

"""Qingchat CLIUsage:qingchat config ip 
     
      qingchat config port 
      
       qingchat config loginqingchat group listqingchat group choose 
       
        ...qingchat group cleanqingchat group send -t 
        
         qingchat group send -i 
         
          qingchat group send -f 
          
            [
           
            ]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,'
     
      ': None,'
      
       ': None,'
       
        ': [],'
        
         ': '127.0.0.1','
         
          ': None,'
          
           ': 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 
      
      
     

　　

选项

形如-o 或者 --option 的文本将会被识别为选项

在转换后的字典中的取值为True或False

Usage:my_program -f 
     

　　

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 
     
      ]
     

　　

等价于

Usage:my_program[command][--option][
     
      ]
     

　　

必选项

形如(required elements)的文本是必选项

上述三种元素默认都是必填项， () 符号用在一些比较特殊的情形下，比如：

Usage:my_program(--either-this
     
      |
      
       )
      
     

　　

选择项

形如element|another 的文本是选择项，可以从中选择一个值

Usage:my_program go (--up|--down|--left|--right)

　　

列表项

形如element...的文本是列表项，可以输入多个参数

比如：

Usage:my_program open 
     
      ...
     

然后可以通过 arguments['<file>']来访问这个列表

Option

option 部分用于指定某些特殊情形，例如：

1. 将某个短参数与长参数关联起来，比如 -i <file>, --input <file>

2. 某个选项有一个参数

3. 选项的默认值，比如 --coefficient=K The K coefficient [default: 2.95]