diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/argparse.rst | 3513 |
1 files changed, 1755 insertions, 1758 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 78922b1..7e74a68 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1,1758 +1,1755 @@ -: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 :data:`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 :func:`sum` function, if ``--sum`` was specified at the command line, +or the :func:`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 :data:`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 :class:`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: +:class:`argparse.RawDescriptionHelpFormatter`, +:class:`argparse.RawTextHelpFormatter` and +:class:`argparse.ArgumentDefaultsHelpFormatter`. The first two allow more +control over how textual descriptions are displayed, while the last +automatically adds information about argument default values. + +By default, ArgumentParser objects line-wrap the description_ and epilog_ texts +in command-line help messages:: + + >>> parser = argparse.ArgumentParser( + ... prog='PROG', + ... description='''this description + ... was indented weird + ... but that is okay''', + ... epilog=''' + ... likewise for this epilog whose whitespace will + ... be cleaned up and whose words will be wrapped + ... across a couple lines''') + >>> parser.print_help() + usage: PROG [-h] + + this description was indented weird but that is okay + + optional arguments: + -h, --help show this help message and exit + + likewise for this epilog whose whitespace will be cleaned up and whose words + will be wrapped across a couple lines + +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 :meth:`__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. :class:`float`, :class:`int` or :class:`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 :class:`dict` objects, :class:`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 :data:`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 :data:`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``. |