【Python】argparse - 命令行选项、参数和子命令解析器

• 一. 介绍
• 二. API
  • 2.1 位置参数
  • 2.2 可选参数
  • 2.3 短参数
  • 2.4 冗长参数
    • 2.4.1 不定参数
    • 2.4.2 计数参数
  • 2.5 区间参数
  • 2.6 互斥参数
  • 2.7 nargs 值类型
  • 2.8 Action 值类型
  • 2.9 const 参数类型
  • 2.10 choices 参数类型
  • 2.11 metavar 参数类型
  • 2.12 dest 参数类型
• 三. 说明与引用
• 四. 参考

一. 介绍

argparse 模块可以让人轻松编写用户友好的命令行接口。程序定义它需要的参数，然后 argparse 将弄清如何从 sys.argv 解析出那些参数。

argparse 模块还会自动生成帮助和使用手册，并在用户给程序传入无效参数时报出错误信息。

二. API

定义单个的命令行参数应当如何解析。每个形参都在下面有它自己更多的描述，长话短说有：

name or flags - 一个命名或者一个选项字符串的列表，例如 foo 或 -f, --foo。
action - 当参数在命令行中出现时使用的动作基本类型。
nargs - 命令行参数应当消耗的数目。
const - 被一些 action 和 nargs 选择所需求的常数。
default - 当参数未在命令行中出现时使用的值。
type - 命令行参数应当被转换成的类型。
choices - 可用的参数的容器。
required - 此命令行选项是否可省略(仅选项可用)。
help - 一个此选项作用的简单描述。
metavar - 在使用方法消息中使用的参数值示例。
dest - 被添加到 parse_args() 所返回对象上的属性名。

常用参数类型有如下几种:

*name_or_flags
action
nargs
const
default
type
choices
required
help
metavar
dest
version
**kwargs

2.1 位置参数

import argparse

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

2.2 可选参数

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--verbose", action="store_true",
                    help="increase output verbosity")
args = parser.parse_args()

2.3 短参数

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("-v", "--verbose", action="store_true",
                    help="increase output verbosity")
args = parser.parse_args()

2.4 冗长参数

2.4.1 不定参数

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("-v", "--verbosity", type=int,
                    help="increase output verbosity")
args = parser.parse_args()

2.4.2 计数参数

import argparse

parser = argparse.ArgumentParser()
# parser.add_argument("-v", "--verbosity", action="count",
#                     help="increase output verbosity")
parser.add_argument("-v", "--verbosity", action="count", default=0,
                    help="increase output verbosity")
args = parser.parse_args()

2.5 区间参数

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("-v", "--verbosity", type=int, choices=[0, 1, 2],
                    help="increase output verbosity")
args = parser.parse_args()

2.6 互斥参数

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()

2.7 nargs 值类型

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

1. N: 一个正整数, 命令行中的 N 个参数会被聚集到一个列表中
2. ?: 会从命令行中消耗一个参数，并产生一个单一项。如果当前没有命令行参数，则会产生 default 值。nargs='?' 的一个更普遍用法是允许可选的输入或输出文件;
3. *: 所有当前命令行参数被聚集到一个列表中。注意通过 nargs='*' 来实现多个位置参数通常没有意义，但是多个选项是可能的。
4. +: 和 * 类似，所有当前命令行参数被聚集到一个列表中。另外，当前没有至少一个命令行参数时会产生一个错误信息;
5. argarse.REMAINDER: 所有剩余的命令行参数被聚集到一个列表中。这通常在从一个命令行功能传递参数到另一个命令行功能中时有用;
6. 如果不提供 nargs 命名参数，则消耗参数的数目将被 action 决定。通常这意味着单一项目（非列表）消耗单一命令行参数;

2.8 Action 值类型

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

常见的参数类型，有如下几种:

2.9 const 参数类型

1. const 参数用于保存不从命令行中读取但被各种 ArgumentParser 动作需求的常数值;
2. 对 store_const 和 append_const 动作， const 命名参数必须给出。对其他动作，默认为 None;

2.10 choices 参数类型

1. 某些命令行参数应当从一组受限值中选择。 这可通过将一个容器对象作为 choices 关键字参数传给 add_argument() 来处理。 当执行命令行解析时，参数值将被检查，如果参数不是可接受的值之一就将显示错误消息;
2. 请注意 choices 容器包含的内容会在执行任意 type 转换之后被检查，因此 choices 容器中对象的类型应当与指定的 type 相匹配;

2.11 metavar 参数类型

1. 当 ArgumentParser 生成帮助消息时，它需要用某种方式来引用每个预期的参数;
2. 默认情况下，ArgumentParser 对象使用 dest 值作为每个对象的 “name”;
3. 默认情况下，对于位置参数动作，dest 值将被直接使用，而对于可选参数动作，dest 值将被转为大写形式;
4. 可以使用 metavar 来指定一个替代名称; metavar 仅改变 显示的名称 - parse_args() 对象的属性名称仍然会由 dest 值确定;
5. 不同的 nargs 值可能导致 metavar 被多次使用;

2.12 dest 参数类型

1. 大多数 ArgumentParser 动作会添加一些值作为 parse_args() 所返回对象的一个属性。 该属性的名称由 add_argument() 的 dest 关键字参数确定;
2. 对于位置参数动作，dest 通常会作为 add_argument() 的第一个参数提供;
3. 对于可选参数动作，dest 的值通常取自选项字符串。
4. dest 允许提供自定义属性名称；

三. 说明与引用

1. argparse 会把我们传递给它的选项视作为字符串，除非我们告诉它别这样;
2. 当程序在收到错误的无效的输入时，它甚至能在执行之前先退出，还能显示很有帮助的错误信息。
3. 使用可选参数选项时，必须指定一个值，但可以是任何值。
4. 默认情况下如果一个可选参数没有被指定，它的值会是 None，并且它不能和整数值相比较(会产生 TypeError 异常)。
5. 无论是从 sys.argv[0] 或是从 prog= 参数确定的程序名称，都可以在帮助消息里通过 %(prog)s 格式说明符来引用。
6. 可以通过 usage= 关键字参数覆盖默认消息;
7. 大多数对 ArgumentParser 构造方法的调用都会使用 description= 关键字参数。这个参数简要描述这个程度做什么以及怎么做。在帮助消息中，这个描述会显示在命令行用法字符串和各种参数的帮助消息之间; 在默认情况下，description 将被换行以便适应给定的空间。
8. 一些程序喜欢在 description 参数后显示额外的对程序的描述。这种文字能够通过给 ArgumentParser:: 提供 epilog= 参数而被指定。和 description 参数一样，epilog=text 在默认情况下会换行，但是这种行为能够被调整通过提供 formatter_class 参数给 ArgumentParse;
9. 请注意大多数父解析器会指定 add_help=False; 否则， ArgumentParse 将会看到两个 -h/--help 选项(一个在父参数中一个在子参数中)并且产生一个错误。
10. type 关键词参数允许任何的类型检查和类型转换。一般的内建类型和函数可以直接被 type 参数使用。
11. choices 关键词参数可能会使类型检查者更方便的检查一个范围的值。
12. 要让一个选项成为 必需的，则可以将 True 作为 required= 关键字参数传给 add_argument();
13. 如果一个选项被标记为 required，则当该选项未在命令行中出现时，parse_args() 将会报告一个错误;
14. 必需的选项通常被认为是不适宜的，因为用户会预期 options 都是可选的，因此在可能的情况下应当避免使用它们。
15. argparse 支持静默特定选项的帮助，具体做法是将 help 的值设为 argparse.SUPPRESS;

四. 参考

1. https://docs.python.org/zh-cn/2.7/howto/argparse.html
2. https://docs.python.org/zh-cn/2.7/library/argparse.html
3. https://docs.python.org/zh-cn/3/howto/argparse.html
4. https://docs.python.org/zh-cn/3/library/argparse.html