【python之argparse模块学习】简单入门

0 前言

1. 该模块地位： Python 标准库中推荐的命令行解析模块。
2. 类比linux命令ls来理解该模块功能。与该命令类似的，如果程序需要用户输入指定的参数参与运行，可以用 argparse 模块来实现。
   1. ls 是一个即使在运行的时候没有提供任何选项，也非常有用的命令。在默认情况下他会输出当前文件夹包含的文件和文件夹。
   2. ls 指定目录会输出指定文件夹包含的文件和文件夹。
   3. ls -l会输出文件和文件夹的详细参数。

1 入门程序

1. 让我们从一个简单到（几乎）什么也做不了的例子开始，该程序文件名为 prog.py。

import argparse
parser = argparse.ArgumentParser()
parser.parse_args()

2. 在该文件所在路径打开cmd命令窗口，执行不同参数的语句结果如下。

$ python3 prog.py

$ python3 prog.py --help
usage: prog.py [-h]
options:
  -h, --help  show this help message and exit
  
$ python3 prog.py --verbose
usage: prog.py [-h]
prog.py: error: unrecognized arguments: --verbose

$ python3 prog.py foo
usage: prog.py [-h]
prog.py: error: unrecognized arguments: foo

3. 程序运行情况如下：
   1. 在没有任何选项的情况下运行脚本不会在标准输出显示任何内容。这没有什么用处。
   2. 第二行代码开始展现出 argparse 模块的作用。我们几乎什么也没有做，但已经得到一条很好的帮助信息。
   3. –help 选项，也可缩写为 -h，是唯一一个可以直接使用的选项（即不需要指定该选项的内容）。指定任何内容都会导致错误。即便如此，我们也能直接得到一条有用的用法信息。

2 参数

1. 作用：使用者调用程序时，在前端输入的信息。
2. 分类：
   1. 位置参数：必须传参，传参不用指定参数名。
   2. 可选参数：可以不传参，传参是需要指定参数名。

2.1 位置参数

1. 位置参数，就像其命名一样，前端将参数按位置顺序传递给程序，不用指定参数名。
2. 为了让程序能更加人性化，可以对参数进行处理，指定“help”、“type”等方法进行处理。
   1. “help”：能让程序使用者调用帮助命令时，用于介绍选项的作用。
   2. “type”：程序选项在接收前端输入时，默认格式为字符串，该参数用于指定数据格式。如果输入的字符串能转换为指定的数据格式，则正常转换，如果转换失败，则报错。
3. 程序示例：
   1. 下面的程序用于接收使用者输入的数据，并输入该数据的平方回显到命令行。
   2. 第二行，创建一个新的 ArgumentParser 对象。
   3. 第三行，新增选项并赋予参数。argparse对象新增一个选项square，该选项赋予两个参数，help参数填写了选项“square”的用途，type参数执行了将输入转换为整型。
   4. 第四行，返回带有成员的命名空间，可以使用.来访问里面的每一个选项。
   5. 第五行，使用对应的选项内容进行计算，并打印结果。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number", type=int)
args = parser.parse_args()
print(args.square**2)

4. 将上述程序存入名为test.py的文件中，在cmd窗口调用，输入不同数据执行结果如下：
   1. 当没有输入参数时，会报错，因为选项square是位置参数，是必须输入的。
   2. 当输入数字4时，成功返回计算结果。
   3. 当输入字符串four时，程序执行出错，提示需要输入数字。
   4. 不同输入参数名，不然会被当做输入给参数的字符串去执行。
   5. 参看该程序的帮助命令，可以看到该程序有位置参数和可选参数两类。

$ python test.py
usage: test.py [-h] square
test.py: error: the following arguments are required: square

$ python test.py 4
16

$ python test.py four
usage: test.py [-h] square
test.py: error: argument square: invalid int value: 'four'

$ python test.py square 4
usage: test.py [-h] square
test.py: error: argument square: invalid int value: 'square'

$ python test.py -h
usage: test.py [-h] square
positional arguments:
  square      display a square of a given number
optional arguments:
  -h, --help  show this help message and exit

2.2 可选参数

1. 有一些参数不是程序执行所必须的，或者是可以设置默认的，可以将其设置为可选参数来参与程序运行。
2. 在上述程序的基础上进行优化，示例如下：
   1. 第4行，添加一个可选参数 “–verbosity”，用 “-” 开头的表示可选参数，两杠表示长参数，一杠表示短参数。
   2. 第6-9行，根据可选参数判断是要输出完整信息还是简要信息。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number", type=int)
parser.add_argument("--verbosity", help="increase output verbosity")
args = parser.parse_args()
if args.verbosity:
	print("the square of " + str(args.square) + " is " + str(args.square**2))
else:
	print(args.square**2)

3. 输入不同参数执行如下：
   1. 给参数 verbosity 传参为1，回显详细输出内容。
   2. 不调用参数 verbosity ，回显简要输出内容。
   3. 当调用参数 verbosity 又不传参时，程序出错，应为该参数还没设置默认参数。
   4. 参看帮助，有两个可选参数分别是 help 和 verbosity 。

$ python test.py 4 --verbosity 1 		# 效果等同 python test.py --verbosity 1 4
the square of 4 is 16

$ python test.py 4
16

$ python test.py 4 --verbosity
usage: test.py [-h] [--verbosity VERBOSITY] square
test.py: error: argument --verbosity: expected one argument

$ python test.py -h
usage: test.py [-h] [--verbosity VERBOSITY] square
positional arguments:
  square                display a square of a given number
optional arguments:
  -h, --help            show this help message and exit
  --verbosity VERBOSITY
                        increase output verbosity

4. 程序优化。
   1. 根据上述程序，可选参数的功能仅是对输出内容完整输出还是简要输出的控制，这一选项更多地是一个标志，而非需要接受一个值的什么东西。
   2. 指定选项 verbose 关键词 action赋值为 “store_true”。这意味着，当这一选项存在时，为 args.verbose 赋值为 True。没有指定时则隐含地赋值为 False。
   3. 新增短选项，为选项同时命名为"-v", “–verbose”，两者皆可启用该参数。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number", type=int)
parser.add_argument("-v", "--verbose", help="increase output verbosity",action="store_true")
args = parser.parse_args()
if args.verbose:
	print("the square of " + str(args.square) + " is " + str(args.square**2))
else:
	print(args.square**2)

5. 输入不同参数执行如下：调用参数 -v ，无需传参，更符合该参数对应功能的使用习惯。

$ python test.py -v 4
the square of 4 is 16

$ python test.py 4 -v
the square of 4 is 16

2.3 矛盾选项

1. argparse.ArgumentParser 实例的第三个方法 add_mutually_exclusive_group()。 它允许我们指定彼此相互冲突的选项。 让我们再更改程序的其余部分以便使用新功能更有意义。
2. 比如，我们将引入 --quiet 选项，它将与 --verbose 正好相反：
   1. 引入一组互相冲突的选项，命名为 group，在该组中添加相互矛盾的选项。
   2. 扩展程序功能，能计算 x 的 y 次方，程序需要接收 x 和 y 两个参数。

import argparse

parser = argparse.ArgumentParser()
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y

if args.quiet:
    print(answer)
elif args.verbose:
    print(f"{args.x} to the power {args.y} equals {answer}")
else:
    print(f"{args.x}^{args.y} == {answer}")

3. 输入不同参数，程序执行如下：
   1. x 和 y 是位置参数，需要按程序的顺序输入，x在前，y在后。
   2. 可以启用参数q或v来控制输出内容的完整程度。
   3. 同时启用参数 q 和 v，程序会报错。

$ python test.py 4 2
4^2 == 16

$ python test.py -q 4 2
16

$ python test.py -v 4 2
4 to the power 2 equals 16

$ python test.py -v -q 4 2
usage: test.py [-h] [-v | -q] x y
test.py: error: argument -q/--quiet: not allowed with argument -v/--verbose

$ python test.py -vq 4 2
usage: test.py [-h] [-v | -q] x y
test.py: error: argument -q/--quiet: not allowed with argument -v/--verbose

3 总结

1. 本文章作为简单的入门指引，能简单熟悉argprase模块的功能。
2. 对于 ArgumentParser 对象，还有以下方法：
   1. prog - 程序的名称 (默认值: os.path.basename(sys.argv[0]))
   2. usage - 描述程序用途的字符串（默认值：从添加到解析器的参数生成）
   3. description - 在参数帮助文档之前显示的文本（默认值：无）
   4. epilog - 在参数帮助文档之后显示的文本（默认值：无）
   5. parents - 一个 ArgumentParser 对象的列表，它们的参数也应包含在内
   6. formatter_class - 用于自定义帮助文档输出格式的类
   7. prefix_chars - 可选参数的前缀字符集合（默认值： ‘-’）
   8. fromfile_prefix_chars - 当需要从文件中读取其他参数时，用于标识文件名的前缀字符集合（默认值： None）
   9. argument_default - 参数的全局默认值（默认值： None）
   10. conflict_handler - 解决冲突选项的策略（通常是不必要的）
   11. add_help - 为解析器添加一个 -h/–help 选项（默认值： True）
   12. allow_abbrev - 如果缩写是无歧义的，则允许缩写长选项 （默认值：True）
   13. exit_on_error - 决定当错误发生时是否让 ArgumentParser 附带错误信息退出。 (默认值: True)
3. 对于 add_argument() 方法，还有以下关键字：
   1. name or flags - 一个命名或者一个选项字符串的列表，例如 foo 或 -f, --foo。
   2. action - 当参数在命令行中出现时使用的动作基本类型。
   3. nargs - 命令行参数应当消耗的数目。
   4. const - 被一些 action 和 nargs 选择所需求的常数。
   5. default - 当参数未在命令行中出现并且也不存在于命名空间对象时所产生的值。
   6. type - 命令行参数应当被转换成的类型。
   7. choices - 可用的参数的容器。
   8. required - 此命令行选项是否可省略 （仅选项可用）。
   9. help - 一个此选项作用的简单描述。
   10. metavar - 在使用方法消息中使用的参数值示例。
   11. dest - 被添加到 parse_args() 所返回对象上的属性名。
4. 更多方法的使用见文末官方文档。

4 参考文献

1. argparse官方文档——入门介绍
2. argparse官方文档