Python命令行参数解析工具 docopt 安装和应用过程详解

什么是 docopt

docopt 是 Python 的一个命令行参数解析库，其最大的特点在于使用一份帮助文档（docstring）来定义命令行接口，而不是像传统的 argparse、getopt 这些工具一样需要手动编写参数列表、参数解析规则、帮助信息等。docopt 的官方网站有更详细的介绍和文档：https://github.com/docopt/docopt。

安装 docopt

docopt 可以通过 pip 安装：

pip install docopt

使用 docopt

首先，我们需要编写一份帮助文档，来定义我们程序要支持的命令行参数和参数解析规则，比如，我们编写的 demo.py 代码如下：

#!/usr/bin/env python
# coding=utf-8

"""Usage:
  demo.py init [--force]
  demo.py add [--verbose] [<file>...]
  demo.py -h | --help
  demo.py --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --force       Force to initialize.
  --verbose     Verbose mode.
"""

from docopt import docopt

def main():
    arguments = docopt(__doc__, version='1.0.0')
    print(arguments)

if __name__ == '__main__':
    main()

在该帮助文档中定义了三个命令，分别是 init，add 和 -h|--help，以及这些命令的参数。这些命令和参数的定义直接体现在 demo.py 的 docstring 中。docopt 能够通过解析该 docstring 来自动生成解析参数的代码，并且在参数输入不符合定义时自动打印帮助信息，支持像 -h 或 --help 选项直接展示 docstring 的文档内容。

从命令行中输入 demo.py --help，可以看到自动生成的帮助信息：

Usage:
  demo.py init [--force]
  demo.py add [--verbose] [<file>...]
  demo.py -h | --help
  demo.py --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --force       Force to initialize.
  --verbose     Verbose mode.

我们可以立即用这份帮助文档的规则解析输入参数，举个例子：

$ python demo.py init --force
{'--force': True, '--help': False, '--version': False, 'add': False, 'init': True, '<file>': [], '--verbose': False}

在这个例子中，我们通过命令行输入 python demo.py init --force，程序解析该命令行参数并返回一个 Python 字典。字典中键的名称即为 docstring 中定义的命令和参数。

再看一个例子，当我们输入命令行参数不符合规则时，docopt 可以自动打印帮助信息。对于上述 Demo 代码来说：

$ python demo.py add -q   # 错误的参数
Usage:
  demo.py init [--force]
  demo.py add [--verbose] [<file>...]
  demo.py -h | --help
  demo.py --version

Options:
...

可以看到，程序根据定义的 docstring 打印了正确的帮助信息，提醒我们正确使用命令行参数。

总结

本文介绍了 docopt 的安装步骤以及如何使用该 Python 命令行参数解析库。相比传统参数解析工具，docopt 使用更简单，而且能够自动生成帮助文档和解析参数代码，大大减轻了开发人员的负担，更容易编写出高质量的命令行程序。