为Python脚本编写帮助文档

Question

我想让我的Python脚本更友好，所以我想写一些帮助说明。你有什么建议吗？我可以简单地加一些逻辑，比如如果用户在运行脚本时输入了“help”这个参数，就显示帮助信息。有没有什么好的做法或者约定呢？

Answer 1

除了内置的 argparse 之外，还有一个第三方的工具包叫做 Click。这个工具包的特点是可以“自动生成帮助页面”和“支持命令的任意嵌套”（这也会生成嵌套的帮助页面）。它的内部实现是基于 argparse 的，但我觉得用装饰器来创建复杂的命令行界面（CLI）会更加方便。

下面是一个示例代码：

import click

@click.command()
@click.argument("things", nargs=-1)
@click.option("-t", show_default=True, default="int", help="Data type")
@click.option("-o", help="Output format")
def combine(things, t):
    """Combines things into a single element"""
    pass

if __name__ == "__main__":
    combine()

生成的帮助页面如下：

$ python myapp.py --help
Usage: myapp.py [OPTIONS] [THINGS]...

  Combines things into a single element

Options:
  -t TEXT  Data type  [default: int]
  -o TEXT  Output format
  --help   Show this message and exit.

它的一个优点是可以把方法的文档字符串（docstrings）作为帮助页面的一部分，这样就方便了，因为文档字符串可以同时用于开发者文档和脚本使用帮助。

你还可以创建嵌套的命令组：

import click

@click.command()
@click.argument("numbers", nargs=-1)
@click.option("-e", help="Extra option for add")
def add(numbers, e):
    """Adds numbers"""
    print(f"This method should add {numbers}")

@click.command()
@click.argument("numbers", nargs=-1)
@click.option("-e", help="Extra option for mul")
def mul(numbers, e):
    """Multiplies numbers"""
    print(f"This method should multiply {numbers}")

@click.group()
def calc():
    pass

calc.add_command(add)
calc.add_command(mul)

if __name__ == "__main__":
    calc()

这样就会生成嵌套的帮助页面：

$ python myapp.py --help
Usage: myapp.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  add  Adds numbers
  mul  Multiplies numbers

---

$ python myapp.py add --help
Usage: myapp.py add [OPTIONS] [NUMBERS]...

  Adds numbers

Options:
  -e TEXT  Extra option for add
  --help   Show this message and exit.

---

$ python myapp.py mul --help
Usage: myapp.py mul [OPTIONS] [NUMBERS]...

  Multiplies numbers

Options:
  -e TEXT  Extra option for mul
  --help   Show this message and exit.

想了解更多信息，可以查看文档中的 文档脚本 部分。

Answer 2

最好的做法是使用 argparse 来处理你所有的命令行参数。它自带一个默认的 --help 选项，你可以根据自己的需要进行定制。

下面是一个最简单的例子：

import argparse

parser = argparse.ArgumentParser(description='This is my help')

args = parser.parse_args()

这会产生：

% python argparse_test.py -h
usage: argparse_test.py [-h]

This is my help

optional arguments:
  -h, --help  show this help message and exit

你可以用 argparse 定义所有的参数，并为每个参数设置帮助信息。最后，经过过滤和验证的参数会通过 parser.parse_args() 返回。

Answer 3

使用 argparse 这个库。

比如说，假设你有一个叫 test.py 的文件：

import argparse

parser=argparse.ArgumentParser(
    description='''My Description. And what a lovely description it is. ''',
    epilog="""All is well that ends well.""")
parser.add_argument('--foo', type=int, default=42, help='FOO!')
parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
args=parser.parse_args()

运行这个文件

% test.py -h

会得到

usage: test.py [-h] [--foo FOO] [bar [bar ...]]

My Description. And what a lovely description it is.
    
positional arguments:
  bar         BAR!
    
optional arguments:
  -h, --help  show this help message and exit
  --foo FOO   FOO!
    
All is well that ends well.