traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add some x-refs.

This commit is contained in:
Georg Brandl 2010-03-02 22:17:38 +00:00
parent 5e32fe5f9d
commit d2decd9965
1 changed files with 204 additions and 207 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

411
Doc/library/argparse.rst
View File

@ -9,11 +9,11 @@
The :mod:`argparse` module makes it easy to write user friendly command line The :mod:`argparse` module makes it easy to write user friendly command line
interfaces. You define what arguments your program requires, and interfaces. You define what arguments your program requires, and :mod:`argparse`
:mod:`argparse` will figure out how to parse those out of ``sys.argv``. The will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse`
:mod:`argparse` module also automatically generates help and usage messages module also automatically generates help and usage messages based on the
based on the arguments you have defined, and issues errors when users give your arguments you have defined, and issues errors when users give your program
program invalid arguments. invalid arguments.
Example Example
------- -------
@ -81,10 +81,10 @@ Adding arguments
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
Once you've created an :class:`ArgumentParser`, you'll want to fill it with 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 information about your program arguments. You typically do this by making calls
to the :meth:`add_argument` method. Generally, these calls tell the to the :meth:`add_argument` method. Generally, these calls tell the
:class:`ArgumentParser` how to take the strings on the command line and turn :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 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:: :meth:`parse_args` is called. For example, if we add some arguments like this::
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+', >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
@ -93,11 +93,11 @@ them into objects for you. This information is stored and used when
... const=sum, default=max, ... const=sum, default=max,
... help='sum the integers (default: find the max)') ... help='sum the integers (default: find the max)')
when we later call :meth:`parse_args`, we can expect it to return an object when we later call :meth:`parse_args`, we can expect it to return an object with
with two attributes, ``integers`` and ``accumulate``. The ``integers`` two attributes, ``integers`` and ``accumulate``. The ``integers`` attribute
attribute will be a list of one or more ints, and the ``accumulate`` attribute will be a list of one or more ints, and the ``accumulate`` attribute will be
will be either the ``sum`` function, if ``--sum`` was specified at the command either the :func:`sum` function, if ``--sum`` was specified at the command line,
line, or the ``max`` function if it was not. or the :func:`max` function if it was not.
Parsing arguments Parsing arguments
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
@ -105,17 +105,17 @@ Parsing arguments
Once an :class:`ArgumentParser` has been initialized with appropriate calls to 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 :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, calling the :meth:`parse_args` method. This will inspect the command-line,
convert each arg to the appropriate type and then invoke the appropriate convert each arg to the appropriate type and then invoke the appropriate action.
action. In most cases, this means a simple namespace object will be built up In most cases, this means a simple namespace object will be built up from
from attributes parsed out of the command-line:: attributes parsed out of the command-line::
>>> parser.parse_args(['--sum', '7', '-1', '42']) >>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[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 In a script, :meth:`parse_args` will typically be called with no arguments, and
the :class:`ArgumentParser` will automatically determine the command-line args 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 from :data:`sys.argv`. That's pretty much it. You're now ready to go write
command line interfaces! some command line interfaces!
ArgumentParser objects ArgumentParser objects
@ -123,7 +123,7 @@ ArgumentParser objects
.. class:: ArgumentParser([description], [epilog], [prog], [usage], [add_help], [argument_default], [parents], [prefix_chars], [conflict_handler], [formatter_class]) .. 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 Create a new :class:`ArgumentParser` object. Each parameter has its own more
detailed description below, but in short they are: detailed description below, but in short they are:
* description_ - Text to display before the argument help. * description_ - Text to display before the argument help.
@ -162,8 +162,8 @@ description
^^^^^^^^^^^ ^^^^^^^^^^^
Most calls to the ArgumentParser constructor will use the ``description=`` Most calls to the ArgumentParser constructor will use the ``description=``
keyword argument. This argument gives a brief description of what the program 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 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:: the command-line usage string and the help messages for the various arguments::
>>> parser = argparse.ArgumentParser(description='A foo that bars') >>> parser = argparse.ArgumentParser(description='A foo that bars')
@ -176,15 +176,15 @@ the command-line usage string and the help messages for the various arguments::
-h, --help show this help message and exit -h, --help show this help message and exit
By default, the description will be line-wrapped so that it fits within the 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. given space. To change this behavior, see the formatter_class_ argument.
epilog epilog
^^^^^^ ^^^^^^
Some programs like to display additional description of the program after the Some programs like to display additional description of the program after the
description of the arguments. Such text can be specified using the ``epilog=`` description of the arguments. Such text can be specified using the ``epilog=``
argument to ArgumentParser:: argument to :class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser( >>> parser = argparse.ArgumentParser(
... description='A foo that bars', ... description='A foo that bars',
@ -208,7 +208,7 @@ add_help
^^^^^^^^ ^^^^^^^^
By default, ArgumentParser objects add a ``-h/--help`` option which simply By default, ArgumentParser objects add a ``-h/--help`` option which simply
displays the parser's help message. For example, consider a file named displays the parser's help message. For example, consider a file named
``myprogram.py`` containing the following code:: ``myprogram.py`` containing the following code::
import argparse import argparse
@ -261,12 +261,12 @@ disallowed.
fromfile_prefix_chars fromfile_prefix_chars
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
Sometimes, e.g. for particularly long argument lists, it may make sense to Sometimes, e.g. for particularly long argument lists, it may make sense to keep
keep the list of arguments in a file rather than typing it out at the command the list of arguments in a file rather than typing it out at the command line.
line. If the ``fromfile_prefix_chars=`` argument is given to the ArgumentParser If the ``fromfile_prefix_chars=`` argument is given to the ArgumentParser
constructor, then arguments that start with any of the specified characters constructor, then arguments that start with any of the specified characters will
will be treated as files, and will be replaced by the arguments they contain. be treated as files, and will be replaced by the arguments they contain. For
For example:: example::
>>> open('args.txt', 'w').write('-f\nbar') >>> open('args.txt', 'w').write('-f\nbar')
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@') >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
@ -276,7 +276,7 @@ For example::
Arguments read from a file must by default be one per line (but see also 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 :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 place as the original file referencing argument on the command line. So in the
example above, the expression ``['-f', 'foo', '@args.txt']`` is considered example above, the expression ``['-f', 'foo', '@args.txt']`` is considered
equivalent to the expression ``['-f', 'foo', '-f', 'bar']``. equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
@ -288,11 +288,11 @@ argument_default
Generally, argument defaults are specified either by passing a default to Generally, argument defaults are specified either by passing a default to
:meth:`add_argument` or by calling the :meth:`set_defaults` methods with a :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 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 specify a single parser-wide default for arguments. This can be accomplished by
passing the ``argument_default=`` keyword argument to ArgumentParser. For passing the ``argument_default=`` keyword argument to ArgumentParser. For
example, to globally suppress attribute creation on :meth:`parse_args` calls, example, to globally suppress attribute creation on :meth:`parse_args` calls, we
we supply ``argument_default=SUPPRESS``:: supply ``argument_default=SUPPRESS``::
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS) >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo') >>> parser.add_argument('--foo')
@ -309,9 +309,9 @@ parents
Sometimes, several parsers share a common set of arguments. Rather than Sometimes, several parsers share a common set of arguments. Rather than
repeating the definitions of these arguments, you can define a single parser repeating the definitions of these arguments, you can define a single parser
with all the shared arguments and then use the ``parents=`` argument to with all the shared arguments and then use the ``parents=`` argument to
ArgumentParser to have these "inherited". The ``parents=`` argument takes a ArgumentParser to have these "inherited". The ``parents=`` argument takes a
list of ArgumentParser objects, collects all the positional and optional list of ArgumentParser objects, collects all the positional and optional actions
actions from them, and adds these actions to the ArgumentParser object being from them, and adds these actions to the ArgumentParser object being
constructed:: constructed::
>>> parent_parser = argparse.ArgumentParser(add_help=False) >>> parent_parser = argparse.ArgumentParser(add_help=False)
@ -327,7 +327,7 @@ constructed::
>>> bar_parser.parse_args(['--bar', 'YYY']) >>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None) Namespace(bar='YYY', parent=None)
Note that most parent parsers will specify ``add_help=False``. Otherwise, the 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 ArgumentParser will see two ``-h/--help`` options (one in the parent and one in
the child) and raise an error. the child) and raise an error.
@ -336,11 +336,12 @@ formatter_class
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
ArgumentParser objects allow the help formatting to be customized by specifying ArgumentParser objects allow the help formatting to be customized by specifying
an alternate formatting class. Currently, there are three such classes: an alternate formatting class. Currently, there are three such classes:
``argparse.RawDescriptionHelpFormatter``, ``argparse.RawTextHelpFormatter`` and :class:`argparse.RawDescriptionHelpFormatter`,
``argparse.ArgumentDefaultsHelpFormatter``. The first two allow more control :class:`argparse.RawTextHelpFormatter` and
over how textual descriptions are displayed, while the last automatically adds :class:`argparse.ArgumentDefaultsHelpFormatter`. The first two allow more
information about argument default values. 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 By default, ArgumentParser objects line-wrap the description_ and epilog_ texts
in command-line help messages:: in command-line help messages::
@ -367,8 +368,8 @@ in command-line help messages::
When you have description_ and epilog_ that is already correctly formatted and When you have description_ and epilog_ that is already correctly formatted and
should not be line-wrapped, you can indicate this by passing should not be line-wrapped, you can indicate this by passing
``argparse.RawDescriptionHelpFormatter`` as the ``formatter_class=`` argument ``argparse.RawDescriptionHelpFormatter`` as the ``formatter_class=`` argument to
to ArgumentParser:: ArgumentParser::
>>> parser = argparse.ArgumentParser( >>> parser = argparse.ArgumentParser(
... prog='PROG', ... prog='PROG',
@ -395,9 +396,8 @@ to ArgumentParser::
If you want to maintain whitespace for all sorts of help text (including If you want to maintain whitespace for all sorts of help text (including
argument descriptions), you can use ``argparse.RawTextHelpFormatter``. argument descriptions), you can use ``argparse.RawTextHelpFormatter``.
The other formatter class available, The other formatter class available, ``argparse.ArgumentDefaultsHelpFormatter``,
``argparse.ArgumentDefaultsHelpFormatter``, will add information about the will add information about the default value of each of the arguments::
default value of each of the arguments::
>>> parser = argparse.ArgumentParser( >>> parser = argparse.ArgumentParser(
... prog='PROG', ... prog='PROG',
@ -418,9 +418,9 @@ default value of each of the arguments::
conflict_handler conflict_handler
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
ArgumentParser objects do not allow two actions with the same option string. ArgumentParser objects do not allow two actions with the same option string. By
By default, ArgumentParser objects will raise an exception if you try to create default, ArgumentParser objects will raise an exception if you try to create an
an argument with an option string that is already in use:: argument with an option string that is already in use::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help') >>> parser.add_argument('-f', '--foo', help='old foo help')
@ -430,7 +430,7 @@ an argument with an option string that is already in use::
ArgumentError: argument --foo: conflicting option string(s): --foo ArgumentError: argument --foo: conflicting option string(s): --foo
Sometimes (e.g. when using parents_) it may be useful to simply override any 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 older arguments with the same option string. To get this behavior, the value
``'resolve'`` can be supplied to the ``conflict_handler=`` argument of ``'resolve'`` can be supplied to the ``conflict_handler=`` argument of
ArgumentParser:: ArgumentParser::
@ -446,7 +446,7 @@ ArgumentParser::
--foo FOO new foo help --foo FOO new foo help
Note that ArgumentParser objects only remove an action if all of its option 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 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 is retained as the ``-f`` action, because only the ``--foo`` option string was
overridden. overridden.
@ -455,9 +455,9 @@ prog
^^^^ ^^^^
By default, ArgumentParser objects use ``sys.argv[0]`` to determine how to 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 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 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`` typed at the command line. For example, consider a file named ``myprogram.py``
with the following code:: with the following code::
import argparse import argparse
@ -553,7 +553,7 @@ The add_argument() method
.. method:: add_argument(name or flags..., [action], [nargs], [const], [default], [type], [choices], [required], [help], [metavar], [dest]) .. 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 Define how a single command line argument should be parsed. Each parameter
has its own more detailed description below, but in short they are: 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`` * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo``
@ -590,8 +590,8 @@ name or flags
The :meth:`add_argument` method needs to know whether you're expecting an 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 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 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, therefore be either a series of flags, or a simple argument name. For example,
an optional argument could be created like:: an optional argument could be created like::
>>> parser.add_argument('-f', '--foo') >>> parser.add_argument('-f', '--foo')
@ -617,15 +617,15 @@ When :meth:`parse_args` is called, optional arguments will be identified by the
action action
^^^^^^ ^^^^^^
:class:`ArgumentParser` objects associate command-line args with actions. These :class:`ArgumentParser` objects associate command-line args with actions. These
actions can do just about anything with the command-line args associated with 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 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:`parse_args`. When you specify a new argument using the
:meth:`add_argument` method, you can indicate how the command-line args should :meth:`add_argument` method, you can indicate how the command-line args should
be handled by specifying the ``action`` keyword argument. The supported actions be handled by specifying the ``action`` keyword argument. The supported actions
are: are:
* ``'store'`` - This just stores the argument's value. This is the default * ``'store'`` - This just stores the argument's value. This is the default
action. For example:: action. For example::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
@ -634,8 +634,8 @@ are:
Namespace(foo='1') Namespace(foo='1')
* ``'store_const'`` - This stores the value specified by the const_ keyword * ``'store_const'`` - This stores the value specified by the const_ keyword
argument. Note that the const_ keyword argument defaults to ``None``, so 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'`` 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 action is most commonly used with optional arguments that specify some sort
of flag. For example:: of flag. For example::
@ -665,9 +665,9 @@ are:
* ``'append_const'`` - This stores a list, and appends the value specified by * ``'append_const'`` - This stores a list, and appends the value specified by
the const_ keyword argument to the list. Note that the const_ keyword 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 argument defaults to ``None``, so you'll almost always need to provide a value
value for it. The ``'append_const'`` action is typically useful when you for it. The ``'append_const'`` action is typically useful when you want
want multiple arguments to store constants to the same list, for example:: multiple arguments to store constants to the same list, for example::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--str', dest='types', action='append_const', const=str) >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
@ -687,13 +687,13 @@ are:
You can also specify an arbitrary action by passing an object that implements 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``, the Action API. The easiest way to do this is to extend ``argparse.Action``,
supplying an appropriate ``__call__`` method. The ``__call__`` method accepts supplying an appropriate :meth:`__call__` method. The ``__call__`` method
four parameters: accepts four parameters:
* ``parser`` - The ArgumentParser object which contains this action. * ``parser`` - The ArgumentParser object which contains this action.
* ``namespace`` - The namespace object that will be returned by * ``namespace`` - The namespace object that will be returned by
:meth:`parse_args`. Most actions add an attribute to this object. :meth:`parse_args`. Most actions add an attribute to this object.
* ``values`` - The associated command-line args, with any type-conversions * ``values`` - The associated command-line args, with any type-conversions
applied. (Type-conversions are specified with the type_ keyword argument to applied. (Type-conversions are specified with the type_ keyword argument to
@ -725,12 +725,11 @@ nargs
ArgumentParser objects usually associate a single command-line argument with a 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 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 different number of command-line arguments with a single action, you can use the
the ``nargs`` keyword argument to :meth:`add_argument`. The supported values ``nargs`` keyword argument to :meth:`add_argument`. The supported values are:
are:
* N (an integer). N args from the command-line will be gathered together into * N (an integer). N args from the command-line will be gathered together into a
a list. For example:: list. For example::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2) >>> parser.add_argument('--foo', nargs=2)
@ -748,53 +747,53 @@ are:
command-line arg. In this case the value from const_ will be produced. Some command-line arg. In this case the value from const_ will be produced. Some
examples to illustrate this:: examples to illustrate this::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='?', const='c', default='d') >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d') >>> parser.add_argument('bar', nargs='?', default='d')
>>> parser.parse_args('XX --foo YY'.split()) >>> parser.parse_args('XX --foo YY'.split())
Namespace(bar='XX', foo='YY') Namespace(bar='XX', foo='YY')
>>> parser.parse_args('XX --foo'.split()) >>> parser.parse_args('XX --foo'.split())
Namespace(bar='XX', foo='c') Namespace(bar='XX', foo='c')
>>> parser.parse_args(''.split()) >>> parser.parse_args(''.split())
Namespace(bar='d', foo='d') Namespace(bar='d', foo='d')
One of the more common uses of ``nargs='?'`` is to allow optional input and One of the more common uses of ``nargs='?'`` is to allow optional input and
output files:: output files::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'), default=sys.stdin) >>> 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.add_argument('outfile', nargs='?', type=argparse.FileType('w'), default=sys.stdout)
>>> parser.parse_args(['input.txt', 'output.txt']) >>> 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...>) Namespace(infile=<open file 'input.txt', mode 'r' at 0x...>, outfile=<open file 'output.txt', mode 'w' at 0x...>)
>>> parser.parse_args([]) >>> parser.parse_args([])
Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>, outfile=<open file '<stdout>', mode 'w' at 0x...>) 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 * ``'*'``. 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 it generally doesn't make much sense to have more than one positional argument
argument with ``nargs='*'``, but multiple optional arguments with with ``nargs='*'``, but multiple optional arguments with ``nargs='*'`` is
``nargs='*'`` is possible. For example:: possible. For example::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='*') >>> parser.add_argument('--foo', nargs='*')
>>> parser.add_argument('--bar', nargs='*') >>> parser.add_argument('--bar', nargs='*')
>>> parser.add_argument('baz', nargs='*') >>> parser.add_argument('baz', nargs='*')
>>> parser.parse_args('a b --foo x y --bar 1 2'.split()) >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y']) Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a * ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
list. Additionally, an error message will be generated if there wasn't at list. Additionally, an error message will be generated if there wasn't at
least one command-line arg present. For example:: least one command-line arg present. For example::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+') >>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args('a b'.split()) >>> parser.parse_args('a b'.split())
Namespace(foo=['a', 'b']) Namespace(foo=['a', 'b'])
>>> parser.parse_args(''.split()) >>> parser.parse_args(''.split())
usage: PROG [-h] foo [foo ...] usage: PROG [-h] foo [foo ...]
PROG: error: too few arguments PROG: error: too few arguments
If the ``nargs`` keyword argument is not provided, the number of args consumed 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 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. will be consumed and a single item (not a list) will be produced.
@ -811,7 +810,7 @@ ArgumentParser actions. The two most common uses of it are:
description for examples. description for examples.
* When :meth:`add_argument` is called with option strings (like ``-f`` or * When :meth:`add_argument` is called with option strings (like ``-f`` or
``--foo``) and ``nargs='?'``. This creates an optional argument that can be ``--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 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 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 value of ``const`` will be assumed instead. See the nargs_ description for
@ -863,8 +862,8 @@ type
By default, ArgumentParser objects read command-line args in as simple strings. By default, ArgumentParser objects read command-line args in as simple strings.
However, quite often the command-line string should instead be interpreted as However, quite often the command-line string should instead be interpreted as
another type, e.g. ``float``, ``int`` or ``file``. The ``type`` keyword another type, e.g. :class:`float`, :class:`int` or :class:`file`. The ``type``
argument of :meth:`add_argument` allows any necessary type-checking and keyword argument of :meth:`add_argument` allows any necessary type-checking and
type-conversions to be performed. Many common builtin types can be used type-conversions to be performed. Many common builtin types can be used
directly as the value of the ``type`` argument:: directly as the value of the ``type`` argument::
@ -876,7 +875,7 @@ directly as the value of the ``type`` argument::
To ease the use of various types of files, the argparse module provides the 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 factory FileType which takes the ``mode=`` and ``bufsize=`` arguments of the
``file`` object. For example, ``FileType('w')`` can be used to create a ``file`` object. For example, ``FileType('w')`` can be used to create a
writable file:: writable file::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
@ -949,8 +948,8 @@ container should match the type_ specified::
PROG: error: argument foo: invalid choice: (-4+0j) (choose from 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`` Any object that supports the ``in`` operator can be passed as the ``choices``
value, so ``dict`` objects, ``set`` objects, custom containers, etc. are all value, so :class:`dict` objects, :class:`set` objects, custom containers,
supported. etc. are all supported.
required required
@ -974,7 +973,7 @@ 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. will report an error if that option is not present at the command line.
**Warning:** Required options are generally considered bad form - normal users **Warning:** Required options are generally considered bad form - normal users
expect *options* to be *optional*. You should avoid the use of required options expect *options* to be *optional*. You should avoid the use of required options
whenever possible. whenever possible.
@ -982,12 +981,12 @@ help
^^^^ ^^^^
A great command-line interface isn't worth anything if your users can't figure 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 out which option does what. So for the end-users, ``help`` is probably the most
most important argument to include in your :meth:`add_argument` calls. The important argument to include in your :meth:`add_argument` calls. The ``help``
``help`` value should be a string containing a brief description of what the value should be a string containing a brief description of what the argument
argument specifies. When a user requests help (usually by using ``-h`` or specifies. When a user requests help (usually by using ``-h`` or ``--help`` at
``--help`` at the command-line), these ``help`` descriptions will be displayed the command-line), these ``help`` descriptions will be displayed with each
with each argument:: argument::
>>> parser = argparse.ArgumentParser(prog='frobble') >>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true', >>> parser.add_argument('--foo', action='store_true',
@ -1026,7 +1025,7 @@ metavar
^^^^^^^ ^^^^^^^
When ArgumentParser objects generate help messages, they need some way to refer When ArgumentParser objects generate help messages, they need some way to refer
to each expected argument. By default, ArgumentParser objects use the dest_ to each expected argument. By default, ArgumentParser objects use the dest_
value as the "name" of each object. By default, for positional argument value as the "name" of each object. By default, for positional argument
actions, the dest_ value is used directly, and for optional argument actions, 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 the dest_ value is uppercased. So if we have a single positional argument with
@ -1074,8 +1073,8 @@ attribute on the :meth:`parse_args` object is still determined by the dest_
value. value.
Different values of ``nargs`` may cause the metavar to be used multiple times. 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, If you'd like to specify a different display name for each of the arguments, you
you can provide a tuple to ``metavar``:: can provide a tuple to ``metavar``::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2) >>> parser.add_argument('-x', nargs=2)
@ -1093,8 +1092,8 @@ dest
^^^^ ^^^^
Most ArgumentParser actions add some value as an attribute of the object 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 returned by :meth:`parse_args`. The name of this attribute is determined by the
``dest`` keyword argument of :meth:`add_argument`. For positional argument ``dest`` keyword argument of :meth:`add_argument`. For positional argument
actions, ``dest`` is normally supplied as the first argument to actions, ``dest`` is normally supplied as the first argument to
:meth:`add_argument`:: :meth:`add_argument`::
@ -1104,12 +1103,12 @@ actions, ``dest`` is normally supplied as the first argument to
Namespace(bar='XXX') Namespace(bar='XXX')
For optional argument actions, the value of ``dest`` is normally inferred from For optional argument actions, the value of ``dest`` is normally inferred from
the option strings. ArgumentParser objects generate the value of ``dest`` by the option strings. ArgumentParser objects generate the value of ``dest`` by
taking the first long option string and stripping away the initial ``'--'`` taking the first long option string and stripping away the initial ``'--'``
string. If no long option strings were supplied, ``dest`` will be derived from string. If no long option strings were supplied, ``dest`` will be derived from
the first short option string by stripping the initial ``'-'`` character. Any the first short option string by stripping the initial ``'-'`` character. Any
internal ``'-'`` characters will be converted to ``'_'`` characters to make internal ``'-'`` characters will be converted to ``'_'`` characters to make sure
sure the string is a valid attribute name. The examples below illustrate this the string is a valid attribute name. The examples below illustrate this
behavior:: behavior::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
@ -1136,20 +1135,20 @@ The parse_args() method
.. method:: parse_args([args], [namespace]) .. method:: parse_args([args], [namespace])
Convert the strings to objects and assign them as attributes of the Convert the strings to objects and assign them as attributes of the
namespace. Return the populated namespace. namespace. Return the populated namespace.
Previous calls to :meth:`add_argument` determine exactly what objects are Previous calls to :meth:`add_argument` determine exactly what objects are
created and how they are assigned. See the documentation for created and how they are assigned. See the documentation for
:meth:`add_argument` for details. :meth:`add_argument` for details.
By default, the arg strings are taken from ``sys.argv``, and a new empty By default, the arg strings are taken from :data:`sys.argv`, and a new empty
``Namespace`` object is created for the attributes. ``Namespace`` object is created for the attributes.
Option value syntax Option value syntax
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
The :meth:`parse_args` method supports several ways of specifying the value of 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 an option (if it takes one). In the simplest case, the option and its value are
passed as two separate arguments:: passed as two separate arguments::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
@ -1161,8 +1160,8 @@ passed as two separate arguments::
Namespace(foo='FOO', x=None) Namespace(foo='FOO', x=None)
For long options (options with names longer than a single character), you may 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 ``=`` also pass the option and value as a single command line argument, using ``=`` to
to separate them:: separate them::
>>> parser.parse_args('--foo=FOO'.split()) >>> parser.parse_args('--foo=FOO'.split())
Namespace(foo='FOO', x=None) Namespace(foo='FOO', x=None)
@ -1189,7 +1188,7 @@ Invalid arguments
While parsing the command-line, ``parse_args`` checks for a variety of errors, While parsing the command-line, ``parse_args`` checks for a variety of errors,
including ambiguous options, invalid types, invalid options, wrong number of including ambiguous options, invalid types, invalid options, wrong number of
positional arguments, etc. When it encounters such an error, it exits and positional arguments, etc. When it encounters such an error, it exits and
prints the error along with a usage message:: prints the error along with a usage message::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
@ -1216,9 +1215,9 @@ Arguments containing ``"-"``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``parse_args`` method attempts to give errors whenever the user has clearly 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 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 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 attempt to provide a positional argument. The ``parse_args`` method is cautious
here: positional arguments may only begin with ``'-'`` if they look like 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 negative numbers and there are no options in the parser that look like negative
numbers:: numbers::
@ -1285,11 +1284,11 @@ refer to more than one option.
Beyond ``sys.argv`` Beyond ``sys.argv``
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
Sometimes it may be useful to have an ArgumentParser parse args other than Sometimes it may be useful to have an ArgumentParser parse args other than those
those of ``sys.argv``. This can be accomplished by passing a list of strings of :data:`sys.argv`. This can be accomplished by passing a list of strings to
to ``parse_args``. You may have noticed that the examples in the argparse ``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 documentation have made heavy use of this calling style - it is much easier to
to use at the interactive prompt:: use at the interactive prompt::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument( >>> parser.add_argument(
@ -1308,9 +1307,8 @@ Custom namespaces
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
It may also be useful to have an ArgumentParser assign attributes to an already 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 existing object, rather than the newly-created Namespace object that is normally
normally used. This can be achieved by specifying the ``namespace=`` keyword used. This can be achieved by specifying the ``namespace=`` keyword argument::
argument::
>>> class C(object): >>> class C(object):
... pass ... pass
@ -1331,18 +1329,17 @@ Sub-commands
.. method:: add_subparsers() .. method:: add_subparsers()
A lot of programs split up their functionality into a number of A lot of programs split up their functionality into a number of sub-commands,
sub-commands, for example, the ``svn`` program can invoke sub-commands like for example, the ``svn`` program can invoke sub-commands like ``svn
``svn checkout``, ``svn update``, ``svn commit``, etc. Splitting up checkout``, ``svn update``, ``svn commit``, etc. Splitting up functionality
functionality this way can be a particularly good idea when a program this way can be a particularly good idea when a program performs several
performs several different functions which require different kinds of different functions which require different kinds of command-line arguments.
command-line arguments. ArgumentParser objects support the creation of such ArgumentParser objects support the creation of such sub-commands with the
sub-commands with the :meth:`add_subparsers` method. The :meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally
:meth:`add_subparsers` method is normally called with no arguments and called with no arguments and returns an special action object. This object
returns an special action object. This object has a single method, has a single method, ``add_parser``, which takes a command name and any
``add_parser``, which takes a command name and any ArgumentParser ArgumentParser constructor arguments, and returns an ArgumentParser object
constructor arguments, and returns an ArgumentParser object that can be that can be modified as usual.
modified as usual.
Some example usage:: Some example usage::
@ -1368,15 +1365,15 @@ Sub-commands
Note that the object returned by :meth:`parse_args` will only contain 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 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 command line (and not any other subparsers). So in the example above, when
the ``"a"`` command is specified, only the ``foo`` and ``bar`` attributes the ``"a"`` command is specified, only the ``foo`` and ``bar`` attributes are
are present, and when the ``"b"`` command is specified, only the ``foo`` and present, and when the ``"b"`` command is specified, only the ``foo`` and
``baz`` attributes are present. ``baz`` attributes are present.
Similarly, when a help message is requested from a subparser, only the help 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 for that particular parser will be printed. The help message will not
include parent parser or sibling parser messages. (You can however supply a include parent parser or sibling parser messages. (You can however supply a
help message for each subparser command by suppling the ``help=`` argument help message for each subparser command by suppling the ``help=`` argument to
to ``add_parser`` as above.) ``add_parser`` as above.)
:: ::
@ -1408,9 +1405,9 @@ Sub-commands
-h, --help show this help message and exit -h, --help show this help message and exit
--baz {X,Y,Z} baz help --baz {X,Y,Z} baz help
The :meth:`add_subparsers` method also supports ``title`` and The :meth:`add_subparsers` method also supports ``title`` and ``description``
``description`` keyword arguments. When either is present, the subparser's keyword arguments. When either is present, the subparser's commands will
commands will appear in their own group in the help output. For example:: appear in their own group in the help output. For example::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands', >>> subparsers = parser.add_subparsers(title='subcommands',
@ -1430,9 +1427,9 @@ Sub-commands
{foo,bar} additional help {foo,bar} additional help
One particularly effective way of handling sub-commands is to combine the One particularly effective way of handling sub-commands is to combine the use
use of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so
so that each subparser knows which Python function it should execute. For that each subparser knows which Python function it should execute. For
example:: example::
>>> # sub-command functions >>> # sub-command functions
@ -1469,8 +1466,8 @@ Sub-commands
This way, you can let :meth:`parse_args` do all the work for you, and then 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. just call the appropriate function after the argument parsing is complete.
Associating functions with actions like this is typically the easiest way Associating functions with actions like this is typically the easiest way to
to handle the different actions for each of your subparsers. However, if you 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 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` can always provide a ``dest`` keyword argument to the :meth:`add_subparsers`
call:: call::
@ -1491,9 +1488,9 @@ FileType objects
.. class:: FileType(mode='r', bufsize=None) .. class:: FileType(mode='r', bufsize=None)
The :class:`FileType` factory creates objects that can be passed to the type The :class:`FileType` factory creates objects that can be passed to the type
argument of :meth:`add_argument`. Arguments that have :class:`FileType` argument of :meth:`add_argument`. Arguments that have :class:`FileType`
objects as their type will open command-line args as files with the objects as their type will open command-line args as files with the requested
requested modes and buffer sizes: modes and buffer sizes:
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--output', type=argparse.FileType('wb', 0)) >>> parser.add_argument('--output', type=argparse.FileType('wb', 0))
@ -1534,9 +1531,9 @@ Argument groups
The :meth:`add_argument_group` method returns an argument group object which The :meth:`add_argument_group` method returns an argument group object which
has an :meth:`add_argument` method just like a regular ArgumentParser 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 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 like a normal argument, but displays the argument in a separate group for
help messages. The :meth:`add_argument_group` method accepts ``title`` and help messages. The :meth:`add_argument_group` method accepts ``title`` and
``description`` arguments which can be used to customize this display:: ``description`` arguments which can be used to customize this display::
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
@ -1567,7 +1564,7 @@ Mutual exclusion
.. method:: add_mutually_exclusive_group([required=False]) .. method:: add_mutually_exclusive_group([required=False])
Sometimes, you need to make sure that only one of a couple different options 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 is specified on the command line. You can create groups of such mutually
exclusive arguments using the :meth:`add_mutually_exclusive_group` method. exclusive arguments using the :meth:`add_mutually_exclusive_group` method.
When :func:`parse_args` is called, argparse will make sure that only one of 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 the arguments in the mutually exclusive group was present on the command
@ -1598,7 +1595,7 @@ Mutual exclusion
PROG: error: one of the arguments --foo --bar is required PROG: error: one of the arguments --foo --bar is required
Note that currently mutually exclusive argument groups do not support the Note that currently mutually exclusive argument groups do not support the
``title`` and ``description`` arguments of :meth:`add_argument_group`. This ``title`` and ``description`` arguments of :meth:`add_argument_group`. This
may change in the future however, so you are *strongly* recommended to may change in the future however, so you are *strongly* recommended to
specify ``required`` as a keyword argument if you use it. specify ``required`` as a keyword argument if you use it.
@ -1608,12 +1605,12 @@ Parser defaults
.. method:: set_defaults(**kwargs) .. method:: set_defaults(**kwargs)
Most of the time, the attributes of the object returned by Most of the time, the attributes of the object returned by :meth:`parse_args`
:meth:`parse_args` will be fully determined by inspecting the command-line will be fully determined by inspecting the command-line args and the argument
args and the argument actions described in your :meth:`add_argument` calls. actions described in your :meth:`add_argument` calls. However, sometimes it
However, sometimes it may be useful to add some additional attributes that may be useful to add some additional attributes that are determined without
are determined without any inspection of the command-line. The any inspection of the command-line. The :meth:`set_defaults` method allows
:meth:`set_defaults` method allows you to do this:: you to do this::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int) >>> parser.add_argument('foo', type=int)
@ -1650,7 +1647,7 @@ Printing help
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
In most typical applications, :meth:`parse_args` will take care of formatting 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 and printing any usage or error messages. However, should you want to format or
print these on your own, several methods are available: print these on your own, several methods are available:
.. method:: print_usage([file]): .. method:: print_usage([file]):
@ -1662,7 +1659,7 @@ print these on your own, several methods are available:
.. method:: print_help([file]): .. method:: print_help([file]):
Print a help message, including the program usage and information about the Print a help message, including the program usage and information about the
arguments registered with the :class:`ArgumentParser`. If ``file`` is not arguments registered with the :class:`ArgumentParser`. If ``file`` is not
present, ``sys.stderr`` is assumed. present, ``sys.stderr`` is assumed.
There are also variants of these methods that simply return a string instead of There are also variants of these methods that simply return a string instead of
@ -1687,10 +1684,10 @@ Partial parsing
Sometimes a script may only parse a few of the command line arguments, passing 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 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_known_args` method can be useful. It works much like
:meth:`parse_args` except that it does not produce an error when extra :meth:`parse_args` except that it does not produce an error when extra arguments
arguments are present. Instead, it returns a two item tuple containing the are present. Instead, it returns a two item tuple containing the populated
populated namespace and the list of remaining argument strings. namespace and the list of remaining argument strings.
:: ::
@ -1716,8 +1713,8 @@ Customizing file parsing
the argument file. It returns a list of arguments parsed from this string. 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. 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 A useful override of this method is one that treats each space-separated word
word as an argument:: as an argument::
def convert_arg_line_to_args(self, arg_line): def convert_arg_line_to_args(self, arg_line):
for arg in arg_line.split(): for arg in arg_line.split():
@ -1730,19 +1727,19 @@ Upgrading optparse code
----------------------- -----------------------
Originally, the argparse module had attempted to maintain compatibility with Originally, the argparse module had attempted to maintain compatibility with
optparse. However, optparse was difficult to extend transparently, optparse. However, optparse was difficult to extend transparently, particularly
particularly with the changes required to support the new ``nargs=`` with the changes required to support the new ``nargs=`` specifiers and better
specifiers and better usage messges. When most everything in optparse had usage messges. When most everything in optparse had either been copy-pasted
either been copy-pasted over or monkey-patched, it no longer seemed practical over or monkey-patched, it no longer seemed practical to try to maintain the
to try to maintain the backwards compatibility. backwards compatibility.
A partial upgrade path from optparse to argparse: A partial upgrade path from optparse to argparse:
* Replace all ``add_option()`` calls with :meth:`add_argument` calls. * Replace all ``add_option()`` calls with :meth:`add_argument` calls.
* Replace ``options, args = parser.parse_args()`` with * Replace ``options, args = parser.parse_args()`` with ``args =
``args = parser.parse_args()`` and add additional :meth:`add_argument` calls parser.parse_args()`` and add additional :meth:`add_argument` calls for the
for the positional arguments. positional arguments.
* Replace callback actions and the ``callback_*`` keyword arguments with * Replace callback actions and the ``callback_*`` keyword arguments with
``type`` or ``action`` arguments. ``type`` or ``action`` arguments.
@ -1753,6 +1750,6 @@ A partial upgrade path from optparse to argparse:
* Replace ``Values`` with ``Namespace`` and ``OptionError/OptionValueError`` * Replace ``Values`` with ``Namespace`` and ``OptionError/OptionValueError``
with ``ArgumentError``. with ``ArgumentError``.
* Replace strings with implicit arguments such as ``%default`` or ``%prog`` * Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
with the standard python syntax to use dictionaries to format strings, that the standard python syntax to use dictionaries to format strings, that is,
is, ``%(default)s`` and ``%(prog)s``. ``%(default)s`` and ``%(prog)s``.