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]

Usageoptions里的内容就组成了帮助信息,当用户输入-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项目里提供了很多的例子,可以去试试。

results matching ""

    No results matching ""