python中description_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 --