python add_argument() 方法详解

官方文档的说明

首先我们来看一下官方文档的说明,了解一下 add_argument() 有哪些参数,接下来的介绍中引用块都是所有官方文档的原文,对于每一个参数及其取值的说明会加上我的个人理解以及举例说明。

ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])

下面的官方介绍简单看一下即可,后面分别作详细解释

定义单个的命令行参数应当如何解析。每个形参都在下面有它自己更多的描述,长话短说有:
• name or flags 一个命名或者一个选项字符串的列表,例如 foo-f, --foo
• action 当参数在命令行中出现时使用的动作基本类型。
• nargs 命令行参数应当消耗的数目。
• const 被一些action和 nargs选择所需求的常数。
• default 当参数未在命令行中出现并且也不存在于命名空间对象时所产生的值。
• type 命令行参数应当被转换成的类型。
• choices 可用的参数的容器。
• required 此命令行选项是否可省略 (仅选项可用)。
• help 一个此选项作用的简单描述。
•metavar 在使用方法消息中使用的参数值示例。
• dest 被添加到 [parse_args()] 所返回对象上的属性名。

参数 name or flags

name or flags - 一个命名或者一个选项字符串的列表,例如 foo-f, --foo

add_argument()方法必须知道它是否是一个选项,例如 -f--foo,或是一个位置参数,例如一组文件名。第一个传递给 add_argument() 的参数必须是一系列 flags 或者是一个简单的参数名。

在官方文档中,诸如 foo 这种前面没有 “-” 的参数被称为名称(name),而 -f, --foo 这种前面有 “-” 的参数被称为旗标(flags)

所谓的位置参数(foo)指的是在命令行参数的顺序必须与name or flags字符串列表中的位置参数顺序一致。反之,-f—-foo则可以在命令行里任意位置指定,前者一般为后者的缩略形式(比如查看某些库的版本时既可以使用 xxx -v 也可以使用 xxx -—version)。

例 1:

import argparse

# 将命令行中输入的数字组合成一个四位数
parser = argparse.ArgumentParser(description='命令行中输入若干个数字')
parser.add_argument('n1', type=int, help='输入第一个数字')
parser.add_argument('n2', type=int, help='输入第二个个数字')
parser.add_argument('-n3', type=int, help='输入一个数字')
parser.add_argument('--n4', type=int, help='输入一个数字')
args = parser.parse_args()
ans = 0
ans = 1000 * args.n1 + 100 * args.n2 + 10 * args.n3 + args.n4
print(ans)
# 输出结果
**python demo.py 1 2 -n3=3  --n4=4**
1234
**python demo.py 1 -n3=3 2  --n4=4**
1234
**python demo.py --n4=9 1 2 -n3=0**
1209

从上述结果可知,位置参数 n1 和 n2 是由命令行参数的顺序决定的,而参数 n3 和 n4 是由 flag=x 指定的,而且n3 和 n4 的在命令行中何处指定都可以。

参数action

action - 当参数在命令行中出现时使用的动作基本类型。

ArgumentParser 对象将命令行参数与动作相关联。这些动作可以做与它们相关联的命令行参数的任何事,尽管大多数动作只是简单的向parse_args()返回的对象上添加属性。action命名参数指定了这个命令行参数应当如何处理。

action = ‘store’

默认值,存储参数的值。用法见例 1

action = 'store_const’

存储被 const 命名参数指定的值。

'store_const'动作通常用在选项中来指定一些标志。

例 2:

在命令行参数中加入 -v--version 来获取程序的版本信息。

import argparse

parser = argparse.ArgumentParser(description='命令行中输入若干个数字')
# an example of action='store_const'
parser.add_argument('-v', '--version', action='store_const', const=True, default=False, help='显示版本信息')
args = parser.parse_args()

if args.version:
    print('Version: 1.0')
print('Exit')
# 输出结果
**python demo.py**   
Exit
**python demo.py -v**       
Version: 1.0
Exit
**python demo.py --version**
Version: 1.0
Exit

例 3:

import argparse

parser = argparse.ArgumentParser(description='命令行中输入若干个数字')
# an example of action='store_const'
parser.add_argument('-t', '--times', action='store_const', const=10, default=1, help='将结果乘以10')
args = parser.parse_args()

sum = 0
for i in range(1,10):
    sum += i
print(sum * args.times)
# 输出结果
**python demo.py**   
45
**python demo.py -t**       
450
**python demo.py --times**
450

从例子中可以看出,当 action = ‘store_const’ 时,需要为其指定一个 const 值和一个 default 值,这样当在命令行参数输入 flags(例 1 中为 -v—-version )时,args 中对应参数的值就会等于 const 值,否则等于 default 值(这种情况下不需也不能在命令行中指定参数的值,如 python demo.py --version 1 会报错)

action = 'store_true’ 和 'store_false’

这些是 'store_const'分别用作存储 TrueFalse 值的特例。另外,它们的默认值分别为 FalseTrue

注意,官方文档里说的“默认值”指的是 const 值而不是 default 值。

例 2 中第 5 行代码可以等价简化为以下形式:

parser.add_argument('-v', '--version', action='store_true', default=False, help='显示版本信息')

action = ‘append’

存储一个列表,并且将每个参数值追加到列表中。在允许多次使用选项时很有用。

直接看例子:

例 4:

import argparse

parser = argparse.ArgumentParser(description='命令行中输入若干个数字')
# an example of action='append'
parser.add_argument('-n', '--numbers', action='append', type=int, help='输入若干个数字')
args = parser.parse_args()
print(args.numbers)
# 输出结果
**python demo.py -n 3 -n 6 -n 7**
[3, 6, 7]

action = ‘append_const’

存储一个列表,并将 const 命名参数指定的值追加到列表中。(注意 const 命名参数默认为 None。)

'append_const’ 动作一般在多个参数需要在同一列表中存储常数时会有用

'store_const' ,这里就不详细展开了。

action = ‘count’

计算一个关键字参数出现的数目或次数。对于一个增长的详情等级来说有用。

例 5:

import argparse

parser = argparse.ArgumentParser()
# an example of action='count'
parser.add_argument('-v', '--verbose', action='count', default=0)
args = parser.parse_args()
for i in range(args.verbose + 1):
    print('verbose:', i)
# 输出结果
**python demo.py**               
verbose: 0
**python demo.py -v**
verbose: 0
verbose: 1
**python demo.py -vvv**
verbose: 0
verbose: 1
verbose: 2
verbose: 3
**python demo.py --verbose --verbose** # 太麻烦了,一般不这么用
verbose: 0
verbose: 1
verbose: 2

action = ‘help’

打印所有当前解析器中的选项和参数的完整帮助信息,然后退出。默认情况下,一个 help 动作会被自动加入解析器。关于输出是如何创建的,参见 ArgumentParser

action = ‘version’

期望有一个 version= 命名参数在 add_argument() 调用中,并打印版本信息并在调用后退出。

例 2action = ‘version’ 改写:

例 6:

import argparse

parser = argparse.ArgumentParser(prog='Version:',description='命令行中输入若干个数字')
# an example of action='store_const'
parser.add_argument('-v', '--version', action='version', version='%(prog)s 1.0', help='显示版本信息')
args = parser.parse_args()

print('Exit')
# 输出结果
**python demo.py**   
Exit
**python demo.py -v**  
Version: 1.0

action = ‘extend’

这会存储一个列表,并将每个参数值加入到列表中。

nargs

ArgumentParser 对象通常关联一个单独的命令行参数到一个单独的被执行的动作。 nargs
命名参数关联不同数目的命令行参数到单一动作。

支持的值有:

nargs = N

命令行中的 N 个参数会被聚集到一个列表中。

N 是一个整数。

例 7:

import argparse

parser = argparse.ArgumentParser(description='命令行中输入5个数字')
# an example of nargs=N
parser.add_argument('numbers', type=int, nargs=5, help='输入5个数字')
args = parser.parse_args()
print(args.numbers)
# 输出结果
**python demo.py 2 3 4 5 6**  
[2, 3, 4, 5, 6]

nargs = '?’

如果可能的话,会从命令行中消耗一个参数,并产生一个单一项。如果当前没有命令行参数,则会产生 default 值。注意,对于选项,有另外的用例 - 选项字符串出现但没有跟随命令行参数,则会产生 const 值。

这个官方文档描述的比较清楚了,注意不给参数的话什么情况下产生 default 值,什么情况下产生 const 值。

import argparse

parser = argparse.ArgumentParser(description='命令行中至多输入1个数字')
# an example of nargs='?'
parser.add_argument('-n', '--numbers', type=int, nargs='?', const=1, default=2, help='至多输入1个数字')
args = parser.parse_args()

print(args.numbers)
# 输出结果
**python demo.py** # default          
2
**python demo.py -n** # const
1
**python demo.py --numbers** # const
1
**python demo.py -n 3**     
3

nargs='?' 的一个更普遍用法是允许可选的输入或输出文件。

例 8(官方例子):

import argparse
import sys

parser = argparse.ArgumentParser(description='命令行中输入文件')
# an example of nargs=N

parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
                    default=sys.stdin)
parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
                    default=sys.stdout)
args = parser.parse_args()

print(args)
# 输出结果
**python demo.py input.txt output.txt**
Namespace(infile=<_io.TextIOWrapper name='input.txt' mode='r' encoding='UTF-8'>, outfile=<_io.TextIOWrapper name='output.txt' mode='w' encoding='UTF-8'>)

nargs = ‘*’

'*'。所有当前命令行参数被聚集到一个列表中。注意通过 nargs='*' 来实现多个位置参数通常没有意义,但是多个选项是可能的。

通过 nargs='*' 可以让一个参数接受 0 到多个来自命令行参数的输入。

例 9:

import argparse
import sys

parser = argparse.ArgumentParser(description='命令行中输入多个数字,输出他们的和')
# an example of nargs='*'
parser.add_argument('numbers', type=int, nargs='*', help='输入多个数字')
args = parser.parse_args()
print(sum(args.numbers))
# 输出结果
**python demo.py**                     
0
**python demo.py 2 3 4 5**
14
**python demo.py 1 2 3 4 5 6 7**
28

nargs = ‘+’

'*' 类似,所有当前命令行参数被聚集到一个列表中。另外,当前没有至少一个命令行参数时会产生一个错误信息。

nargs='*' 基本一致,通过 nargs='+' 可以让一个参数接受 1 到多个来自命令行参数的输入。

参数 const

add_argument()const 参数用于保存不从命令行中读取但被各种 ArgumentParser 动作需求的常数值。

通过前面的介绍可以知道,简单来说,const 就是为 action='store_const'action='append_constnargs='?' 服务的。

参数 default

命令行参数未出现时所使用的值(const 值是在命令行参数出现,但命令行参数后面没有给出值是被使用)

参数 type

默认情况下,解析器会将命令行参数当作简单字符串读入。 然而,命令行字符串经常应当被解读为其他类型,例如 floatintadd_argument()type 关键字允许执行任何必要的类型检查和类型转换。

如果 type 关键字使用了 default 关键字,则类型转换器仅会在默认值为字符串时被应用。

传给 type 的参数可以是任何接受单个字符串的可调用对象。 如果函数引发了 ArgumentTypeError, TypeErrorValueError,异常会被捕获并显示经过良好格式化的错误消息。 其他异常类型则不会被处理。

普通内置类型和函数可被用作类型转换器。

参数 choices

参数只能从 choices 给定的值中选择。

例 10:

import argparse

parser = argparse.ArgumentParser(description='命令行中输入一个水果')
# an example of choices
parser.add_argument('-f', '--fruit', choices=['apple', 'orange', 'pear'], help='输入一个水果')
args = parser.parse_args()
print(args.fruit)
# 输出结果
**python demo.py -f apple**
apple
**python demo.py -f watermelon**
usage: demo.py [-h] [-f {apple,orange,pear}]
demo.py: error: argument -f/--fruit: invalid choice: 'watermelon' (choose from 'apple', 'orange', 'pear')

任何容器都可作为 choices 值传入,因此 list 对象,set 对象以及自定义容器都是受支持的。

不建议使用 enum.Enum,因为要控制其在用法、帮助和错误消息中的外观是很困难的。

参数 required

-f, --foo 这样的 flags 默认是可选的,如果指定它们为必选,设置 required=True 即可

必需的选项通常被认为是不适宜的,因为用户会预期 options 都是 可选的,因此在可能的情况下应当避免使用它们。

参数 help

help 值是一个包含参数简短描述的字符串。 当用户请求帮助时(一般是通过在命令行中使用 -h--help 的方式),这些 help 描述将随每个参数一同显示。

如上面的例 10:

# 输出结果
**python demo.py -h**
usage: demo.py [-h] [-f {apple,orange,pear}]

命令行中输入一个水果

optional arguments:
  -h, --help            show this help message and exit
  -f {apple,orange,pear}, --fruit {apple,orange,pear}
                        输入一个水果

help 字符串可包括各种格式描述符以避免重复使用程序名称或参数 default 等文本。 有效的描述符包括程序名称 %(prog)s 和传给 add_argument() 的大部分关键字参数,例如 %(default)s, %(type)s 等等

例 6 第 5 行,与 version 类似。

参数 metavar

ArgumentParser 生成帮助消息时,它需要用某种方式来引用每个预期的参数。 默认情况下,ArgumentParser 对象使用 dest 值作为每个对象的 “name”。 默认情况下,对于位置参数动作,dest 值将被直接使用,而对于可选参数动作,dest 值将被转为大写形式。 因此,一个位置参数 dest='bar' 的引用形式将为 bar。 一个带有单独命令行参数的可选参数 --foo
的引用形式将为 FOO

简单理解,就是用来改变帮助信息的,作用是用 metavar 改变一个参数的替代名称。

例 10的第 5 行加上 metavar=’fruit_name’

parser.add_argument('-f', '--fruit', metavar='fruit_name', choices=['apple', 'orange', 'pear'], help='输入一个水果')

注意与例 10输出结果的区别:

# 输出结果
**python demo.py -h**
usage: demo.py [-h] [-f fruit_name]

命令行中输入一个水果

optional arguments:
  -h, --help            show this help message and exit
  -f fruit_name, --fruit fruit_name
                        输入一个水果

参数 dest

dest 是用来改变参数的属性名称的,什么是参数的属性名称呢,将例 10最后一行改写如下

print(args)

那么输出结果为:

**python demo.py -f apple**
Namespace(fruit='apple')

结果中的‘fruit’即为属性名,不指定 dest 时属性名默认的命名方法是:

  1. 如果有长 flag(前缀为‘- -’的参数),则去掉前缀将 flag 名作为属性名(如‘- -fruit’转化为属性名为‘fruit’)。
  2. 如果没有长 flag,将短 flag(前缀为‘-’的参数)去掉前缀,再将 flag 名中所有的 ‘-’ 替换成 ‘_’

作为属性名(如‘-first-num’转化为属性名为‘first_name’)。

例 10的第 5 行加上 dest=’fruit_name’

print(args)

的结果将变为:

**python demo.py -f apple**
Namespace(fruit_name='apple')

你可能感兴趣的:(Python,python,linux,pycharm)