docopt - 创建漂亮的命令行交互界面 (未完成)

背景

• 在芝麻星上挖到过这个链接
  • 去docopt官网上稍微浏览了一下
  • 知道这是一个用于参数解析的python第三方库
• 编写交互日记系统时
  • 想根据传入参数执行写入或读出
  • 需要提供usage等帮助信息
  • 因此去深入了解docopt

简介

docopt官网上的介绍是

Command-line interface description language

docopt helps you:

• define interface for your command-line app, and
• automatically generate parser for it.

从中可以看出docopt的两个主要功能：

• 定义交互参数
• 解析参数信息

再看官网上对于命令行交互界面的一个简单例子

Naval Fate.

Usage:
  naval_fate ship new <name>...
  naval_fate ship <name> move <x> <y> [--speed=<kn>]
  naval_fate ship shoot <x> <y>
  naval_fate mine (set|remove) <x> <y> [--moored|--drifting]
  naval_fate -h | --help
  naval_fate --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --speed=<kn>  Speed in knots [default: 10].
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.

在这个例子中，Naval Fate是app名称，naval_fate是命令行命令，ship, new, move这些是可选的执行命令(commands), , , 这些是位置参数(positional arguments)，-h, --help, --speed=这些是选项参数(options)，

例子里面用

• "[]"描述可选元素(optional)
• "()"描述必要元素(required)
• "|" 描述互斥元素(mutually exclusive)
• "..."描述重复元素(repeating)

这些参数，前面加上naval_fate就形成了可用的命令，这些命令在Usage中介绍。

Usage下面的Options里罗列了选项(options)及其描述，它具体描述了

• 选项是否有长/短形式，如-h, --help
• 选项后面是否带参数，如--speed=
• 选项是否有默认值，如[default: 10]

Usage和options里的内容就组成了帮助信息，当用户输入-h或--help参数时，命令行就会输出帮助信息。

docopt会抽取帮助信息里的内容，然后对命令行传入的参数进行解析。

用实例来说明，创建一个naval_fate.py文档

# naval_fate.py
"""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)

执行命令

$ python naval_fate.py ship new hangzhou

得到输出

{'--drifting': False,
 '--help': False,
 '--moored': False,
 '--speed': '10',
 '--version': False,
 '<name>': ['anaconda'],
 '<x>': '10',
 '<y>': '20',
 'mine': False,
 'move': True,
 'new': False,
 'remove': False,
 'set': False,
 'ship': True,
 'shoot': False}

再执行

$ python naval_fate.py ship shoot 42 36

得到输出

{'--drifting': False,
 '--help': False,
 '--moored': False,
 '--speed': '10',
 '--version': False,
 '<name>': [],
 '<x>': '42',
 '<y>': '36',
 'mine': False,
 'move': False,
 'new': False,
 'remove': False,
 'set': False,
 'ship': True,
 'shoot': True}

然后再尝试一个Usage里没有的命令

$ python naval_fate.py repair

得到输出

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

可以看出，

• docopt(__doc__)这个函数根据帮助文档的说明解析命令行参数，然后将结果返回为一个字典。
• 当用户使用不在Usage之内的命令，输出帮助文档。

安装

方法一：

使用pip

$ pip install docopt==0.6.1

方法二：

因为docopt.py是自我完备的(self-contained)，所以可以将它直接放到项目里进行调用。

ps: docopt is tested with Python 2.5, 2.6, 2.7, 3.2, 3.3 and PyPy.

使用

在python脚本中：

首先从docopt模块中调用docopt函数

from docopt import docopt

之后用docopt函数解析参数

docopt(doc, argv=None, help=True, version=None, options_first=False)

docopt需要1个必要的位置参数和4个可选的关键字参数

• doc可以是模块的docstring(doc)或其他包含帮助信息的字符串。它被用于当作参数解析的规则。
• argv是一个参数列表，默认值为sys.argv[1:]，你也可以提供其他列表如['--verbose', '-o', 'hai.txt']。
• help选择当遇到-h和--help参数时是否输出帮助信息并退出程序，默认值为True。
• version描述程序版本，默认值为None，如果给version传入了值，那么在解析--version选项时，程序会输出版本信息并退出。
• options_first默认值为False。如果它设为True的话会禁止混合使用选项(options)和位置参数(positional argument)。例如，在第一个位置参数后面，其他参数都被当作位置参数，而不是选项。

docopt()的返回值是一个字典

• 所有选项、位置参数和命令的名称作为键(key)
• 传入的参数作为值(value)

体验

docopt的github项目里提供了很多的例子，可以去试试。