diff options
Diffstat (limited to 'Doc/library/argparse.rst')
| -rw-r--r-- | Doc/library/argparse.rst | 1758 |
1 files changed, 1758 insertions, 0 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst new file mode 100644 index 0000000..78922b1 --- /dev/null +++ b/Doc/library/argparse.rst @@ -0,0 +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``.
|