ArgumentParser的description和epilog

2020年1月31日 / 24次阅读 / Last Modified 2020年1月31日
argparse模块

用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 --

本文链接:https://www.pynote.net/archives/1766

留言区

电子邮件地址不会被公开。 必填项已用*标注


前一篇:
后一篇:

More


©Copyright 麦新杰 Since 2019 Python笔记

go to top