ArgumentParser的description和epilog

用python编写一个命令行接口的程序，少不了 -h 时的丰富的命令行信息显示，这就需要 ArgumentParser 对象使用description和epilog参数。description参数显示在usage和命令行参数（positional或optional）之间，我喜欢用这个区域来写程序的usage example。epilog参数显示在最后，我喜欢用这个区域留下自己的github页面和博客链接。

import argparse

parser = argparse.ArgumentParser(
                description = 'this is description',
                epilog = 'www.pynote.net')
parser.print_help()

这段示例代码运行效果如下：

E:\py>python cmd_info.py
usage: cmd_info.py [-h]

this is description

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

www.pynote.net

description部分一般要写不少内容，会有很多行，默认情况下，ArgumentParser对象会对多行内容进行line-wrap，就是把所有的换行和连续的空格都变成一个空格。针对line-wrap，我用下面这个示例展示：

import argparse

parser = argparse.ArgumentParser(
                description = '''this is description
                which have a few lines and many line
                feed and space...this is description
                which have a few lines and many line
                feed and space...
                ''',
                epilog = 'www.pynote.net')
parser.print_help()

让我们来看看line-wrap的效果：

E:\py>python cmd_info.py
usage: cmd_info.py [-h]

this is description which have a few lines and many line feed and space...this
is description which have a few lines and many line feed and space...

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

www.pynote.net

核心关切是，代码中description这段文字的所有格式都会因为line-wrap而失效。一般情况下，这不是我需要的。我需要在程序 -h 的时候，显示出来的description与代码中的格式保持一致。

这就需要用到ArgumentParser对象的另一个参数，formatter_class，请看下面的代码：

import argparse

parser = argparse.ArgumentParser(
                formatter_class = argparse.RawDescriptionHelpFormatter,
                description = '''this is description
                which have a few lines and many line
                feed and space...this is description
                which have a few lines and many line
                feed and space...
                ''',
                epilog = 'www.pynote.net')
parser.print_help()

我让 formatter_class = argparse.RawDescriptionHelpFormatter, 就有了一部分刚才我需要的效果：

E:\py>python cmd_info.py
usage: cmd_info.py [-h]

this is description
                which have a few lines and many line
                feed and space...this is description
                which have a few lines and many line
                feed and space...


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

www.pynote.net

还是有问题，indentation与预期不符。这是因为使用'''（triple single quotation）的长字符串，内含了很多空格。这时，要祭出python另一个标准库中的模块：textwrap。使用textwrap.dedent函数，可以很好的解决上面没有对齐的问题。

import argparse
import textwrap

parser = argparse.ArgumentParser(
                formatter_class = argparse.RawDescriptionHelpFormatter,
                description = textwrap.dedent('''\
                this is description
                which have a few lines and many line
                feed and space...this is description
                which have a few lines and many line
                feed and space...
                '''),
                epilog = 'www.pynote.net')
parser.print_help()

此时，我要的效果就完整了：

E:\py>python cmd_info.py
usage: cmd_info.py [-h]

this is description
which have a few lines and many line
feed and space...this is description
which have a few lines and many line
feed and space...

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

www.pynote.net

epilog参数与description一样，默认都是line-wrap，也同样收到formatter_class的影响。formatter_class有4个值可以选择，具体请参考python官方的说明：https://docs.python.org/3/library/argparse.html#formatter-class

好好编写python命令行程序的description和epilog，代码即文档。

-- EOF --

相关文章

• 如何使用argparse.FileType？
• 用choices给命令行参数设置范围
• 实现命令行程序的互斥参数
• 用argparse实现带sub-command的命令行
• ArgumentParser的prog参数
• argparse模块的位置参数和可选（必选）参数
• add_argument函数action参数总结
• argparse支持命令行的模式选项
• add_argument函数的dest参数
• add_argument函数的default参数
• add_argument函数的metavar参数
• 用add_argument函数的nagrs参数实现命令行多值参数
• 用argparse实现任意类型的命令行参数