# 15.4. `argparse` — 命令行选项、参数和子命令解析器

2.7 新版功能.

源代码： Lib/argparse.py

`argparse` 模块可以让人轻松编写用户友好的命令行接口。程序定义它需要的参数，然后 `argparse` 将弄清如何从 `sys.argv` 解析出那些参数。 `argparse` 模块还会自动生成帮助和使用手册，并在用户给程序传入无效参数时报出错误信息。

## 15.4.1. 示例

以下代码是一个 Python 程序，它获取一个整数列表并计算总和或者最大值：

    import argparse

    parser = argparse.ArgumentParser(description='Process some integers.')
    parser.add_argument('integers', metavar='N', type=int, nargs='+',
                        help='an integer for the accumulator')
    parser.add_argument('--sum', dest='accumulate', action='store_const',
                        const=sum, default=max,
                        help='sum the integers (default: find the max)')

    args = parser.parse_args()
    print args.accumulate(args.integers)

假设上面的 Python 代码保存在名为 `prog.py` 的文件中，它可以在命令行运行并提供有用的帮助信息：

    $ python prog.py -h
    usage: prog.py [-h] [--sum] N [N ...]

    Process some integers.

    positional arguments:
     N           an integer for the accumulator

    optional arguments:
     -h, --help  show this help message and exit
     --sum       sum the integers (default: find the max)

当使用适当的参数运行时，它会输出命令行传入整数的总和或者最大值：

    $ python prog.py 1 2 3 4
    4

    $ python prog.py 1 2 3 4 --sum
    10

如果传入无效参数，则会报出错误：

    $ python prog.py a b c
    usage: prog.py [-h] [--sum] N [N ...]
    prog.py: error: argument N: invalid int value: 'a'

以下部分将引导你完成这个示例。

### 15.4.1.1. 创建一个解析器

使用 `argparse` 的第一步是创建一个 `ArgumentParser` 对象：

    >>> parser = argparse.ArgumentParser(description='Process some integers.')

`ArgumentParser` 对象包含将命令行解析成 Python 数据类型所需的全部信息。

### 15.4.1.2. 添加参数

给一个 `ArgumentParser` 添加程序参数信息是通过调用 `add_argument()` 方法完成的。通常，这些调用指定 `ArgumentParser` 如何获取命令行字符串并将其转换为对象。这些信息在 `parse_args()` 调用时被存储和使用。例如：

    >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
    ...                     help='an integer for the accumulator')
    >>> parser.add_argument('--sum', dest='accumulate', action='store_const',
    ...                     const=sum, default=max,
    ...                     help='sum the integers (default: find the max)')

然后，调用 `parse_args()` 将返回一个具有 `integers` 和 `accumulate` 两个属性的对象。`integers` 属性将是一个包含一个或多个整数的列表，而 `accumulate` 属性当命令行中指定了 `--sum` 参数时将是 `sum()` 函数，否则则是 `max()` 函数。

### 15.4.1.3. 解析参数

`ArgumentParser` 通过 `parse_args()` 方法解析参数。它将检查命令行，把每个参数转换为适当的类型然后调用相应的操作。在大多数情况下，这意味着一个简单的 `Namespace` 对象将从命令行解析出的属性构建：

    >>> parser.parse_args(['--sum', '7', '-1', '42'])
    Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

在脚本中，通常 `parse_args()` 会被不带参数调用，而 `ArgumentParser` 将自动从 `sys.argv` 中确定命令行参数。

## 15.4.2. ArgumentParser 对象

class `argparse.``ArgumentParser`(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True)

  创建一个新的 `ArgumentParser` 对象。所有的参数都应当作为关键字参数传入。每个参数在下面都有它更详细的描述，但简而言之，它们是：

  - prog - 程序的名称（默认值：`sys.argv[0]`）

  - usage - 描述程序用途的字符串（默认值：从添加到解析器的参数生成）

  - description - 在参数帮助文档之前显示的文本（默认值：无）

  - epilog - 在参数帮助文档之后显示的文本（默认值：无）

  - parents - 一个 `ArgumentParser` 对象的列表，它们的参数也应包含在内

  - formatter_class - 用于自定义帮助文档输出格式的类

  - prefix_chars - 可选参数的前缀字符集合（默认值： ‘-‘）

  - fromfile_prefix_chars - 当需要从文件中读取其他参数时，用于标识文件名的前缀字符集合（默认值： `None`）

  - argument_default - 参数的全局默认值（默认值： `None`）

  - conflict_handler - 解决冲突选项的策略（通常是不必要的）

  - add_help - 为解析器添加一个 `-h/--help` 选项（默认值： `True`）

以下部分描述这些参数如何使用。

### 15.4.2.1. prog

默认情况下，`ArgumentParser` 对象使用 `sys.argv[0]` 来确定如何在帮助消息中显示程序名称。这一默认值几乎总是可取的，因为它将使帮助消息与从命令行调用此程序的方式相匹配。例如，对于有如下代码的名为 `myprogram.py` 的文件：

    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument('--foo', help='foo help')
    args = parser.parse_args()

该程序的帮助信息将显示 `myprogram.py` 作为程序名称（无论程序从何处被调用）：

    $ python myprogram.py --help
    usage: myprogram.py [-h] [--foo FOO]

    optional arguments:
     -h, --help  show this help message and exit
     --foo FOO   foo help
    $ cd ..
    $ python subdir/myprogram.py --help
    usage: myprogram.py [-h] [--foo FOO]

    optional arguments:
     -h, --help  show this help message and exit
     --foo FOO   foo help

要更改这样的默认行为，可以使用 `prog=` 参数为 `ArgumentParser` 指定另一个值：

    >>> parser = argparse.ArgumentParser(prog='myprogram')
    >>> parser.print_help()
    usage: myprogram [-h]

    optional arguments:
     -h, --help  show this help message and exit

需要注意的是，无论是从 `sys.argv[0]` 或是从 `prog=` 参数确定的程序名称，都可以在帮助消息里通过 `%(prog)s` 格式说明符来引用。

    >>> parser = argparse.ArgumentParser(prog='myprogram')
    >>> parser.add_argument('--foo', help='foo of the %(prog)s program')
    >>> parser.print_help()
    usage: myprogram [-h] [--foo FOO]

    optional arguments:
     -h, --help  show this help message and exit
     --foo FOO   foo of the myprogram program

### 15.4.2.2. usage

默认情况下，`ArgumentParser` 根据它包含的参数来构建用法消息：

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('--foo', nargs='?', help='foo help')
    >>> parser.add_argument('bar', nargs='+', help='bar help')
    >>> parser.print_help()
    usage: PROG [-h] [--foo [FOO]] bar [bar ...]

    positional arguments:
     bar          bar help

    optional arguments:
     -h, --help   show this help message and exit
     --foo [FOO]  foo help

可以通过 `usage=` 关键字参数覆盖这一默认消息：

    >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
    >>> parser.add_argument('--foo', nargs='?', help='foo help')
    >>> parser.add_argument('bar', nargs='+', help='bar help')
    >>> parser.print_help()
    usage: PROG [options]

    positional arguments:
     bar          bar help

    optional arguments:
     -h, --help   show this help message and exit
     --foo [FOO]  foo help

在用法消息中可以使用 `%(prog)s` 格式说明符来填入程序名称。

### 15.4.2.3. 描述

大多数对 `ArgumentParser` 构造方法的调用都会使用 `description=` 关键字参数。这个参数简要描述这个程度做什么以及怎么做。在帮助消息中，这个描述会显示在命令行用法字符串和各种参数的帮助消息之间：

    >>> parser = argparse.ArgumentParser(description='A foo that bars')
    >>> parser.print_help()
    usage: argparse.py [-h]

    A foo that bars

    optional arguments:
     -h, --help  show this help message and exit

在默认情况下，description 将被换行以便适应给定的空间。如果想改变这种行为，见 formatter_class 参数。

### 15.4.2.4. epilog

一些程序喜欢在 description 参数后显示额外的对程序的描述。这种文字能够通过给 `ArgumentParser`:: 提供 `epilog=` 参数而被指定。

    >>> parser = argparse.ArgumentParser(
    ...     description='A foo that bars',
    ...     epilog="And that's how you'd foo a bar")
    >>> parser.print_help()
    usage: argparse.py [-h]

    A foo that bars

    optional arguments:
     -h, --help  show this help message and exit

    And that's how you'd foo a bar

和 description 参数一样，`epilog=` text 在默认情况下会换行，但是这种行为能够被调整通过提供 formatter_class 参数给 `ArgumentParse`.

### 15.4.2.5. parents

有些时候，少数解析器会使用同一系列参数。 单个解析器能够通过提供 `parents=` 参数给 `ArgumentParser` 而使用相同的参数而不是重复这些参数的定义。`parents=` 参数使用 `ArgumentParser` 对象的列表，从它们那里收集所有的位置和可选的行为，然后将这写行为加到正在构建的 `ArgumentParser` 对象。

    >>> parent_parser = argparse.ArgumentParser(add_help=False)
    >>> parent_parser.add_argument('--parent', type=int)

    >>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
    >>> foo_parser.add_argument('foo')
    >>> foo_parser.parse_args(['--parent', '2', 'XXX'])
    Namespace(foo='XXX', parent=2)

    >>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
    >>> bar_parser.add_argument('--bar')
    >>> bar_parser.parse_args(['--bar', 'YYY'])
    Namespace(bar='YYY', parent=None)

请注意大多数父解析器会指定 `add_help=False` . 否则， `ArgumentParse` 将会看到两个 `-h/--help` 选项（一个在父参数中一个在子参数中）并且产生一个错误。

注解

你在传``parents=``给那些解析器时必须完全初始化它们。如果你在子解析器之后改变父解析器是，这些改变不会反映在子解析器上。

### 15.4.2.6. formatter_class

`ArgumentParser` objects allow the help formatting to be customized by specifying an alternate formatting class. Currently, there are three such classes:

class `argparse.``RawDescriptionHelpFormatter`
class `argparse.``RawTextHelpFormatter`
class `argparse.``ArgumentDefaultsHelpFormatter`

The first two allow more control over how textual descriptions are displayed, while the last automatically adds information about argument default values.

By default, `ArgumentParser` objects line-wrap the description and epilog texts in command-line help messages:

    >>> parser = argparse.ArgumentParser(
    ...     prog='PROG',
    ...     description='''this description
    ...         was indented weird
    ...             but that is okay''',
    ...     epilog='''
    ...             likewise for this epilog whose whitespace will
    ...         be cleaned up and whose words will be wrapped
    ...         across a couple lines''')
    >>> parser.print_help()
    usage: PROG [-h]

    this description was indented weird but that is okay

    optional arguments:
     -h, --help  show this help message and exit

    likewise for this epilog whose whitespace will be cleaned up and whose words
    will be wrapped across a couple lines

传 `RawDescriptionHelpFormatter` 给 `formatter_class=` 表示 description 和 epilog 已经被正确的格式化了，不能在命令行中被自动换行:

    >>> parser = argparse.ArgumentParser(
    ...     prog='PROG',
    ...     formatter_class=argparse.RawDescriptionHelpFormatter,
    ...     description=textwrap.dedent('''\
    ...         Please do not mess up this text!
    ...         --------------------------------
    ...             I have indented it
    ...             exactly the way
    ...             I want it
    ...         '''))
    >>> parser.print_help()
    usage: PROG [-h]

    Please do not mess up this text!
    --------------------------------
       I have indented it
       exactly the way
       I want it

    optional arguments:
     -h, --help  show this help message and exit

`RawTextHelpFormatter` 保留所有种类文字的空格，包括参数的描述。然而，多重的新行会被替换成一行。如果你想保留多重的空白行，可以在新行之间加空格。

The other formatter class available, `ArgumentDefaultsHelpFormatter`, will add information about the default value of each of the arguments:

    >>> parser = argparse.ArgumentParser(
    ...     prog='PROG',
    ...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
    >>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
    >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
    >>> parser.print_help()
    usage: PROG [-h] [--foo FOO] [bar [bar ...]]

    positional arguments:
     bar         BAR! (default: [1, 2, 3])

    optional arguments:
     -h, --help  show this help message and exit
     --foo FOO   FOO! (default: 42)

### 15.4.2.7. prefix_chars

许多命令行会使用 `-` 当作前缀，比如 `-f/--foo`。如果解析器需要支持不同的或者额外的字符，比如像 `+f` 或者 `/foo` 的选项，可以在参数解析构建器中使用 `prefix_chars=` 参数。

    >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
    >>> parser.add_argument('+f')
    >>> parser.add_argument('++bar')
    >>> parser.parse_args('+f X ++bar Y'.split())
    Namespace(bar='Y', f='X')

The `prefix_chars=` 参数默认使用 `'-'`. 支持一系列字符，但是不包括 `-` ，这样会产生不被允许的 `-f/--foo` 选项。

### 15.4.2.8. fromfile_prefix_chars

有些时候，先举个例子，当处理一个特别长的参数列表的时候，把它存入一个文件中而不是在命令行打出来会很有意义。如果 `fromfile_prefix_chars=` 参数提供给 `ArgumentParser` 构造函数，之后所有类型的字符的参数都会被当成文件处理，并且会被文件包含的参数替代。举个栗子:

    >>> with open('args.txt', 'w') as fp:
    ...     fp.write('-f\nbar')
    >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
    >>> parser.add_argument('-f')
    >>> parser.parse_args(['-f', 'foo', '@args.txt'])
    Namespace(f='bar')

从文件读取的参数在默认情况下必须一个一行（但是可参见 `convert_arg_line_to_args()`）并且它们被视为与命令行上的原始文件引用参数位于同一位置。所以在以上例子中，`['-f', 'foo', '@args.txt']` 的表示和 `['-f', 'foo', '-f', 'bar']` 的表示相同。

`fromfile_prefix_chars=` 参数默认为 `None`，意味着参数不会被当作文件对待。

### 15.4.2.9. argument_default

一般情况下，参数默认会通过设置一个默认到 `add_argument()` 或者调用带一组指定键值对的 `ArgumentParser.set_defaults()` 方法。但是有些时候，为参数指定一个普遍适用的解析器会更有用。这能够通过传输 `argument_default=` 关键词参数给 `ArgumentParser` 来完成。举个栗子，要全局禁止在 `parse_args()` 中创建属性，我们提供 `argument_default=SUPPRESS`:

    >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
    >>> parser.add_argument('--foo')
    >>> parser.add_argument('bar', nargs='?')
    >>> parser.parse_args(['--foo', '1', 'BAR'])
    Namespace(bar='BAR', foo='1')
    >>> parser.parse_args([])
    Namespace()

### 15.4.2.10. conflict_handler

`ArgumentParser` 对象不允许在相同选项字符串下有两种行为。默认情况下， `ArgumentParser` 对象会产生一个异常如果去创建一个正在使用的选项字符串参数。

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-f', '--foo', help='old foo help')
    >>> parser.add_argument('--foo', help='new foo help')
    Traceback (most recent call last):
     ..
    ArgumentError: argument --foo: conflicting option string(s): --foo

有些时候（例如：使用 parents），重写旧的有相同选项字符串的参数会更有用。为了产生这种行为， `'resolve'` 值可以提供给 `ArgumentParser` 的 `conflict_handler=` 参数:

    >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
    >>> parser.add_argument('-f', '--foo', help='old foo help')
    >>> parser.add_argument('--foo', help='new foo help')
    >>> parser.print_help()
    usage: PROG [-h] [-f FOO] [--foo FOO]

    optional arguments:
     -h, --help  show this help message and exit
     -f FOO      old foo help
     --foo FOO   new foo help

注意 `ArgumentParser` 对象只能移除一个行为如果它所有的选项字符串都被重写。所以，在上面的例子中，旧的 `-f/--foo` 行为 回合 `-f` 行为保持一样, 因为只有 `--foo` 选项字符串被重写。

### 15.4.2.11. add_help

默认情况下，ArgumentParser 对象添加一个简单的显示解析器帮助信息的选项。举个栗子，考虑一个名为 `myprogram.py` 的文件包含如下代码:

    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument('--foo', help='foo help')
    args = parser.parse_args()

如果 `-h` or `--help` 在命令行中被提供, 参数解析器帮助信息会打印:

    $ python myprogram.py --help
    usage: myprogram.py [-h] [--foo FOO]

    optional arguments:
     -h, --help  show this help message and exit
     --foo FOO   foo help

有时候可能会需要关闭额外的帮助信息。这可以通过在 `ArgumentParser` 中设置 `add_help=` 参数为 `False` 来实现。

    >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
    >>> parser.add_argument('--foo', help='foo help')
    >>> parser.print_help()
    usage: PROG [--foo FOO]

    optional arguments:
     --foo FOO  foo help

帮助选项一般为 `-h/--help`。如果 `prefix_chars=` 被指定并且没有包含 `-` 字符，在这种情况下， `-h` `--help` 不是有效的选项。此时， `prefix_chars` 的第一个字符将用作帮助选项的前缀。

    >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
    >>> parser.print_help()
    usage: PROG [+h]

    optional arguments:
      +h, ++help  show this help message and exit

## 15.4.3. 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()` 所返回对象上的属性名。

以下部分描述这些参数如何使用。

### 15.4.3.1. name or flags

`add_argument()` 方法必须知道它是否是一个选项，例如 `-f` 或 `--foo`，或是一个位置参数，例如一组文件名。第一个传递给 `add_argument()` 的参数必须是一系列 flags 或者是一个简单的参数名。例如，可以选项可以被这样创建:

    >>> parser.add_argument('-f', '--foo')

而位置参数可以这么创建:

    >>> parser.add_argument('bar')

当 `parse_args()` 被调用，选项会以 `-` 前缀识别，剩下的参数则会被假定为位置参数:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-f', '--foo')
    >>> parser.add_argument('bar')
    >>> parser.parse_args(['BAR'])
    Namespace(bar='BAR', foo=None)
    >>> parser.parse_args(['BAR', '--foo', 'FOO'])
    Namespace(bar='BAR', foo='FOO')
    >>> parser.parse_args(['--foo', 'FOO'])
    usage: PROG [-h] [-f FOO] bar
    PROG: error: too few arguments

### 15.4.3.2. action

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

- `'store'` - 存储参数的值。这是默认的动作。例如:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo')
      >>> parser.parse_args('--foo 1'.split())
      Namespace(foo='1')

- `'store_const'` - 存储被 const 命名参数指定的值。 `'store_const'` 动作通常用在选项中来指定一些标志。例如:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', action='store_const', const=42)
      >>> parser.parse_args(['--foo'])
      Namespace(foo=42)

- `'store_true'` and `'store_false'` - These are special cases of `'store_const'` using for storing the values `True` and `False` respectively. In addition, they create default values of `False` and `True` respectively. For example:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', action='store_true')
      >>> parser.add_argument('--bar', action='store_false')
      >>> parser.add_argument('--baz', action='store_false')
      >>> parser.parse_args('--foo --bar'.split())
      Namespace(bar=False, baz=True, foo=True)

- `'append'` - 存储一个列表，并且将每个参数值追加到列表中。在允许多次使用选项时很有用。例如:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', action='append')
      >>> parser.parse_args('--foo 1 --foo 2'.split())
      Namespace(foo=['1', '2'])

- `'append_const'` - 这存储一个列表，并将 const 命名参数指定的值追加到列表中。（注意 const 命名参数默认为 `None`。）``’append_const’`` 动作一般在多个参数需要在同一列表中存储常数时会有用。例如:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
      >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
      >>> parser.parse_args('--str --int'.split())
      Namespace(types=[<type 'str'>, <type 'int'>])

- `'count'` - 计算一个关键字参数出现的数目或次数。例如，对于一个增长的详情等级来说有用:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--verbose', '-v', action='count')
      >>> parser.parse_args(['-vvv'])
      Namespace(verbose=3)

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

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

      >>> import argparse
      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
      >>> parser.parse_args(['--version'])
      PROG 2.0

您还可以通过传递 Action 子类或实现相同接口的其他对象来指定任意操作。建议的方法是扩展 `Action`，覆盖 `__call__` 方法和可选的 `__init__` 方法。

一个自定义动作的例子:

    >>> class FooAction(argparse.Action):
    ...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
    ...         if nargs is not None:
    ...             raise ValueError("nargs not allowed")
    ...         super(FooAction, self).__init__(option_strings, dest, **kwargs)
    ...     def __call__(self, parser, namespace, values, option_string=None):
    ...         print '%r %r %r' % (namespace, values, option_string)
    ...         setattr(namespace, self.dest, values)
    ...
    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', action=FooAction)
    >>> parser.add_argument('bar', action=FooAction)
    >>> args = parser.parse_args('1 --foo 2'.split())
    Namespace(bar=None, foo=None) '1' None
    Namespace(bar='1', foo=None) '2' '--foo'
    >>> args
    Namespace(bar='1', foo='2')

更多描述，见 `Action`。

### 15.4.3.3. nargs

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

- `N` （一个整数）。命令行中的 `N` 个参数会被聚集到一个列表中。 例如:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', nargs=2)
      >>> parser.add_argument('bar', nargs=1)
      >>> parser.parse_args('c --foo a b'.split())
      Namespace(bar=['c'], foo=['a', 'b'])

  注意 `nargs=1` 会产生一个单元素列表。这和默认的元素本身是不同的。

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

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
      >>> parser.add_argument('bar', nargs='?', default='d')
      >>> parser.parse_args(['XX', '--foo', 'YY'])
      Namespace(bar='XX', foo='YY')
      >>> parser.parse_args(['XX', '--foo'])
      Namespace(bar='XX', foo='c')
      >>> parser.parse_args([])
      Namespace(bar='d', foo='d')

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

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
      ...                     default=sys.stdin)
      >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
      ...                     default=sys.stdout)
      >>> parser.parse_args(['input.txt', 'output.txt'])
      Namespace(infile=<open file 'input.txt', mode 'r' at 0x...>,
                outfile=<open file 'output.txt', mode 'w' at 0x...>)
      >>> parser.parse_args([])
      Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>,
                outfile=<open file '<stdout>', mode 'w' at 0x...>)

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

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', nargs='*')
      >>> parser.add_argument('--bar', nargs='*')
      >>> parser.add_argument('baz', nargs='*')
      >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
      Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

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

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('foo', nargs='+')
      >>> parser.parse_args(['a', 'b'])
      Namespace(foo=['a', 'b'])
      >>> parser.parse_args([])
      usage: PROG [-h] foo [foo ...]
      PROG: error: too few arguments

- `argarse.REMAINDER`。所有剩余的命令行参数被聚集到一个列表中。这通常在从一个命令行功能传递参数到另一个命令行功能中时有用:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('--foo')
      >>> parser.add_argument('command')
      >>> parser.add_argument('args', nargs=argparse.REMAINDER)
      >>> print parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())
      Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')

如果不提供 `nargs` 命名参数，则消耗参数的数目将被 action 决定。通常这意味着单一项目（非列表）消耗单一命令行参数。

### 15.4.3.4. const

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

- 当 `add_argument()` 通过 `action='store_const'` 或 `action='append_const` 调用时。这些动作将 `const` 值添加到 `parse_args()` 返回的对象的属性中。在 action 的描述中查看案例。

- 当 `add_argument()` 通过选项（例如 `-f` 或 `--foo`）调用并且 `nargs='?'` 时。这会创建一个可以跟随零个或一个命令行参数的选项。当解析命令行时，如果选项后没有参数，则将用 `const` 代替。在 nargs 描述中查看案例。

对 `'store_const'` 和 `'append_const'` 动作， `const` 命名参数必须给出。对其他动作，默认为 `None`。

### 15.4.3.5. 默认值

所有选项和一些位置参数可能在命令行中被忽略。`add_argument()` 的命名参数 `default`，默认值为 `None`，指定了在命令行参数未出现时应当使用的值。对于选项， `default` 值在选项未在命令行中出现时使用:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', default=42)
    >>> parser.parse_args(['--foo', '2'])
    Namespace(foo='2')
    >>> parser.parse_args([])
    Namespace(foo=42)

如果 `default` 值是一个字符串，解析器解析此值就像一个命令行参数。特别是，在将属性设置在 `Namespace` 的返回值之前，解析器应用任何提供的 type 转换参数。否则解析器使用原值:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--length', default='10', type=int)
    >>> parser.add_argument('--width', default=10.5, type=int)
    >>> parser.parse_args()
    Namespace(length=10, width=10.5)

对于 nargs 等于 `?` 或 `*` 的位置参数， `default` 值在没有命令行参数出现时使用。

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('foo', nargs='?', default=42)
    >>> parser.parse_args(['a'])
    Namespace(foo='a')
    >>> parser.parse_args([])
    Namespace(foo=42)

Providing `default=argparse.SUPPRESS` causes no attribute to be added if the command-line argument was not present.:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
    >>> parser.parse_args([])
    Namespace()
    >>> parser.parse_args(['--foo', '1'])
    Namespace(foo='1')

### 15.4.3.6. type – 类型

默认情况下，`ArgumentParser` 对象将命令行参数当作简单字符串读入。然而，命令行字符串经常需要被当作其它的类型，比如 `float` 或者 `int`。`add_argument()` 的 `type` 关键词参数允许任何的类型检查和类型转换。一般的内建类型和函数可以直接被 `type` 参数使用。

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('foo', type=int)
    >>> parser.add_argument('bar', type=file)
    >>> parser.parse_args('2 temp.txt'.split())
    Namespace(bar=<open file 'temp.txt', mode 'r' at 0x...>, foo=2)

当 `type` 参数被应用到默认参数时，请参考 default 参数的部分。

To ease the use of various types of files, the argparse module provides the factory FileType which takes the `mode=` and `bufsize=` arguments of the `file` object. For example, `FileType('w')` can be used to create a writable file:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('bar', type=argparse.FileType('w'))
    >>> parser.parse_args(['out.txt'])
    Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)

`type=` can take any callable that takes a single string argument and returns the converted value:

    >>> def perfect_square(string):
    ...     value = int(string)
    ...     sqrt = math.sqrt(value)
    ...     if sqrt != int(sqrt):
    ...         msg = "%r is not a perfect square" % string
    ...         raise argparse.ArgumentTypeError(msg)
    ...     return value
    ...
    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('foo', type=perfect_square)
    >>> parser.parse_args(['9'])
    Namespace(foo=9)
    >>> parser.parse_args(['7'])
    usage: PROG [-h] foo
    PROG: error: argument foo: '7' is not a perfect square

choices 关键词参数可能会使类型检查者更方便的检查一个范围的值。

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('foo', type=int, choices=xrange(5, 10))
    >>> parser.parse_args(['7'])
    Namespace(foo=7)
    >>> parser.parse_args(['11'])
    usage: PROG [-h] {5,6,7,8,9}
    PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)

详情请查阅 choices 段落。

### 15.4.3.7. choices

Some command-line arguments should be selected from a restricted set of values. These can be handled by passing a container object as the choices keyword argument to `add_argument()`. When the command line is parsed, argument values will be checked, and an error message will be displayed if the argument was not one of the acceptable values:

    >>> parser = argparse.ArgumentParser(prog='game.py')
    >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
    >>> parser.parse_args(['rock'])
    Namespace(move='rock')
    >>> parser.parse_args(['fire'])
    usage: game.py [-h] {rock,paper,scissors}
    game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
    'paper', 'scissors')

Note that inclusion in the choices container is checked after any type conversions have been performed, so the type of the objects in the choices container should match the type specified:

    >>> parser = argparse.ArgumentParser(prog='doors.py')
    >>> parser.add_argument('door', type=int, choices=range(1, 4))
    >>> print(parser.parse_args(['3']))
    Namespace(door=3)
    >>> parser.parse_args(['4'])
    usage: doors.py [-h] {1,2,3}
    doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

Any object that supports the `in` operator can be passed as the choices value, so `dict` objects, `set` objects, custom containers, etc. are all supported.

### 15.4.3.8. required

In general, the `argparse` module assumes that flags like `-f` and `--bar` indicate optional arguments, which can always be omitted at the command line. To make an option required, `True` can be specified for the `required=` keyword argument to `add_argument()`:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', required=True)
    >>> parser.parse_args(['--foo', 'BAR'])
    Namespace(foo='BAR')
    >>> parser.parse_args([])
    usage: argparse.py [-h] [--foo FOO]
    argparse.py: error: option --foo is required

As the example shows, if an option is marked as `required`, `parse_args()` will report an error if that option is not present at the command line.

注解

Required options are generally considered bad form because users expect options to be optional, and thus they should be avoided when possible.

### 15.4.3.9. help

The `help` value is a string containing a brief description of the argument. When a user requests help (usually by using `-h` or `--help` at the command line), these `help` descriptions will be displayed with each argument:

    >>> parser = argparse.ArgumentParser(prog='frobble')
    >>> parser.add_argument('--foo', action='store_true',
    ...                     help='foo the bars before frobbling')
    >>> parser.add_argument('bar', nargs='+',
    ...                     help='one of the bars to be frobbled')
    >>> parser.parse_args(['-h'])
    usage: frobble [-h] [--foo] bar [bar ...]

    positional arguments:
     bar     one of the bars to be frobbled

    optional arguments:
     -h, --help  show this help message and exit
     --foo   foo the bars before frobbling

The `help` strings can include various format specifiers to avoid repetition of things like the program name or the argument default. The available specifiers include the program name, `%(prog)s` and most keyword arguments to `add_argument()`, e.g. `%(default)s`, `%(type)s`, etc.:

    >>> parser = argparse.ArgumentParser(prog='frobble')
    >>> parser.add_argument('bar', nargs='?', type=int, default=42,
    ...                     help='the bar to %(prog)s (default: %(default)s)')
    >>> parser.print_help()
    usage: frobble [-h] [bar]

    positional arguments:
     bar     the bar to frobble (default: 42)

    optional arguments:
     -h, --help  show this help message and exit

`argparse` supports silencing the help entry for certain options, by setting the `help` value to `argparse.SUPPRESS`:

    >>> parser = argparse.ArgumentParser(prog='frobble')
    >>> parser.add_argument('--foo', help=argparse.SUPPRESS)
    >>> parser.print_help()
    usage: frobble [-h]

    optional arguments:
      -h, --help  show this help message and exit

### 15.4.3.10. metavar

When `ArgumentParser` generates help messages, it needs some way to refer to each expected argument. By default, ArgumentParser objects use the dest value as the “name” of each object. By default, for positional argument actions, the dest value is used directly, and for optional argument actions, the dest value is uppercased. So, a single positional argument with `dest='bar'` will be referred to as `bar`. A single optional argument `--foo` that should be followed by a single command-line argument will be referred to as `FOO`. An example:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo')
    >>> parser.add_argument('bar')
    >>> parser.parse_args('X --foo Y'.split())
    Namespace(bar='X', foo='Y')
    >>> parser.print_help()
    usage:  [-h] [--foo FOO] bar

    positional arguments:
     bar

    optional arguments:
     -h, --help  show this help message and exit
     --foo FOO

An alternative name can be specified with `metavar`:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', metavar='YYY')
    >>> parser.add_argument('bar', metavar='XXX')
    >>> parser.parse_args('X --foo Y'.split())
    Namespace(bar='X', foo='Y')
    >>> parser.print_help()
    usage:  [-h] [--foo YYY] XXX

    positional arguments:
     XXX

    optional arguments:
     -h, --help  show this help message and exit
     --foo YYY

Note that `metavar` only changes the displayed name - the name of the attribute on the `parse_args()` object is still determined by the dest value.

Different values of `nargs` may cause the metavar to be used multiple times. Providing a tuple to `metavar` specifies a different display for each of the arguments:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-x', nargs=2)
    >>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
    >>> parser.print_help()
    usage: PROG [-h] [-x X X] [--foo bar baz]

    optional arguments:
     -h, --help     show this help message and exit
     -x X X
     --foo bar baz

### 15.4.3.11. dest

Most `ArgumentParser` actions add some value as an attribute of the object returned by `parse_args()`. The name of this attribute is determined by the `dest` keyword argument of `add_argument()`. For positional argument actions, `dest` is normally supplied as the first argument to `add_argument()`:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('bar')
    >>> parser.parse_args(['XXX'])
    Namespace(bar='XXX')

For optional argument actions, the value of `dest` is normally inferred from the option strings. `ArgumentParser` generates the value of `dest` by taking the first long option string and stripping away the initial `--` string. If no long option strings were supplied, `dest` will be derived from the first short option string by stripping the initial `-` character. Any internal `-` characters will be converted to `_` characters to make sure the string is a valid attribute name. The examples below illustrate this behavior:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('-f', '--foo-bar', '--foo')
    >>> parser.add_argument('-x', '-y')
    >>> parser.parse_args('-f 1 -x 2'.split())
    Namespace(foo_bar='1', x='2')
    >>> parser.parse_args('--foo 1 -y 2'.split())
    Namespace(foo_bar='1', x='2')

`dest` allows a custom attribute name to be provided:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', dest='bar')
    >>> parser.parse_args('--foo XXX'.split())
    Namespace(bar='XXX')

### 15.4.3.12. Action classes

Action classes implement the Action API, a callable which returns a callable which processes arguments from the command-line. Any object which follows this API may be passed as the `action` parameter to `add_argument()`.

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

Action objects are used by an ArgumentParser to represent the information needed to parse a single argument from one or more strings from the command line. The Action class must accept the two positional arguments plus any keyword arguments passed to `ArgumentParser.add_argument()` except for the `action` itself.

Instances of Action (or return value of any callable to the `action` parameter) should have attributes “dest”, “option_strings”, “default”, “type”, “required”, “help”, etc. defined. The easiest way to ensure these attributes are defined is to call `Action.__init__`.

Action instances should be callable, so subclasses must override the `__call__` method, which should accept four parameters:

- `parser` - The ArgumentParser object which contains this action.

- `namespace` - The `Namespace` object that will be returned by `parse_args()`. Most actions add an attribute to this object using `setattr()`.

- `values` - The associated command-line arguments, with any type conversions applied. Type conversions are specified with the type keyword argument to `add_argument()`.

- `option_string` - The option string that was used to invoke this action. The `option_string` argument is optional, and will be absent if the action is associated with a positional argument.

The `__call__` method may perform arbitrary actions, but will typically set attributes on the `namespace` based on `dest` and `values`.

## 15.4.4. parse_args() 方法

`ArgumentParser.``parse_args`(args=None, namespace=None)

  Convert argument strings to objects and assign them as attributes of the namespace. Return the populated namespace.

  Previous calls to `add_argument()` determine exactly what objects are created and how they are assigned. See the documentation for `add_argument()` for details.

  - args - List of strings to parse. The default is taken from `sys.argv`.

  - namespace - An object to take the attributes. The default is a new empty `Namespace` object.

### 15.4.4.1. Option value syntax

The `parse_args()` method supports several ways of specifying the value of an option (if it takes one). In the simplest case, the option and its value are passed as two separate arguments:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-x')
    >>> parser.add_argument('--foo')
    >>> parser.parse_args(['-x', 'X'])
    Namespace(foo=None, x='X')
    >>> parser.parse_args(['--foo', 'FOO'])
    Namespace(foo='FOO', x=None)

For long options (options with names longer than a single character), the option and value can also be passed as a single command-line argument, using `=` to separate them:

    >>> parser.parse_args(['--foo=FOO'])
    Namespace(foo='FOO', x=None)

For short options (options only one character long), the option and its value can be concatenated:

    >>> parser.parse_args(['-xX'])
    Namespace(foo=None, x='X')

Several short options can be joined together, using only a single `-` prefix, as long as only the last option (or none of them) requires a value:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-x', action='store_true')
    >>> parser.add_argument('-y', action='store_true')
    >>> parser.add_argument('-z')
    >>> parser.parse_args(['-xyzZ'])
    Namespace(x=True, y=True, z='Z')

### 15.4.4.2. 无效的参数

While parsing the command line, `parse_args()` checks for a variety of errors, including ambiguous options, invalid types, invalid options, wrong number of positional arguments, etc. When it encounters such an error, it exits and prints the error along with a usage message:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('--foo', type=int)
    >>> parser.add_argument('bar', nargs='?')

    >>> # invalid type
    >>> parser.parse_args(['--foo', 'spam'])
    usage: PROG [-h] [--foo FOO] [bar]
    PROG: error: argument --foo: invalid int value: 'spam'

    >>> # invalid option
    >>> parser.parse_args(['--bar'])
    usage: PROG [-h] [--foo FOO] [bar]
    PROG: error: no such option: --bar

    >>> # wrong number of arguments
    >>> parser.parse_args(['spam', 'badger'])
    usage: PROG [-h] [--foo FOO] [bar]
    PROG: error: extra arguments found: badger

### 15.4.4.3. 包含 `-` 的参数

The `parse_args()` method attempts to give errors whenever the user has clearly made a mistake, but some situations are inherently ambiguous. For example, the command-line argument `-1` could either be an attempt to specify an option or an attempt to provide a positional argument. The `parse_args()` method is cautious here: positional arguments may only begin with `-` if they look like negative numbers and there are no options in the parser that look like negative numbers:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-x')
    >>> parser.add_argument('foo', nargs='?')

    >>> # no negative number options, so -1 is a positional argument
    >>> parser.parse_args(['-x', '-1'])
    Namespace(foo=None, x='-1')

    >>> # no negative number options, so -1 and -5 are positional arguments
    >>> parser.parse_args(['-x', '-1', '-5'])
    Namespace(foo='-5', x='-1')

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-1', dest='one')
    >>> parser.add_argument('foo', nargs='?')

    >>> # negative number options present, so -1 is an option
    >>> parser.parse_args(['-1', 'X'])
    Namespace(foo=None, one='X')

    >>> # negative number options present, so -2 is an option
    >>> parser.parse_args(['-2'])
    usage: PROG [-h] [-1 ONE] [foo]
    PROG: error: no such option: -2

    >>> # negative number options present, so both -1s are options
    >>> parser.parse_args(['-1', '-1'])
    usage: PROG [-h] [-1 ONE] [foo]
    PROG: error: argument -1: expected one argument

If you have positional arguments that must begin with `-` and don’t look like negative numbers, you can insert the pseudo-argument `'--'` which tells `parse_args()` that everything after that is a positional argument:

    >>> parser.parse_args(['--', '-f'])
    Namespace(foo='-f', one=None)

### 15.4.4.4. 参数缩写（前缀匹配）

The `parse_args()` method allows long options to be abbreviated to a prefix, if the abbreviation is unambiguous (the prefix matches a unique option):

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-bacon')
    >>> parser.add_argument('-badger')
    >>> parser.parse_args('-bac MMM'.split())
    Namespace(bacon='MMM', badger=None)
    >>> parser.parse_args('-bad WOOD'.split())
    Namespace(bacon=None, badger='WOOD')
    >>> parser.parse_args('-ba BA'.split())
    usage: PROG [-h] [-bacon BACON] [-badger BADGER]
    PROG: error: ambiguous option: -ba could match -badger, -bacon

An error is produced for arguments that could produce more than one options.

### 15.4.4.5. Beyond `sys.argv`

Sometimes it may be useful to have an ArgumentParser parse arguments other than those of `sys.argv`. This can be accomplished by passing a list of strings to `parse_args()`. This is useful for testing at the interactive prompt:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument(
    ...     'integers', metavar='int', type=int, choices=xrange(10),
    ...     nargs='+', help='an integer in the range 0..9')
    >>> parser.add_argument(
    ...     '--sum', dest='accumulate', action='store_const', const=sum,
    ...     default=max, help='sum the integers (default: find the max)')
    >>> parser.parse_args(['1', '2', '3', '4'])
    Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
    >>> parser.parse_args(['1', '2', '3', '4', '--sum'])
    Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])

### 15.4.4.6. 命名空间对象

class `argparse.``Namespace`

  Simple class used by default by `parse_args()` to create an object holding attributes and return it.

This class is deliberately simple, just an `object` subclass with a readable string representation. If you prefer to have dict-like view of the attributes, you can use the standard Python idiom, `vars()`:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo')
    >>> args = parser.parse_args(['--foo', 'BAR'])
    >>> vars(args)
    {'foo': 'BAR'}

It may also be useful to have an `ArgumentParser` assign attributes to an already existing object, rather than a new `Namespace` object. This can be achieved by specifying the `namespace=` keyword argument:

    >>> class C(object):
    ...     pass
    ...
    >>> c = C()
    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo')
    >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
    >>> c.foo
    'BAR'

## 15.4.5. 其它实用工具

### 15.4.5.1. 子命令

`ArgumentParser.``add_subparsers`([title][, description][, prog][, parser_class][, action][, option_string][, dest][, help][, metavar])

  Many programs split up their functionality into a number of sub-commands, for example, the `svn` program can invoke sub-commands like `svn checkout`, `svn update`, and `svn commit`. Splitting up functionality this way can be a particularly good idea when a program performs several different functions which require different kinds of command-line arguments. `ArgumentParser` supports the creation of such sub-commands with the `add_subparsers()` method. The `add_subparsers()` method is normally called with no arguments and returns a special action object. This object has a single method, `add_parser()`, which takes a command name and any `ArgumentParser` constructor arguments, and returns an `ArgumentParser` object that can be modified as usual.

  形参的描述

  - title - title for the sub-parser group in help output; by default “subcommands” if description is provided, otherwise uses title for positional arguments

  - description - description for the sub-parser group in help output, by default `None`

  - prog - usage information that will be displayed with sub-command help, by default the name of the program and any positional arguments before the subparser argument

  - parser_class - class which will be used to create sub-parser instances, by default the class of the current parser (e.g. ArgumentParser)

  - action - the basic type of action to be taken when this argument is encountered at the command line

  - dest - name of the attribute under which sub-command name will be stored; by default `None` and no value is stored

  - help - help for sub-parser group in help output, by default `None`

  - metavar - string presenting available sub-commands in help; by default it is `None` and presents sub-commands in form {cmd1, cmd2, ..}

  一些使用示例:

      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('--foo', action='store_true', help='foo help')
      >>> subparsers = parser.add_subparsers(help='sub-command help')
      >>>
      >>> # create the parser for the "a" command
      >>> parser_a = subparsers.add_parser('a', help='a help')
      >>> parser_a.add_argument('bar', type=int, help='bar help')
      >>>
      >>> # create the parser for the "b" command
      >>> parser_b = subparsers.add_parser('b', help='b help')
      >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
      >>>
      >>> # parse some argument lists
      >>> parser.parse_args(['a', '12'])
      Namespace(bar=12, foo=False)
      >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
      Namespace(baz='Z', foo=True)

  Note that the object returned by `parse_args()` will only contain attributes for the main parser and the subparser that was selected by the command line (and not any other subparsers). So in the example above, when the `a` command is specified, only the `foo` and `bar` attributes are present, and when the `b` command is specified, only the `foo` and `baz` attributes are present.

  Similarly, when a help message is requested from a subparser, only the help for that particular parser will be printed. The help message will not include parent parser or sibling parser messages. (A help message for each subparser command, however, can be given by supplying the `help=` argument to `add_parser()` as above.)

      >>> parser.parse_args(['--help'])
      usage: PROG [-h] [--foo] {a,b} ...

      positional arguments:
        {a,b}   sub-command help
          a     a help
          b     b help

      optional arguments:
        -h, --help  show this help message and exit
        --foo   foo help

      >>> parser.parse_args(['a', '--help'])
      usage: PROG a [-h] bar

      positional arguments:
        bar     bar help

      optional arguments:
        -h, --help  show this help message and exit

      >>> parser.parse_args(['b', '--help'])
      usage: PROG b [-h] [--baz {X,Y,Z}]

      optional arguments:
        -h, --help     show this help message and exit
        --baz {X,Y,Z}  baz help

  The `add_subparsers()` method also supports `title` and `description` keyword arguments. When either is present, the subparser’s commands will appear in their own group in the help output. For example:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(title='subcommands',
      ...                                    description='valid subcommands',
      ...                                    help='additional help')
      >>> subparsers.add_parser('foo')
      >>> subparsers.add_parser('bar')
      >>> parser.parse_args(['-h'])
      usage:  [-h] {foo,bar} ...

      optional arguments:
        -h, --help  show this help message and exit

      subcommands:
        valid subcommands

        {foo,bar}   additional help

  One particularly effective way of handling sub-commands is to combine the use of the `add_subparsers()` method with calls to `set_defaults()` so that each subparser knows which Python function it should execute. For example:

      >>> # sub-command functions
      >>> def foo(args):
      ...     print args.x * args.y
      ...
      >>> def bar(args):
      ...     print '((%s))' % args.z
      ...
      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers()
      >>>
      >>> # create the parser for the "foo" command
      >>> parser_foo = subparsers.add_parser('foo')
      >>> parser_foo.add_argument('-x', type=int, default=1)
      >>> parser_foo.add_argument('y', type=float)
      >>> parser_foo.set_defaults(func=foo)
      >>>
      >>> # create the parser for the "bar" command
      >>> parser_bar = subparsers.add_parser('bar')
      >>> parser_bar.add_argument('z')
      >>> parser_bar.set_defaults(func=bar)
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('foo 1 -x 2'.split())
      >>> args.func(args)
      2.0
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('bar XYZYX'.split())
      >>> args.func(args)
      ((XYZYX))

  This way, you can let `parse_args()` do the job of calling the appropriate function after argument parsing is complete. Associating functions with actions like this is typically the easiest way to handle the different actions for each of your subparsers. However, if it is necessary to check the name of the subparser that was invoked, the `dest` keyword argument to the `add_subparsers()` call will work:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(dest='subparser_name')
      >>> subparser1 = subparsers.add_parser('1')
      >>> subparser1.add_argument('-x')
      >>> subparser2 = subparsers.add_parser('2')
      >>> subparser2.add_argument('y')
      >>> parser.parse_args(['2', 'frobble'])
      Namespace(subparser_name='2', y='frobble')

### 15.4.5.2. FileType 对象

class `argparse.``FileType`(mode='r', bufsize=None)

  The `FileType` factory creates objects that can be passed to the type argument of `ArgumentParser.add_argument()`. Arguments that have `FileType` objects as their type will open command-line arguments as files with the requested modes and buffer sizes:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--output', type=argparse.FileType('wb', 0))
      >>> parser.parse_args(['--output', 'out'])
      Namespace(output=<open file 'out', mode 'wb' at 0x...>)

  FileType objects understand the pseudo-argument `'-'` and automatically convert this into `sys.stdin` for readable `FileType` objects and `sys.stdout` for writable `FileType` objects:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('infile', type=argparse.FileType('r'))
      >>> parser.parse_args(['-'])
      Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>)

### 15.4.5.3. 参数组

`ArgumentParser.``add_argument_group`(title=None, description=None)

  By default, `ArgumentParser` groups command-line arguments into “positional arguments” and “optional arguments” when displaying help messages. When there is a better conceptual grouping of arguments than this default one, appropriate groups can be created using the `add_argument_group()` method:

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group = parser.add_argument_group('group')
      >>> group.add_argument('--foo', help='foo help')
      >>> group.add_argument('bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--foo FOO] bar

      group:
        bar    bar help
        --foo FOO  foo help

  The `add_argument_group()` method returns an argument group object which has an `add_argument()` method just like a regular `ArgumentParser`. When an argument is added to the group, the parser treats it just like a normal argument, but displays the argument in a separate group for help messages. The `add_argument_group()` method accepts title and description arguments which can be used to customize this display:

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group1 = parser.add_argument_group('group1', 'group1 description')
      >>> group1.add_argument('foo', help='foo help')
      >>> group2 = parser.add_argument_group('group2', 'group2 description')
      >>> group2.add_argument('--bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--bar BAR] foo

      group1:
        group1 description

        foo    foo help

      group2:
        group2 description

        --bar BAR  bar help

  Note that any arguments not in your user-defined groups will end up back in the usual “positional arguments” and “optional arguments” sections.

### 15.4.5.4. Mutual exclusion

`ArgumentParser.``add_mutually_exclusive_group`(required=False)

  创建一个互斥组。 `argparse` 将会确保互斥组中只有一个参数在命令行中可用:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group()
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args(['--foo'])
      Namespace(bar=True, foo=True)
      >>> parser.parse_args(['--bar'])
      Namespace(bar=False, foo=False)
      >>> parser.parse_args(['--foo', '--bar'])
      usage: PROG [-h] [--foo | --bar]
      PROG: error: argument --bar: not allowed with argument --foo

  `add_mutually_exclusive_group()` 方法也接受一个 required 参数，表示在互斥组中至少有一个参数是需要的:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group(required=True)
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args([])
      usage: PROG [-h] (--foo | --bar)
      PROG: error: one of the arguments --foo --bar is required

  注意，目前互斥参数组不支持 `add_argument_group()` 的 title 和 description 参数。

### 15.4.5.5. Parser defaults

`ArgumentParser.``set_defaults`(**kwargs)

  Most of the time, the attributes of the object returned by `parse_args()` will be fully determined by inspecting the command-line arguments and the argument actions. `set_defaults()` allows some additional attributes that are determined without any inspection of the command line to be added:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('foo', type=int)
      >>> parser.set_defaults(bar=42, baz='badger')
      >>> parser.parse_args(['736'])
      Namespace(bar=42, baz='badger', foo=736)

  Note that parser-level defaults always override argument-level defaults:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='bar')
      >>> parser.set_defaults(foo='spam')
      >>> parser.parse_args([])
      Namespace(foo='spam')

  Parser-level defaults can be particularly useful when working with multiple parsers. See the `add_subparsers()` method for an example of this type.

`ArgumentParser.``get_default`(dest)

  Get the default value for a namespace attribute, as set by either `add_argument()` or by `set_defaults()`:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='badger')
      >>> parser.get_default('foo')
      'badger'

### 15.4.5.6. 打印帮助

In most typical applications, `parse_args()` will take care of formatting and printing any usage or error messages. However, several formatting methods are available:

`ArgumentParser.``print_usage`(file=None)

  Print a brief description of how the `ArgumentParser` should be invoked on the command line. If file is `None`, `sys.stdout` is assumed.

`ArgumentParser.``print_help`(file=None)

  Print a help message, including the program usage and information about the arguments registered with the `ArgumentParser`. If file is `None`, `sys.stdout` is assumed.

There are also variants of these methods that simply return a string instead of printing it:

`ArgumentParser.``format_usage`()

  Return a string containing a brief description of how the `ArgumentParser` should be invoked on the command line.

`ArgumentParser.``format_help`()

  Return a string containing a help message, including the program usage and information about the arguments registered with the `ArgumentParser`.

### 15.4.5.7. Partial parsing

`ArgumentParser.``parse_known_args`(args=None, namespace=None)

Sometimes a script may only parse a few of the command-line arguments, passing the remaining arguments on to another script or program. In these cases, the `parse_known_args()` method can be useful. It works much like `parse_args()` except that it does not produce an error when extra arguments are present. Instead, it returns a two item tuple containing the populated namespace and the list of remaining argument strings.

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', action='store_true')
    >>> parser.add_argument('bar')
    >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
    (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

警告

Prefix matching rules apply to `parse_known_args()`. The parser may consume an option even if it’s just a prefix of one of its known options, instead of leaving it in the remaining arguments list.

### 15.4.5.8. 自定义文件解析

`ArgumentParser.``convert_arg_line_to_args`(arg_line)

  Arguments that are read from a file (see the fromfile_prefix_chars keyword argument to the `ArgumentParser` constructor) are read one argument per line. `convert_arg_line_to_args()` can be overridden for fancier reading.

  This method takes a single argument arg_line which is a string read from the argument file. It returns a list of arguments parsed from this string. The method is called once per line read from the argument file, in order.

  A useful override of this method is one that treats each space-separated word as an argument:

      def convert_arg_line_to_args(self, arg_line):
          return arg_line.split()

### 15.4.5.9. 退出方法

`ArgumentParser.``exit`(status=0, message=None)

  This method terminates the program, exiting with the specified status and, if given, it prints a message before that.

`ArgumentParser.``error`(message)

  This method prints a usage message including the message to the standard error and terminates the program with a status code of 2.

## 15.4.6. 升级 optparse 代码

Originally, the `argparse` module had attempted to maintain compatibility with `optparse`. However, `optparse` was difficult to extend transparently, particularly with the changes required to support the new `nargs=` specifiers and better usage messages. When most everything in `optparse` had either been copy-pasted over or monkey-patched, it no longer seemed practical to try to maintain the backwards compatibility.

The `argparse` module improves on the standard library `optparse` module in a number of ways including:

- 处理位置参数。

- 支持子命令。

- Allowing alternative option prefixes like `+` and `/`.

- Handling zero-or-more and one-or-more style arguments.

- Producing more informative usage messages.

- Providing a much simpler interface for custom `type` and `action`.

A partial upgrade path from `optparse` to `argparse`:

- Replace all `optparse.OptionParser.add_option()` calls with `ArgumentParser.add_argument()` calls.

- Replace `(options, args) = parser.parse_args()` with `args = parser.parse_args()` and add additional `ArgumentParser.add_argument()` calls for the positional arguments. Keep in mind that what was previously called `options`, now in the `argparse` context is called `args`.

- Replace `optparse.OptionParser.disable_interspersed_args()` by setting `nargs` of a positional argument to argparse.REMAINDER, or use `parse_known_args()` to collect unparsed argument strings in a separate list.

- Replace callback actions and the `callback_*` keyword arguments with `type` or `action` arguments.

- Replace string names for `type` keyword arguments with the corresponding type objects (e.g. int, float, complex, etc).

- Replace `optparse.Values` with `Namespace` and `optparse.OptionError` and `optparse.OptionValueError` with `ArgumentError`.

- Replace strings with implicit arguments such as `%default` or `%prog` with the standard Python syntax to use dictionaries to format strings, that is, `%(default)s` and `%(prog)s`.

- Replace the OptionParser constructor `version` argument with a call to `parser.add_argument('--version', action='version', version='<the version>')`.