set svn:eol-style
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 78922b1..750e819 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1,1758 +1,1758 @@
-:mod:`argparse` -- Parser for command line options, arguments and sub-commands
-==============================================================================
-
-.. module:: argparse
- :synopsis: Command-line option and argument parsing library.
-.. moduleauthor:: Steven Bethard <steven.bethard@gmail.com>
-.. versionadded:: 2.7
-.. sectionauthor:: Steven Bethard <steven.bethard@gmail.com>
-
-
-The :mod:`argparse` module makes it easy to write user friendly command line
-interfaces. You define what arguments your program requires, and
-:mod:`argparse` will figure out how to parse those out of ``sys.argv``. The
-:mod:`argparse` module also automatically generates help and usage messages
-based on the arguments you have defined, and issues errors when users give your
-program invalid arguments.
-
-Example
--------
-
-As an example, the following code is a Python program that takes a list of
-integers and produces either the sum or the max::
-
- 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)
-
-Assuming the Python code above is saved into a file called ``prog.py``, it can
-be run at the command line and provides useful help messages::
-
- $ 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)
-
-When run with the appropriate arguments, it prints either the sum or the max of
-the command-line integers::
-
- $ prog.py 1 2 3 4
- 4
-
- $ prog.py 1 2 3 4 --sum
- 10
-
-If invalid arguments are passed in, it will issue an error::
-
- $ prog.py a b c
- usage: prog.py [-h] [--sum] N [N ...]
- prog.py: error: argument N: invalid int value: 'a'
-
-The following sections walk you through this example.
-
-Creating a parser
-^^^^^^^^^^^^^^^^^
-
-Pretty much every script that uses the :mod:`argparse` module will start out by
-creating an :class:`ArgumentParser` object::
-
- >>> parser = argparse.ArgumentParser(description='Process some integers.')
-
-The :class:`ArgumentParser` object will hold all the information necessary to
-parse the command line into a more manageable form for your program.
-
-
-Adding arguments
-^^^^^^^^^^^^^^^^
-
-Once you've created an :class:`ArgumentParser`, you'll want to fill it with
-information about your program arguments. You typically do this by making calls
-to the :meth:`add_argument` method. Generally, these calls tell the
-:class:`ArgumentParser` how to take the strings on the command line and turn
-them into objects for you. This information is stored and used when
-:meth:`parse_args` is called. For example, if we add some arguments like this::
-
- >>> 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)')
-
-when we later call :meth:`parse_args`, we can expect it to return an object
-with two attributes, ``integers`` and ``accumulate``. The ``integers``
-attribute will be a list of one or more ints, and the ``accumulate`` attribute
-will be either the ``sum`` function, if ``--sum`` was specified at the command
-line, or the ``max`` function if it was not.
-
-Parsing arguments
-^^^^^^^^^^^^^^^^^
-
-Once an :class:`ArgumentParser` has been initialized with appropriate calls to
-:meth:`add_argument`, it can be instructed to parse the command-line args by
-calling the :meth:`parse_args` method. This will inspect the command-line,
-convert each arg to the appropriate type and then invoke the appropriate
-action. In most cases, this means a simple namespace object will be built up
-from attributes parsed out of the command-line::
-
- >>> parser.parse_args(['--sum', '7', '-1', '42'])
- Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
-
-In a script, :meth:`parse_args` will typically be called with no arguments, and
-the :class:`ArgumentParser` will automatically determine the command-line args
-from ``sys.argv``. That's pretty much it. You're now ready to go write some
-command line interfaces!
-
-
-ArgumentParser objects
-----------------------
-
-.. class:: ArgumentParser([description], [epilog], [prog], [usage], [add_help], [argument_default], [parents], [prefix_chars], [conflict_handler], [formatter_class])
-
- Create a new :class:`ArgumentParser` object. Each parameter has its own more
- detailed description below, but in short they are:
-
- * description_ - Text to display before the argument help.
-
- * epilog_ - Text to display after the argument help.
-
- * add_help_ - Add a -h/--help option to the parser. (default: True)
-
- * argument_default_ - Set the global default value for arguments.
- (default: None)
-
- * parents_ - A list of :class:ArgumentParser objects whose arguments should
- also be included.
-
- * prefix_chars_ - The set of characters that prefix optional arguments.
- (default: '-')
-
- * fromfile_prefix_chars_ - The set of characters that prefix files from
- which additional arguments should be read. (default: None)
-
- * formatter_class_ - A class for customizing the help output.
-
- * conflict_handler_ - Usually unnecessary, defines strategy for resolving
- conflicting optionals.
-
- * prog_ - Usually unnecessary, the name of the program
- (default: ``sys.argv[0]``)
-
- * usage_ - Usually unnecessary, the string describing the program usage
- (default: generated)
-
- The following sections describe how each of these are used.
-
-
-description
-^^^^^^^^^^^
-
-Most calls to the ArgumentParser constructor will use the ``description=``
-keyword argument. This argument gives a brief description of what the program
-does and how it works. In help messages, the description is displayed between
-the command-line usage string and the help messages for the various arguments::
-
- >>> 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
-
-By default, the description will be line-wrapped so that it fits within the
-given space. To change this behavior, see the formatter_class_ argument.
-
-
-epilog
-^^^^^^
-
-Some programs like to display additional description of the program after the
-description of the arguments. Such text can be specified using the ``epilog=``
-argument to ArgumentParser::
-
- >>> 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
-
-As with the description_ argument, the ``epilog=`` text is by default
-line-wrapped, but this behavior can be adjusted with the formatter_class_
-argument to ArgumentParser.
-
-
-add_help
-^^^^^^^^
-
-By default, ArgumentParser objects add a ``-h/--help`` option which simply
-displays the parser's help message. For example, consider a file named
-``myprogram.py`` containing the following code::
-
- import argparse
- parser = argparse.ArgumentParser()
- parser.add_argument('--foo', help='foo help')
- args = parser.parse_args()
-
-If ``-h`` or ``--help`` is supplied is at the command-line, the ArgumentParser
-help will be printed::
-
- $ python myprogram.py --help
- usage: myprogram.py [-h] [--foo FOO]
-
- optional arguments:
- -h, --help show this help message and exit
- --foo FOO foo help
-
-Occasionally, it may be useful to disable the addition of this help option.
-This can be achieved by passing ``False`` as the ``add_help=`` argument to
-ArgumentParser::
-
- >>> 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
-
-
-prefix_chars
-^^^^^^^^^^^^
-
-Most command-line options will use ``'-'`` as the prefix, e.g. ``-f/--foo``.
-Parsers that need to support additional prefix characters, e.g. for options
-like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
-to the ArgumentParser constructor::
-
- >>> 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=`` argument defaults to ``'-'``. Supplying a set of
-characters that does not include ``'-'`` will cause ``-f/--foo`` options to be
-disallowed.
-
-
-fromfile_prefix_chars
-^^^^^^^^^^^^^^^^^^^^^
-
-Sometimes, e.g. for particularly long argument lists, it may make sense to
-keep the list of arguments in a file rather than typing it out at the command
-line. If the ``fromfile_prefix_chars=`` argument is given to the ArgumentParser
-constructor, then arguments that start with any of the specified characters
-will be treated as files, and will be replaced by the arguments they contain.
-For example::
-
- >>> open('args.txt', 'w').write('-f\nbar')
- >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
- >>> parser.add_argument('-f')
- >>> parser.parse_args(['-f', 'foo', '@args.txt'])
- Namespace(f='bar')
-
-Arguments read from a file must by default be one per line (but see also
-:meth:`convert_arg_line_to_args`) and are treated as if they were in the same
-place as the original file referencing argument on the command line. So in the
-example above, the expression ``['-f', 'foo', '@args.txt']`` is considered
-equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
-
-The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
-arguments will never be treated as file references.
-
-argument_default
-^^^^^^^^^^^^^^^^
-
-Generally, argument defaults are specified either by passing a default to
-:meth:`add_argument` or by calling the :meth:`set_defaults` methods with a
-specific set of name-value pairs. Sometimes however, it may be useful to
-specify a single parser-wide default for arguments. This can be accomplished by
-passing the ``argument_default=`` keyword argument to ArgumentParser. For
-example, to globally suppress attribute creation on :meth:`parse_args` calls,
-we supply ``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()
-
-
-parents
-^^^^^^^
-
-Sometimes, several parsers share a common set of arguments. Rather than
-repeating the definitions of these arguments, you can define a single parser
-with all the shared arguments and then use the ``parents=`` argument to
-ArgumentParser to have these "inherited". The ``parents=`` argument takes a
-list of ArgumentParser objects, collects all the positional and optional
-actions from them, and adds these actions to the ArgumentParser object being
-constructed::
-
- >>> 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)
-
-Note that most parent parsers will specify ``add_help=False``. Otherwise, the
-ArgumentParser will see two ``-h/--help`` options (one in the parent and one in
-the child) and raise an error.
-
-
-formatter_class
-^^^^^^^^^^^^^^^
-
-ArgumentParser objects allow the help formatting to be customized by specifying
-an alternate formatting class. Currently, there are three such classes:
-``argparse.RawDescriptionHelpFormatter``, ``argparse.RawTextHelpFormatter`` and
-``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
-
-When you have description_ and epilog_ that is already correctly formatted and
-should not be line-wrapped, you can indicate this by passing
-``argparse.RawDescriptionHelpFormatter`` as the ``formatter_class=`` argument
-to ArgumentParser::
-
- >>> 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
-
-If you want to maintain whitespace for all sorts of help text (including
-argument descriptions), you can use ``argparse.RawTextHelpFormatter``.
-
-The other formatter class available,
-``argparse.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)
-
-
-conflict_handler
-^^^^^^^^^^^^^^^^
-
-ArgumentParser objects do not allow two actions with the same option string.
-By default, ArgumentParser objects will raise an exception if you try to create
-an argument with an option string that is already in use::
-
- >>> 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
-
-Sometimes (e.g. when using parents_) it may be useful to simply override any
-older arguments with the same option string. To get this behavior, the value
-``'resolve'`` can be supplied to the ``conflict_handler=`` argument of
-ArgumentParser::
-
- >>> 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
-
-Note that ArgumentParser objects only remove an action if all of its option
-strings are overridden. So, in the example above, the old ``-f/--foo`` action
-is retained as the ``-f`` action, because only the ``--foo`` option string was
-overridden.
-
-
-prog
-^^^^
-
-By default, ArgumentParser objects use ``sys.argv[0]`` to determine how to
-display the name of the program in help messages. This default is almost always
-what you want because it will make the help messages match what your users have
-typed at the command line. For example, consider a file named ``myprogram.py``
-with the following code::
-
- import argparse
- parser = argparse.ArgumentParser()
- parser.add_argument('--foo', help='foo help')
- args = parser.parse_args()
-
-The help for this program will display ``myprogram.py`` as the program name
-(regardless of where the program was invoked from)::
-
- $ 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
-
-To change this default behavior, another value can be supplied using the
-``prog=`` argument to ArgumentParser::
-
- >>> parser = argparse.ArgumentParser(prog='myprogram')
- >>> parser.print_help()
- usage: myprogram [-h]
-
- optional arguments:
- -h, --help show this help message and exit
-
-Note that the program name, whether determined from ``sys.argv[0]`` or from the
-``prog=`` argument, is available to help messages using the ``%(prog)s`` format
-specifier.
-
-::
-
- >>> 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
-
-
-usage
-^^^^^
-
-By default, ArgumentParser objects calculate the usage message from the
-arguments it contains::
-
- >>> 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
-
-If the default usage message is not appropriate for your application, you can
-supply your own usage message using the ``usage=`` keyword argument to
-ArgumentParser::
-
- >>> 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
-
-Note you can use the ``%(prog)s`` format specifier to fill in the program name
-in your usage messages.
-
-
-The add_argument() method
--------------------------
-
-.. method:: add_argument(name or flags..., [action], [nargs], [const], [default], [type], [choices], [required], [help], [metavar], [dest])
-
- Define how a single command line argument should be parsed. Each parameter
- has its own more detailed description below, but in short they are:
-
- * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo``
- or ``-f, --foo``
-
- * action_ - The basic type of action to be taken when this argument is
- encountered at the command-line.
-
- * nargs_ - The number of command-line arguments that should be consumed.
-
- * const_ - A constant value required by some action_ and nargs_ selections.
-
- * default_ - The value produced if the argument is absent from the
- command-line.
-
- * type_ - The type to which the command-line arg should be converted.
-
- * choices_ - A container of the allowable values for the argument.
-
- * required_ - Whether or not the command-line option may be omitted
- (optionals only).
-
- * help_ - A brief description of what the argument does.
-
- * metavar_ - A name for the argument in usage messages.
-
- * dest_ - The name of the attribute to be added to the object returned by
- :meth:`parse_args`.
-
- The following sections describe how each of these are used.
-
-name or flags
-^^^^^^^^^^^^^
-
-The :meth:`add_argument` method needs to know whether you're expecting an
-optional argument, e.g. ``-f`` or ``--foo``, or a positional argument, e.g. a
-list of filenames. The first arguments passed to :meth:`add_argument` must
-therefore be either a series of flags, or a simple argument name. For example,
-an optional argument could be created like::
-
- >>> parser.add_argument('-f', '--foo')
-
-while a positional argument could be created like::
-
- >>> parser.add_argument('bar')
-
-When :meth:`parse_args` is called, optional arguments will be identified by the
-``-`` prefix, and the remaining arguments will be assumed to be positional::
-
- >>> 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
-
-action
-^^^^^^
-
-:class:`ArgumentParser` objects associate command-line args with actions. These
-actions can do just about anything with the command-line args associated with
-them, though most actions simply add an attribute to the object returned by
-:meth:`parse_args`. When you specify a new argument using the
-:meth:`add_argument` method, you can indicate how the command-line args should
-be handled by specifying the ``action`` keyword argument. The supported actions
-are:
-
-* ``'store'`` - This just stores the argument's value. This is the default
- action. For example::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('--foo')
- >>> parser.parse_args('--foo 1'.split())
- Namespace(foo='1')
-
-* ``'store_const'`` - This stores the value specified by the const_ keyword
- argument. Note that the const_ keyword argument defaults to ``None``, so
- you'll almost always need to provide a value for it. The ``'store_const'``
- action is most commonly used with optional arguments that specify some sort
- of flag. For example::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('--foo', action='store_const', const=42)
- >>> parser.parse_args('--foo'.split())
- Namespace(foo=42)
-
-* ``'store_true'`` and ``'store_false'`` - These store the values ``True`` and
- ``False`` respectively. These are basically special cases of
- ``'store_const'``. For example::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('--foo', action='store_true')
- >>> parser.add_argument('--bar', action='store_false')
- >>> parser.parse_args('--foo --bar'.split())
- Namespace(bar=False, foo=True)
-
-* ``'append'`` - This stores a list, and appends each argument value to the
- list. This is useful when you want to allow an option to be specified
- multiple times. Example usage::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('--foo', action='append')
- >>> parser.parse_args('--foo 1 --foo 2'.split())
- Namespace(foo=['1', '2'])
-
-* ``'append_const'`` - This stores a list, and appends the value specified by
- the const_ keyword argument to the list. Note that the const_ keyword
- argument defaults to ``None``, so you'll almost always need to provide a
- value for it. The ``'append_const'`` action is typically useful when you
- want multiple arguments to store constants to the same list, for example::
-
- >>> 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'>])
-
-* ``'version'`` - This expects a ``version=`` keyword argument in the
- :meth:`add_argument` call, and prints version information and exits when
- invoked.
-
- >>> import argparse
- >>> parser = argparse.ArgumentParser(prog='PROG')
- >>> parser.add_argument('-v', '--version', action='version', version='%(prog)s 2.0')
- >>> parser.parse_args(['-v'])
- PROG 2.0
-
-You can also specify an arbitrary action by passing an object that implements
-the Action API. The easiest way to do this is to extend ``argparse.Action``,
-supplying an appropriate ``__call__`` method. The ``__call__`` method accepts
-four parameters:
-
-* ``parser`` - The ArgumentParser object which contains this action.
-
-* ``namespace`` - The namespace object that will be returned by
- :meth:`parse_args`. Most actions add an attribute to this object.
-
-* ``values`` - The associated command-line args, with any type-conversions
- applied. (Type-conversions are specified with the type_ keyword argument to
- :meth:`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.
-
-So for example::
-
- >>> class FooAction(argparse.Action):
- ... 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')
-
-
-nargs
-^^^^^
-
-ArgumentParser objects usually associate a single command-line argument with a
-single action to be taken. In the situations where you'd like to associate a
-different number of command-line arguments with a single action, you can use
-the ``nargs`` keyword argument to :meth:`add_argument`. The supported values
-are:
-
-* N (an integer). N args from the command-line will be gathered together into
- a list. For example::
-
- >>> 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'])
-
- Note that ``nargs=1`` produces a list of one item. This is different from
- the default, in which the item is produced by itself.
-
-* ``'?'``. One arg will be consumed from the command-line if possible, and
- produced as a single item. If no command-line arg is present, the value from
- default_ will be produced. Note that for optional arguments, there is an
- additional case - the option string is present but not followed by a
- command-line arg. In this case the value from const_ will be produced. Some
- examples to illustrate this::
-
- >>> 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'.split())
- Namespace(bar='XX', foo='YY')
- >>> parser.parse_args('XX --foo'.split())
- Namespace(bar='XX', foo='c')
- >>> parser.parse_args(''.split())
- Namespace(bar='d', foo='d')
-
- One of the more common uses of ``nargs='?'`` is to allow optional input and
- output files::
-
- >>> 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...>)
-
-* ``'*'``. All command-line args present are gathered into a list. Note that
- it generally doesn't make much sense to have more than one positional
- argument with ``nargs='*'``, but multiple optional arguments with
- ``nargs='*'`` is possible. For example::
-
- >>> 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'])
-
-* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
- list. Additionally, an error message will be generated if there wasn't at
- least one command-line arg present. For example::
-
- >>> parser = argparse.ArgumentParser(prog='PROG')
- >>> parser.add_argument('foo', nargs='+')
- >>> parser.parse_args('a b'.split())
- Namespace(foo=['a', 'b'])
- >>> parser.parse_args(''.split())
- usage: PROG [-h] foo [foo ...]
- PROG: error: too few arguments
-
-If the ``nargs`` keyword argument is not provided, the number of args consumed
-is determined by the action_. Generally this means a single command-line arg
-will be consumed and a single item (not a list) will be produced.
-
-
-const
-^^^^^
-
-The ``const`` argument of :meth:`add_argument` is used to hold constant values
-that are not read from the command line but are required for the various
-ArgumentParser actions. The two most common uses of it are:
-
-* When :meth:`add_argument` is called with ``action='store_const'`` or
- ``action='append_const'``. These actions add the ``const`` value to one of
- the attributes of the object returned by :meth:`parse_args`. See the action_
- description for examples.
-
-* When :meth:`add_argument` is called with option strings (like ``-f`` or
- ``--foo``) and ``nargs='?'``. This creates an optional argument that can be
- followed by zero or one command-line args. When parsing the command-line, if
- the option string is encountered with no command-line arg following it, the
- value of ``const`` will be assumed instead. See the nargs_ description for
- examples.
-
-The ``const`` keyword argument defaults to ``None``.
-
-
-default
-^^^^^^^
-
-All optional arguments and some positional arguments may be omitted at the
-command-line. The ``default`` keyword argument of :meth:`add_argument`, whose
-value defaults to ``None``, specifies what value should be used if the
-command-line arg is not present. For optional arguments, the ``default`` value
-is used when the option string was not present at the command line::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('--foo', default=42)
- >>> parser.parse_args('--foo 2'.split())
- Namespace(foo='2')
- >>> parser.parse_args(''.split())
- Namespace(foo=42)
-
-For positional arguments with nargs_ ``='?'`` or ``'*'``, the ``default`` value
-is used when no command-line arg was present::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('foo', nargs='?', default=42)
- >>> parser.parse_args('a'.split())
- Namespace(foo='a')
- >>> parser.parse_args(''.split())
- Namespace(foo=42)
-
-
-If you don't want to see an attribute when an option was not present at the
-command line, you can supply ``default=argparse.SUPPRESS``::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
- >>> parser.parse_args([])
- Namespace()
- >>> parser.parse_args(['--foo', '1'])
- Namespace(foo='1')
-
-
-type
-^^^^
-
-By default, ArgumentParser objects read command-line args in as simple strings.
-However, quite often the command-line string should instead be interpreted as
-another type, e.g. ``float``, ``int`` or ``file``. The ``type`` keyword
-argument of :meth:`add_argument` allows any necessary type-checking and
-type-conversions to be performed. Many common builtin types can be used
-directly as the value of the ``type`` argument::
-
- >>> 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)
-
-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...>)
-
-If you need to do some special type-checking or type-conversions, you can
-provide your own types by passing to ``type=`` a callable that takes a single
-string argument and returns the type-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'.split())
- Namespace(foo=9)
- >>> parser.parse_args('7'.split())
- usage: PROG [-h] foo
- PROG: error: argument foo: '7' is not a perfect square
-
-Note that if your type-checking function is just checking for a particular set
-of values, it may be more convenient to use the choices_ keyword argument::
-
- >>> parser = argparse.ArgumentParser(prog='PROG')
- >>> parser.add_argument('foo', type=int, choices=xrange(5, 10))
- >>> parser.parse_args('7'.split())
- Namespace(foo=7)
- >>> parser.parse_args('11'.split())
- usage: PROG [-h] {5,6,7,8,9}
- PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
-
-See the choices_ section for more details.
-
-
-choices
-^^^^^^^
-
-Some command-line args should be selected from a restricted set of values.
-ArgumentParser objects can be told about such sets of values by passing a
-container object as the ``choices`` keyword argument to :meth:`add_argument`.
-When the command-line is parsed with :meth:`parse_args`, arg values will be
-checked, and an error message will be displayed if the arg was not one of the
-acceptable values::
-
- >>> parser = argparse.ArgumentParser(prog='PROG')
- >>> parser.add_argument('foo', choices='abc')
- >>> parser.parse_args('c'.split())
- Namespace(foo='c')
- >>> parser.parse_args('X'.split())
- usage: PROG [-h] {a,b,c}
- PROG: error: argument foo: invalid choice: 'X' (choose from 'a', 'b', 'c')
-
-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='PROG')
- >>> parser.add_argument('foo', type=complex, choices=[1, 1j])
- >>> parser.parse_args('1j'.split())
- Namespace(foo=1j)
- >>> parser.parse_args('-- -4'.split())
- usage: PROG [-h] {1,1j}
- PROG: error: argument foo: invalid choice: (-4+0j) (choose from 1, 1j)
-
-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.
-
-
-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 change this behavior, i.e. to make an option *required*, the value ``True``
-should be specified for the ``required=`` keyword argument to
-:meth:`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``, :meth:`parse_args`
-will report an error if that option is not present at the command line.
-
-**Warning:** Required options are generally considered bad form - normal users
-expect *options* to be *optional*. You should avoid the use of required options
-whenever possible.
-
-
-help
-^^^^
-
-A great command-line interface isn't worth anything if your users can't figure
-out which option does what. So for the end-users, ``help`` is probably the
-most important argument to include in your :meth:`add_argument` calls. The
-``help`` value should be a string containing a brief description of what the
-argument specifies. 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'.split())
- 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
-:meth:`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
-
-
-metavar
-^^^^^^^
-
-When ArgumentParser objects generate help messages, they need 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 if we have a single positional argument with
-``dest='bar'``, that argument will be referred to as ``bar``. And if we have a
-single optional argument ``--foo`` that should be followed by a single
-command-line arg, that arg will be referred to as ``FOO``. You can see this
-behavior in the example below::
-
- >>> 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
-
-If you would like to provide a different name for your argument in help
-messages, you can supply a value for the ``metavar`` keyword argument to
-:meth:`add_argument`::
-
- >>> 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 :meth:`parse_args` object is still determined by the dest_
-value.
-
-Different values of ``nargs`` may cause the metavar to be used multiple times.
-If you'd like to specify a different display name for each of the arguments,
-you can provide a tuple to ``metavar``::
-
- >>> 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
-
-
-dest
-^^^^
-
-Most ArgumentParser actions add some value as an attribute of the object
-returned by :meth:`parse_args`. The name of this attribute is determined by the
-``dest`` keyword argument of :meth:`add_argument`. For positional argument
-actions, ``dest`` is normally supplied as the first argument to
-:meth:`add_argument`::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('bar')
- >>> parser.parse_args('XXX'.split())
- Namespace(bar='XXX')
-
-For optional argument actions, the value of ``dest`` is normally inferred from
-the option strings. ArgumentParser objects generate 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')
-
-If you would like to use a different attribute name from the one automatically
-inferred by the ArgumentParser, you can supply it with an explicit ``dest``
-parameter::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('--foo', dest='bar')
- >>> parser.parse_args('--foo XXX'.split())
- Namespace(bar='XXX')
-
-
-The parse_args() method
------------------------
-
-.. method:: parse_args([args], [namespace])
-
- Convert the strings to objects and assign them as attributes of the
- namespace. Return the populated namespace.
-
- Previous calls to :meth:`add_argument` determine exactly what objects are
- created and how they are assigned. See the documentation for
- :meth:`add_argument` for details.
-
- By default, the arg strings are taken from ``sys.argv``, and a new empty
- ``Namespace`` object is created for the attributes.
-
-Option value syntax
-^^^^^^^^^^^^^^^^^^^
-
-The :meth:`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'.split())
- Namespace(foo=None, x='X')
- >>> parser.parse_args('--foo FOO'.split())
- Namespace(foo='FOO', x=None)
-
-For long options (options with names longer than a single character), you may
-also pass the option and value as a single command line argument, using ``=``
-to separate them::
-
- >>> parser.parse_args('--foo=FOO'.split())
- Namespace(foo='FOO', x=None)
-
-For short options (options only one character long), you may simply concatenate
-the option and its value::
-
- >>> parser.parse_args('-xX'.split())
- Namespace(foo=None, x='X')
-
-You can also combine several short options 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'.split())
- Namespace(x=True, y=True, z='Z')
-
-
-Invalid arguments
-^^^^^^^^^^^^^^^^^
-
-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
-
-
-Arguments containing ``"-"``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-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 arg ``'-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)
-
-
-Argument abbreviations
-^^^^^^^^^^^^^^^^^^^^^^
-
-The :meth:`parse_args` method allows you to abbreviate long options if the
-abbreviation is unambiguous::
-
- >>> 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
-
-As you can see above, you will get an error if you pick a prefix that could
-refer to more than one option.
-
-
-Beyond ``sys.argv``
-^^^^^^^^^^^^^^^^^^^
-
-Sometimes it may be useful to have an ArgumentParser parse args other than
-those of ``sys.argv``. This can be accomplished by passing a list of strings
-to ``parse_args``. You may have noticed that the examples in the argparse
-documentation have made heavy use of this calling style - it is much easier
-to use 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'.split())
- Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
-
-
-Custom namespaces
-^^^^^^^^^^^^^^^^^
-
-It may also be useful to have an ArgumentParser assign attributes to an already
-existing object, rather than the newly-created Namespace object that is
-normally used. 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'
-
-
-Other utilities
----------------
-
-Sub-commands
-^^^^^^^^^^^^
-
-.. method:: add_subparsers()
-
- A lot of 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``, ``svn commit``, etc. 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 objects support the creation of such
- sub-commands with the :meth:`add_subparsers` method. The
- :meth:`add_subparsers` method is normally called with no arguments and
- returns an 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.
-
- Some example usage::
-
- >>> # 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 arg 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 :meth:`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. (You can however supply a
- help message for each subparser command by suppling 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 :meth:`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 :meth:`add_subparsers` method with calls to :meth:`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 :meth:`parse_args` do all the work for you, and then
- just call the appropriate function after the 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 you
- find it necessary to check the name of the subparser that was invoked, you
- can always provide a ``dest`` keyword argument to the :meth:`add_subparsers`
- call::
-
- >>> 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')
-
-
-FileType objects
-^^^^^^^^^^^^^^^^
-
-.. class:: FileType(mode='r', bufsize=None)
-
- The :class:`FileType` factory creates objects that can be passed to the type
- argument of :meth:`add_argument`. Arguments that have :class:`FileType`
- objects as their type will open command-line args 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 :class:`FileType` objects and
- ``sys.stdout`` for writable :class:`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...>)
-
-
-Argument groups
-^^^^^^^^^^^^^^^
-
-.. method:: add_argument_group([title], [description])
-
- By default, ArgumentParser objects group 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
- :meth:`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 :meth:`add_argument_group` method returns an argument group object which
- has an :meth:`add_argument` method just like a regular ArgumentParser
- objects. 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 :meth:`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.
-
-
-Mutual exclusion
-^^^^^^^^^^^^^^^^
-
-.. method:: add_mutually_exclusive_group([required=False])
-
- Sometimes, you need to make sure that only one of a couple different options
- is specified on the command line. You can create groups of such mutually
- exclusive arguments using the :meth:`add_mutually_exclusive_group` method.
- When :func:`parse_args` is called, argparse will make sure that only one of
- the arguments in the mutually exclusive group was present on the command
- line::
-
- >>> 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
-
- The :meth:`add_mutually_exclusive_group` method also accepts a ``required``
- argument, to indicate that at least one of the mutually exclusive arguments
- is 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
-
- Note that currently mutually exclusive argument groups do not support the
- ``title`` and ``description`` arguments of :meth:`add_argument_group`. This
- may change in the future however, so you are *strongly* recommended to
- specify ``required`` as a keyword argument if you use it.
-
-
-Parser defaults
-^^^^^^^^^^^^^^^
-
-.. method:: set_defaults(**kwargs)
-
- Most of the time, the attributes of the object returned by
- :meth:`parse_args` will be fully determined by inspecting the command-line
- args and the argument actions described in your :meth:`add_argument` calls.
- However, sometimes it may be useful to add some additional attributes that
- are determined without any inspection of the command-line. The
- :meth:`set_defaults` method allows you to do this::
-
- >>> 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. So
- if you set a parser-level default for a name that matches an argument, the
- old argument default will no longer be used::
-
- >>> 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 you're working with
- multiple parsers. See the :meth:`add_subparsers` method for an example of
- this type.
-
-.. method:: get_default(dest)
-
- Get the default value for a namespace attribute, as set by either
- :meth:`add_argument` or by :meth:`set_defaults`::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('--foo', default='badger')
- >>> parser.get_default('foo')
- 'badger'
-
-
-Printing help
-^^^^^^^^^^^^^
-
-In most typical applications, :meth:`parse_args` will take care of formatting
-and printing any usage or error messages. However, should you want to format or
-print these on your own, several methods are available:
-
-.. method:: print_usage([file]):
-
- Print a brief description of how the :class:`ArgumentParser` should be
- invoked on the command line. If ``file`` is not present, ``sys.stderr`` is
- assumed.
-
-.. method:: print_help([file]):
-
- Print a help message, including the program usage and information about the
- arguments registered with the :class:`ArgumentParser`. If ``file`` is not
- present, ``sys.stderr`` is assumed.
-
-There are also variants of these methods that simply return a string instead of
-printing it:
-
-.. method:: format_usage():
-
- Return a string containing a brief description of how the
- :class:`ArgumentParser` should be invoked on the command line.
-
-.. method:: format_help():
-
- Return a string containing a help message, including the program usage and
- information about the arguments registered with the :class:`ArgumentParser`.
-
-
-
-Partial parsing
-^^^^^^^^^^^^^^^
-
-.. method:: parse_known_args([args], [namespace])
-
-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
-:meth:`parse_known_args` method can be useful. It works much like
-:meth:`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'])
-
-
-Customizing file parsing
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. method:: convert_arg_line_to_args(arg_line)
-
- Arguments that are read from a file (see the ``fromfile_prefix_chars``
- keyword argument to the :class:`ArgumentParser` constructor) are read one
- argument per line. If you need fancier parsing, then you can subclass the
- :class:`ArgumentParser` and override the :meth:`convert_arg_line_to_args`
- method.
-
- 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):
- for arg in arg_line.split():
- if not arg.strip():
- continue
- yield arg
-
-
-Upgrading optparse code
------------------------
-
-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 messges. 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.
-
-A partial upgrade path from optparse to argparse:
-
-* Replace all ``add_option()`` calls with :meth:`add_argument` calls.
-
-* Replace ``options, args = parser.parse_args()`` with
- ``args = parser.parse_args()`` and add additional :meth:`add_argument` calls
- for the positional arguments.
-
-* 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 ``Values`` with ``Namespace`` and ``OptionError/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``.
+:mod:`argparse` -- Parser for command line options, arguments and sub-commands
+==============================================================================
+
+.. module:: argparse
+ :synopsis: Command-line option and argument parsing library.
+.. moduleauthor:: Steven Bethard <steven.bethard@gmail.com>
+.. versionadded:: 2.7
+.. sectionauthor:: Steven Bethard <steven.bethard@gmail.com>
+
+
+The :mod:`argparse` module makes it easy to write user friendly command line
+interfaces. You define what arguments your program requires, and
+:mod:`argparse` will figure out how to parse those out of ``sys.argv``. The
+:mod:`argparse` module also automatically generates help and usage messages
+based on the arguments you have defined, and issues errors when users give your
+program invalid arguments.
+
+Example
+-------
+
+As an example, the following code is a Python program that takes a list of
+integers and produces either the sum or the max::
+
+ 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)
+
+Assuming the Python code above is saved into a file called ``prog.py``, it can
+be run at the command line and provides useful help messages::
+
+ $ 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)
+
+When run with the appropriate arguments, it prints either the sum or the max of
+the command-line integers::
+
+ $ prog.py 1 2 3 4
+ 4
+
+ $ prog.py 1 2 3 4 --sum
+ 10
+
+If invalid arguments are passed in, it will issue an error::
+
+ $ prog.py a b c
+ usage: prog.py [-h] [--sum] N [N ...]
+ prog.py: error: argument N: invalid int value: 'a'
+
+The following sections walk you through this example.
+
+Creating a parser
+^^^^^^^^^^^^^^^^^
+
+Pretty much every script that uses the :mod:`argparse` module will start out by
+creating an :class:`ArgumentParser` object::
+
+ >>> parser = argparse.ArgumentParser(description='Process some integers.')
+
+The :class:`ArgumentParser` object will hold all the information necessary to
+parse the command line into a more manageable form for your program.
+
+
+Adding arguments
+^^^^^^^^^^^^^^^^
+
+Once you've created an :class:`ArgumentParser`, you'll want to fill it with
+information about your program arguments. You typically do this by making calls
+to the :meth:`add_argument` method. Generally, these calls tell the
+:class:`ArgumentParser` how to take the strings on the command line and turn
+them into objects for you. This information is stored and used when
+:meth:`parse_args` is called. For example, if we add some arguments like this::
+
+ >>> 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)')
+
+when we later call :meth:`parse_args`, we can expect it to return an object
+with two attributes, ``integers`` and ``accumulate``. The ``integers``
+attribute will be a list of one or more ints, and the ``accumulate`` attribute
+will be either the ``sum`` function, if ``--sum`` was specified at the command
+line, or the ``max`` function if it was not.
+
+Parsing arguments
+^^^^^^^^^^^^^^^^^
+
+Once an :class:`ArgumentParser` has been initialized with appropriate calls to
+:meth:`add_argument`, it can be instructed to parse the command-line args by
+calling the :meth:`parse_args` method. This will inspect the command-line,
+convert each arg to the appropriate type and then invoke the appropriate
+action. In most cases, this means a simple namespace object will be built up
+from attributes parsed out of the command-line::
+
+ >>> parser.parse_args(['--sum', '7', '-1', '42'])
+ Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
+
+In a script, :meth:`parse_args` will typically be called with no arguments, and
+the :class:`ArgumentParser` will automatically determine the command-line args
+from ``sys.argv``. That's pretty much it. You're now ready to go write some
+command line interfaces!
+
+
+ArgumentParser objects
+----------------------
+
+.. class:: ArgumentParser([description], [epilog], [prog], [usage], [add_help], [argument_default], [parents], [prefix_chars], [conflict_handler], [formatter_class])
+
+ Create a new :class:`ArgumentParser` object. Each parameter has its own more
+ detailed description below, but in short they are:
+
+ * description_ - Text to display before the argument help.
+
+ * epilog_ - Text to display after the argument help.
+
+ * add_help_ - Add a -h/--help option to the parser. (default: True)
+
+ * argument_default_ - Set the global default value for arguments.
+ (default: None)
+
+ * parents_ - A list of :class:ArgumentParser objects whose arguments should
+ also be included.
+
+ * prefix_chars_ - The set of characters that prefix optional arguments.
+ (default: '-')
+
+ * fromfile_prefix_chars_ - The set of characters that prefix files from
+ which additional arguments should be read. (default: None)
+
+ * formatter_class_ - A class for customizing the help output.
+
+ * conflict_handler_ - Usually unnecessary, defines strategy for resolving
+ conflicting optionals.
+
+ * prog_ - Usually unnecessary, the name of the program
+ (default: ``sys.argv[0]``)
+
+ * usage_ - Usually unnecessary, the string describing the program usage
+ (default: generated)
+
+ The following sections describe how each of these are used.
+
+
+description
+^^^^^^^^^^^
+
+Most calls to the ArgumentParser constructor will use the ``description=``
+keyword argument. This argument gives a brief description of what the program
+does and how it works. In help messages, the description is displayed between
+the command-line usage string and the help messages for the various arguments::
+
+ >>> 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
+
+By default, the description will be line-wrapped so that it fits within the
+given space. To change this behavior, see the formatter_class_ argument.
+
+
+epilog
+^^^^^^
+
+Some programs like to display additional description of the program after the
+description of the arguments. Such text can be specified using the ``epilog=``
+argument to ArgumentParser::
+
+ >>> 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
+
+As with the description_ argument, the ``epilog=`` text is by default
+line-wrapped, but this behavior can be adjusted with the formatter_class_
+argument to ArgumentParser.
+
+
+add_help
+^^^^^^^^
+
+By default, ArgumentParser objects add a ``-h/--help`` option which simply
+displays the parser's help message. For example, consider a file named
+``myprogram.py`` containing the following code::
+
+ import argparse
+ parser = argparse.ArgumentParser()
+ parser.add_argument('--foo', help='foo help')
+ args = parser.parse_args()
+
+If ``-h`` or ``--help`` is supplied is at the command-line, the ArgumentParser
+help will be printed::
+
+ $ python myprogram.py --help
+ usage: myprogram.py [-h] [--foo FOO]
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --foo FOO foo help
+
+Occasionally, it may be useful to disable the addition of this help option.
+This can be achieved by passing ``False`` as the ``add_help=`` argument to
+ArgumentParser::
+
+ >>> 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
+
+
+prefix_chars
+^^^^^^^^^^^^
+
+Most command-line options will use ``'-'`` as the prefix, e.g. ``-f/--foo``.
+Parsers that need to support additional prefix characters, e.g. for options
+like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
+to the ArgumentParser constructor::
+
+ >>> 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=`` argument defaults to ``'-'``. Supplying a set of
+characters that does not include ``'-'`` will cause ``-f/--foo`` options to be
+disallowed.
+
+
+fromfile_prefix_chars
+^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes, e.g. for particularly long argument lists, it may make sense to
+keep the list of arguments in a file rather than typing it out at the command
+line. If the ``fromfile_prefix_chars=`` argument is given to the ArgumentParser
+constructor, then arguments that start with any of the specified characters
+will be treated as files, and will be replaced by the arguments they contain.
+For example::
+
+ >>> open('args.txt', 'w').write('-f\nbar')
+ >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
+ >>> parser.add_argument('-f')
+ >>> parser.parse_args(['-f', 'foo', '@args.txt'])
+ Namespace(f='bar')
+
+Arguments read from a file must by default be one per line (but see also
+:meth:`convert_arg_line_to_args`) and are treated as if they were in the same
+place as the original file referencing argument on the command line. So in the
+example above, the expression ``['-f', 'foo', '@args.txt']`` is considered
+equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
+
+The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
+arguments will never be treated as file references.
+
+argument_default
+^^^^^^^^^^^^^^^^
+
+Generally, argument defaults are specified either by passing a default to
+:meth:`add_argument` or by calling the :meth:`set_defaults` methods with a
+specific set of name-value pairs. Sometimes however, it may be useful to
+specify a single parser-wide default for arguments. This can be accomplished by
+passing the ``argument_default=`` keyword argument to ArgumentParser. For
+example, to globally suppress attribute creation on :meth:`parse_args` calls,
+we supply ``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()
+
+
+parents
+^^^^^^^
+
+Sometimes, several parsers share a common set of arguments. Rather than
+repeating the definitions of these arguments, you can define a single parser
+with all the shared arguments and then use the ``parents=`` argument to
+ArgumentParser to have these "inherited". The ``parents=`` argument takes a
+list of ArgumentParser objects, collects all the positional and optional
+actions from them, and adds these actions to the ArgumentParser object being
+constructed::
+
+ >>> 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)
+
+Note that most parent parsers will specify ``add_help=False``. Otherwise, the
+ArgumentParser will see two ``-h/--help`` options (one in the parent and one in
+the child) and raise an error.
+
+
+formatter_class
+^^^^^^^^^^^^^^^
+
+ArgumentParser objects allow the help formatting to be customized by specifying
+an alternate formatting class. Currently, there are three such classes:
+``argparse.RawDescriptionHelpFormatter``, ``argparse.RawTextHelpFormatter`` and
+``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
+
+When you have description_ and epilog_ that is already correctly formatted and
+should not be line-wrapped, you can indicate this by passing
+``argparse.RawDescriptionHelpFormatter`` as the ``formatter_class=`` argument
+to ArgumentParser::
+
+ >>> 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
+
+If you want to maintain whitespace for all sorts of help text (including
+argument descriptions), you can use ``argparse.RawTextHelpFormatter``.
+
+The other formatter class available,
+``argparse.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)
+
+
+conflict_handler
+^^^^^^^^^^^^^^^^
+
+ArgumentParser objects do not allow two actions with the same option string.
+By default, ArgumentParser objects will raise an exception if you try to create
+an argument with an option string that is already in use::
+
+ >>> 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
+
+Sometimes (e.g. when using parents_) it may be useful to simply override any
+older arguments with the same option string. To get this behavior, the value
+``'resolve'`` can be supplied to the ``conflict_handler=`` argument of
+ArgumentParser::
+
+ >>> 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
+
+Note that ArgumentParser objects only remove an action if all of its option
+strings are overridden. So, in the example above, the old ``-f/--foo`` action
+is retained as the ``-f`` action, because only the ``--foo`` option string was
+overridden.
+
+
+prog
+^^^^
+
+By default, ArgumentParser objects use ``sys.argv[0]`` to determine how to
+display the name of the program in help messages. This default is almost always
+what you want because it will make the help messages match what your users have
+typed at the command line. For example, consider a file named ``myprogram.py``
+with the following code::
+
+ import argparse
+ parser = argparse.ArgumentParser()
+ parser.add_argument('--foo', help='foo help')
+ args = parser.parse_args()
+
+The help for this program will display ``myprogram.py`` as the program name
+(regardless of where the program was invoked from)::
+
+ $ 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
+
+To change this default behavior, another value can be supplied using the
+``prog=`` argument to ArgumentParser::
+
+ >>> parser = argparse.ArgumentParser(prog='myprogram')
+ >>> parser.print_help()
+ usage: myprogram [-h]
+
+ optional arguments:
+ -h, --help show this help message and exit
+
+Note that the program name, whether determined from ``sys.argv[0]`` or from the
+``prog=`` argument, is available to help messages using the ``%(prog)s`` format
+specifier.
+
+::
+
+ >>> 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
+
+
+usage
+^^^^^
+
+By default, ArgumentParser objects calculate the usage message from the
+arguments it contains::
+
+ >>> 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
+
+If the default usage message is not appropriate for your application, you can
+supply your own usage message using the ``usage=`` keyword argument to
+ArgumentParser::
+
+ >>> 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
+
+Note you can use the ``%(prog)s`` format specifier to fill in the program name
+in your usage messages.
+
+
+The add_argument() method
+-------------------------
+
+.. method:: add_argument(name or flags..., [action], [nargs], [const], [default], [type], [choices], [required], [help], [metavar], [dest])
+
+ Define how a single command line argument should be parsed. Each parameter
+ has its own more detailed description below, but in short they are:
+
+ * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo``
+ or ``-f, --foo``
+
+ * action_ - The basic type of action to be taken when this argument is
+ encountered at the command-line.
+
+ * nargs_ - The number of command-line arguments that should be consumed.
+
+ * const_ - A constant value required by some action_ and nargs_ selections.
+
+ * default_ - The value produced if the argument is absent from the
+ command-line.
+
+ * type_ - The type to which the command-line arg should be converted.
+
+ * choices_ - A container of the allowable values for the argument.
+
+ * required_ - Whether or not the command-line option may be omitted
+ (optionals only).
+
+ * help_ - A brief description of what the argument does.
+
+ * metavar_ - A name for the argument in usage messages.
+
+ * dest_ - The name of the attribute to be added to the object returned by
+ :meth:`parse_args`.
+
+ The following sections describe how each of these are used.
+
+name or flags
+^^^^^^^^^^^^^
+
+The :meth:`add_argument` method needs to know whether you're expecting an
+optional argument, e.g. ``-f`` or ``--foo``, or a positional argument, e.g. a
+list of filenames. The first arguments passed to :meth:`add_argument` must
+therefore be either a series of flags, or a simple argument name. For example,
+an optional argument could be created like::
+
+ >>> parser.add_argument('-f', '--foo')
+
+while a positional argument could be created like::
+
+ >>> parser.add_argument('bar')
+
+When :meth:`parse_args` is called, optional arguments will be identified by the
+``-`` prefix, and the remaining arguments will be assumed to be positional::
+
+ >>> 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
+
+action
+^^^^^^
+
+:class:`ArgumentParser` objects associate command-line args with actions. These
+actions can do just about anything with the command-line args associated with
+them, though most actions simply add an attribute to the object returned by
+:meth:`parse_args`. When you specify a new argument using the
+:meth:`add_argument` method, you can indicate how the command-line args should
+be handled by specifying the ``action`` keyword argument. The supported actions
+are:
+
+* ``'store'`` - This just stores the argument's value. This is the default
+ action. For example::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--foo')
+ >>> parser.parse_args('--foo 1'.split())
+ Namespace(foo='1')
+
+* ``'store_const'`` - This stores the value specified by the const_ keyword
+ argument. Note that the const_ keyword argument defaults to ``None``, so
+ you'll almost always need to provide a value for it. The ``'store_const'``
+ action is most commonly used with optional arguments that specify some sort
+ of flag. For example::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--foo', action='store_const', const=42)
+ >>> parser.parse_args('--foo'.split())
+ Namespace(foo=42)
+
+* ``'store_true'`` and ``'store_false'`` - These store the values ``True`` and
+ ``False`` respectively. These are basically special cases of
+ ``'store_const'``. For example::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--foo', action='store_true')
+ >>> parser.add_argument('--bar', action='store_false')
+ >>> parser.parse_args('--foo --bar'.split())
+ Namespace(bar=False, foo=True)
+
+* ``'append'`` - This stores a list, and appends each argument value to the
+ list. This is useful when you want to allow an option to be specified
+ multiple times. Example usage::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--foo', action='append')
+ >>> parser.parse_args('--foo 1 --foo 2'.split())
+ Namespace(foo=['1', '2'])
+
+* ``'append_const'`` - This stores a list, and appends the value specified by
+ the const_ keyword argument to the list. Note that the const_ keyword
+ argument defaults to ``None``, so you'll almost always need to provide a
+ value for it. The ``'append_const'`` action is typically useful when you
+ want multiple arguments to store constants to the same list, for example::
+
+ >>> 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'>])
+
+* ``'version'`` - This expects a ``version=`` keyword argument in the
+ :meth:`add_argument` call, and prints version information and exits when
+ invoked.
+
+ >>> import argparse
+ >>> parser = argparse.ArgumentParser(prog='PROG')
+ >>> parser.add_argument('-v', '--version', action='version', version='%(prog)s 2.0')
+ >>> parser.parse_args(['-v'])
+ PROG 2.0
+
+You can also specify an arbitrary action by passing an object that implements
+the Action API. The easiest way to do this is to extend ``argparse.Action``,
+supplying an appropriate ``__call__`` method. The ``__call__`` method accepts
+four parameters:
+
+* ``parser`` - The ArgumentParser object which contains this action.
+
+* ``namespace`` - The namespace object that will be returned by
+ :meth:`parse_args`. Most actions add an attribute to this object.
+
+* ``values`` - The associated command-line args, with any type-conversions
+ applied. (Type-conversions are specified with the type_ keyword argument to
+ :meth:`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.
+
+So for example::
+
+ >>> class FooAction(argparse.Action):
+ ... 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')
+
+
+nargs
+^^^^^
+
+ArgumentParser objects usually associate a single command-line argument with a
+single action to be taken. In the situations where you'd like to associate a
+different number of command-line arguments with a single action, you can use
+the ``nargs`` keyword argument to :meth:`add_argument`. The supported values
+are:
+
+* N (an integer). N args from the command-line will be gathered together into
+ a list. For example::
+
+ >>> 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'])
+
+ Note that ``nargs=1`` produces a list of one item. This is different from
+ the default, in which the item is produced by itself.
+
+* ``'?'``. One arg will be consumed from the command-line if possible, and
+ produced as a single item. If no command-line arg is present, the value from
+ default_ will be produced. Note that for optional arguments, there is an
+ additional case - the option string is present but not followed by a
+ command-line arg. In this case the value from const_ will be produced. Some
+ examples to illustrate this::
+
+ >>> 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'.split())
+ Namespace(bar='XX', foo='YY')
+ >>> parser.parse_args('XX --foo'.split())
+ Namespace(bar='XX', foo='c')
+ >>> parser.parse_args(''.split())
+ Namespace(bar='d', foo='d')
+
+ One of the more common uses of ``nargs='?'`` is to allow optional input and
+ output files::
+
+ >>> 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...>)
+
+* ``'*'``. All command-line args present are gathered into a list. Note that
+ it generally doesn't make much sense to have more than one positional
+ argument with ``nargs='*'``, but multiple optional arguments with
+ ``nargs='*'`` is possible. For example::
+
+ >>> 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'])
+
+* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
+ list. Additionally, an error message will be generated if there wasn't at
+ least one command-line arg present. For example::
+
+ >>> parser = argparse.ArgumentParser(prog='PROG')
+ >>> parser.add_argument('foo', nargs='+')
+ >>> parser.parse_args('a b'.split())
+ Namespace(foo=['a', 'b'])
+ >>> parser.parse_args(''.split())
+ usage: PROG [-h] foo [foo ...]
+ PROG: error: too few arguments
+
+If the ``nargs`` keyword argument is not provided, the number of args consumed
+is determined by the action_. Generally this means a single command-line arg
+will be consumed and a single item (not a list) will be produced.
+
+
+const
+^^^^^
+
+The ``const`` argument of :meth:`add_argument` is used to hold constant values
+that are not read from the command line but are required for the various
+ArgumentParser actions. The two most common uses of it are:
+
+* When :meth:`add_argument` is called with ``action='store_const'`` or
+ ``action='append_const'``. These actions add the ``const`` value to one of
+ the attributes of the object returned by :meth:`parse_args`. See the action_
+ description for examples.
+
+* When :meth:`add_argument` is called with option strings (like ``-f`` or
+ ``--foo``) and ``nargs='?'``. This creates an optional argument that can be
+ followed by zero or one command-line args. When parsing the command-line, if
+ the option string is encountered with no command-line arg following it, the
+ value of ``const`` will be assumed instead. See the nargs_ description for
+ examples.
+
+The ``const`` keyword argument defaults to ``None``.
+
+
+default
+^^^^^^^
+
+All optional arguments and some positional arguments may be omitted at the
+command-line. The ``default`` keyword argument of :meth:`add_argument`, whose
+value defaults to ``None``, specifies what value should be used if the
+command-line arg is not present. For optional arguments, the ``default`` value
+is used when the option string was not present at the command line::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--foo', default=42)
+ >>> parser.parse_args('--foo 2'.split())
+ Namespace(foo='2')
+ >>> parser.parse_args(''.split())
+ Namespace(foo=42)
+
+For positional arguments with nargs_ ``='?'`` or ``'*'``, the ``default`` value
+is used when no command-line arg was present::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('foo', nargs='?', default=42)
+ >>> parser.parse_args('a'.split())
+ Namespace(foo='a')
+ >>> parser.parse_args(''.split())
+ Namespace(foo=42)
+
+
+If you don't want to see an attribute when an option was not present at the
+command line, you can supply ``default=argparse.SUPPRESS``::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
+ >>> parser.parse_args([])
+ Namespace()
+ >>> parser.parse_args(['--foo', '1'])
+ Namespace(foo='1')
+
+
+type
+^^^^
+
+By default, ArgumentParser objects read command-line args in as simple strings.
+However, quite often the command-line string should instead be interpreted as
+another type, e.g. ``float``, ``int`` or ``file``. The ``type`` keyword
+argument of :meth:`add_argument` allows any necessary type-checking and
+type-conversions to be performed. Many common builtin types can be used
+directly as the value of the ``type`` argument::
+
+ >>> 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)
+
+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...>)
+
+If you need to do some special type-checking or type-conversions, you can
+provide your own types by passing to ``type=`` a callable that takes a single
+string argument and returns the type-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'.split())
+ Namespace(foo=9)
+ >>> parser.parse_args('7'.split())
+ usage: PROG [-h] foo
+ PROG: error: argument foo: '7' is not a perfect square
+
+Note that if your type-checking function is just checking for a particular set
+of values, it may be more convenient to use the choices_ keyword argument::
+
+ >>> parser = argparse.ArgumentParser(prog='PROG')
+ >>> parser.add_argument('foo', type=int, choices=xrange(5, 10))
+ >>> parser.parse_args('7'.split())
+ Namespace(foo=7)
+ >>> parser.parse_args('11'.split())
+ usage: PROG [-h] {5,6,7,8,9}
+ PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
+
+See the choices_ section for more details.
+
+
+choices
+^^^^^^^
+
+Some command-line args should be selected from a restricted set of values.
+ArgumentParser objects can be told about such sets of values by passing a
+container object as the ``choices`` keyword argument to :meth:`add_argument`.
+When the command-line is parsed with :meth:`parse_args`, arg values will be
+checked, and an error message will be displayed if the arg was not one of the
+acceptable values::
+
+ >>> parser = argparse.ArgumentParser(prog='PROG')
+ >>> parser.add_argument('foo', choices='abc')
+ >>> parser.parse_args('c'.split())
+ Namespace(foo='c')
+ >>> parser.parse_args('X'.split())
+ usage: PROG [-h] {a,b,c}
+ PROG: error: argument foo: invalid choice: 'X' (choose from 'a', 'b', 'c')
+
+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='PROG')
+ >>> parser.add_argument('foo', type=complex, choices=[1, 1j])
+ >>> parser.parse_args('1j'.split())
+ Namespace(foo=1j)
+ >>> parser.parse_args('-- -4'.split())
+ usage: PROG [-h] {1,1j}
+ PROG: error: argument foo: invalid choice: (-4+0j) (choose from 1, 1j)
+
+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.
+
+
+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 change this behavior, i.e. to make an option *required*, the value ``True``
+should be specified for the ``required=`` keyword argument to
+:meth:`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``, :meth:`parse_args`
+will report an error if that option is not present at the command line.
+
+**Warning:** Required options are generally considered bad form - normal users
+expect *options* to be *optional*. You should avoid the use of required options
+whenever possible.
+
+
+help
+^^^^
+
+A great command-line interface isn't worth anything if your users can't figure
+out which option does what. So for the end-users, ``help`` is probably the
+most important argument to include in your :meth:`add_argument` calls. The
+``help`` value should be a string containing a brief description of what the
+argument specifies. 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'.split())
+ 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
+:meth:`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
+
+
+metavar
+^^^^^^^
+
+When ArgumentParser objects generate help messages, they need 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 if we have a single positional argument with
+``dest='bar'``, that argument will be referred to as ``bar``. And if we have a
+single optional argument ``--foo`` that should be followed by a single
+command-line arg, that arg will be referred to as ``FOO``. You can see this
+behavior in the example below::
+
+ >>> 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
+
+If you would like to provide a different name for your argument in help
+messages, you can supply a value for the ``metavar`` keyword argument to
+:meth:`add_argument`::
+
+ >>> 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 :meth:`parse_args` object is still determined by the dest_
+value.
+
+Different values of ``nargs`` may cause the metavar to be used multiple times.
+If you'd like to specify a different display name for each of the arguments,
+you can provide a tuple to ``metavar``::
+
+ >>> 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
+
+
+dest
+^^^^
+
+Most ArgumentParser actions add some value as an attribute of the object
+returned by :meth:`parse_args`. The name of this attribute is determined by the
+``dest`` keyword argument of :meth:`add_argument`. For positional argument
+actions, ``dest`` is normally supplied as the first argument to
+:meth:`add_argument`::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('bar')
+ >>> parser.parse_args('XXX'.split())
+ Namespace(bar='XXX')
+
+For optional argument actions, the value of ``dest`` is normally inferred from
+the option strings. ArgumentParser objects generate 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')
+
+If you would like to use a different attribute name from the one automatically
+inferred by the ArgumentParser, you can supply it with an explicit ``dest``
+parameter::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--foo', dest='bar')
+ >>> parser.parse_args('--foo XXX'.split())
+ Namespace(bar='XXX')
+
+
+The parse_args() method
+-----------------------
+
+.. method:: parse_args([args], [namespace])
+
+ Convert the strings to objects and assign them as attributes of the
+ namespace. Return the populated namespace.
+
+ Previous calls to :meth:`add_argument` determine exactly what objects are
+ created and how they are assigned. See the documentation for
+ :meth:`add_argument` for details.
+
+ By default, the arg strings are taken from ``sys.argv``, and a new empty
+ ``Namespace`` object is created for the attributes.
+
+Option value syntax
+^^^^^^^^^^^^^^^^^^^
+
+The :meth:`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'.split())
+ Namespace(foo=None, x='X')
+ >>> parser.parse_args('--foo FOO'.split())
+ Namespace(foo='FOO', x=None)
+
+For long options (options with names longer than a single character), you may
+also pass the option and value as a single command line argument, using ``=``
+to separate them::
+
+ >>> parser.parse_args('--foo=FOO'.split())
+ Namespace(foo='FOO', x=None)
+
+For short options (options only one character long), you may simply concatenate
+the option and its value::
+
+ >>> parser.parse_args('-xX'.split())
+ Namespace(foo=None, x='X')
+
+You can also combine several short options 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'.split())
+ Namespace(x=True, y=True, z='Z')
+
+
+Invalid arguments
+^^^^^^^^^^^^^^^^^
+
+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
+
+
+Arguments containing ``"-"``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 arg ``'-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)
+
+
+Argument abbreviations
+^^^^^^^^^^^^^^^^^^^^^^
+
+The :meth:`parse_args` method allows you to abbreviate long options if the
+abbreviation is unambiguous::
+
+ >>> 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
+
+As you can see above, you will get an error if you pick a prefix that could
+refer to more than one option.
+
+
+Beyond ``sys.argv``
+^^^^^^^^^^^^^^^^^^^
+
+Sometimes it may be useful to have an ArgumentParser parse args other than
+those of ``sys.argv``. This can be accomplished by passing a list of strings
+to ``parse_args``. You may have noticed that the examples in the argparse
+documentation have made heavy use of this calling style - it is much easier
+to use 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'.split())
+ Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
+
+
+Custom namespaces
+^^^^^^^^^^^^^^^^^
+
+It may also be useful to have an ArgumentParser assign attributes to an already
+existing object, rather than the newly-created Namespace object that is
+normally used. 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'
+
+
+Other utilities
+---------------
+
+Sub-commands
+^^^^^^^^^^^^
+
+.. method:: add_subparsers()
+
+ A lot of 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``, ``svn commit``, etc. 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 objects support the creation of such
+ sub-commands with the :meth:`add_subparsers` method. The
+ :meth:`add_subparsers` method is normally called with no arguments and
+ returns an 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.
+
+ Some example usage::
+
+ >>> # 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 arg 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 :meth:`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. (You can however supply a
+ help message for each subparser command by suppling 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 :meth:`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 :meth:`add_subparsers` method with calls to :meth:`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 :meth:`parse_args` do all the work for you, and then
+ just call the appropriate function after the 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 you
+ find it necessary to check the name of the subparser that was invoked, you
+ can always provide a ``dest`` keyword argument to the :meth:`add_subparsers`
+ call::
+
+ >>> 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')
+
+
+FileType objects
+^^^^^^^^^^^^^^^^
+
+.. class:: FileType(mode='r', bufsize=None)
+
+ The :class:`FileType` factory creates objects that can be passed to the type
+ argument of :meth:`add_argument`. Arguments that have :class:`FileType`
+ objects as their type will open command-line args 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 :class:`FileType` objects and
+ ``sys.stdout`` for writable :class:`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...>)
+
+
+Argument groups
+^^^^^^^^^^^^^^^
+
+.. method:: add_argument_group([title], [description])
+
+ By default, ArgumentParser objects group 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
+ :meth:`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 :meth:`add_argument_group` method returns an argument group object which
+ has an :meth:`add_argument` method just like a regular ArgumentParser
+ objects. 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 :meth:`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.
+
+
+Mutual exclusion
+^^^^^^^^^^^^^^^^
+
+.. method:: add_mutually_exclusive_group([required=False])
+
+ Sometimes, you need to make sure that only one of a couple different options
+ is specified on the command line. You can create groups of such mutually
+ exclusive arguments using the :meth:`add_mutually_exclusive_group` method.
+ When :func:`parse_args` is called, argparse will make sure that only one of
+ the arguments in the mutually exclusive group was present on the command
+ line::
+
+ >>> 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
+
+ The :meth:`add_mutually_exclusive_group` method also accepts a ``required``
+ argument, to indicate that at least one of the mutually exclusive arguments
+ is 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
+
+ Note that currently mutually exclusive argument groups do not support the
+ ``title`` and ``description`` arguments of :meth:`add_argument_group`. This
+ may change in the future however, so you are *strongly* recommended to
+ specify ``required`` as a keyword argument if you use it.
+
+
+Parser defaults
+^^^^^^^^^^^^^^^
+
+.. method:: set_defaults(**kwargs)
+
+ Most of the time, the attributes of the object returned by
+ :meth:`parse_args` will be fully determined by inspecting the command-line
+ args and the argument actions described in your :meth:`add_argument` calls.
+ However, sometimes it may be useful to add some additional attributes that
+ are determined without any inspection of the command-line. The
+ :meth:`set_defaults` method allows you to do this::
+
+ >>> 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. So
+ if you set a parser-level default for a name that matches an argument, the
+ old argument default will no longer be used::
+
+ >>> 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 you're working with
+ multiple parsers. See the :meth:`add_subparsers` method for an example of
+ this type.
+
+.. method:: get_default(dest)
+
+ Get the default value for a namespace attribute, as set by either
+ :meth:`add_argument` or by :meth:`set_defaults`::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--foo', default='badger')
+ >>> parser.get_default('foo')
+ 'badger'
+
+
+Printing help
+^^^^^^^^^^^^^
+
+In most typical applications, :meth:`parse_args` will take care of formatting
+and printing any usage or error messages. However, should you want to format or
+print these on your own, several methods are available:
+
+.. method:: print_usage([file]):
+
+ Print a brief description of how the :class:`ArgumentParser` should be
+ invoked on the command line. If ``file`` is not present, ``sys.stderr`` is
+ assumed.
+
+.. method:: print_help([file]):
+
+ Print a help message, including the program usage and information about the
+ arguments registered with the :class:`ArgumentParser`. If ``file`` is not
+ present, ``sys.stderr`` is assumed.
+
+There are also variants of these methods that simply return a string instead of
+printing it:
+
+.. method:: format_usage():
+
+ Return a string containing a brief description of how the
+ :class:`ArgumentParser` should be invoked on the command line.
+
+.. method:: format_help():
+
+ Return a string containing a help message, including the program usage and
+ information about the arguments registered with the :class:`ArgumentParser`.
+
+
+
+Partial parsing
+^^^^^^^^^^^^^^^
+
+.. method:: parse_known_args([args], [namespace])
+
+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
+:meth:`parse_known_args` method can be useful. It works much like
+:meth:`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'])
+
+
+Customizing file parsing
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. method:: convert_arg_line_to_args(arg_line)
+
+ Arguments that are read from a file (see the ``fromfile_prefix_chars``
+ keyword argument to the :class:`ArgumentParser` constructor) are read one
+ argument per line. If you need fancier parsing, then you can subclass the
+ :class:`ArgumentParser` and override the :meth:`convert_arg_line_to_args`
+ method.
+
+ 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):
+ for arg in arg_line.split():
+ if not arg.strip():
+ continue
+ yield arg
+
+
+Upgrading optparse code
+-----------------------
+
+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 messges. 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.
+
+A partial upgrade path from optparse to argparse:
+
+* Replace all ``add_option()`` calls with :meth:`add_argument` calls.
+
+* Replace ``options, args = parser.parse_args()`` with
+ ``args = parser.parse_args()`` and add additional :meth:`add_argument` calls
+ for the positional arguments.
+
+* 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 ``Values`` with ``Namespace`` and ``OptionError/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``.