-:mod:`argparse` --- Parser for command line options, arguments and sub-commands
+: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>
+.. versionadded:: 2.7
+
+**Source code:** :source:`Lib/argparse.py`
+
+--------------
-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. The program defines what arguments it 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 and issues errors
>>> parser = argparse.ArgumentParser(description='Process some integers.')
The :class:`ArgumentParser` object will hold all the information necessary to
-parse the command line into python data types.
+parse the command line into Python data types.
Adding arguments
... const=sum, default=max,
... help='sum the integers (default: find the max)')
-Later, calling :meth:`parse_args` will return an object with
+Later, calling :meth:`~ArgumentParser.parse_args` will 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,
Parsing arguments
^^^^^^^^^^^^^^^^^
-:class:`ArgumentParser` parses args through the
-:meth:`~ArgumentParser.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::
+:class:`ArgumentParser` parses arguments through the
+:meth:`~ArgumentParser.parse_args` method. This will inspect the command line,
+convert each argument to the appropriate type and then invoke the appropriate action.
+In most cases, this means a simple :class:`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:`~ArgumentParser.parse_args` will typically be called with no
arguments, and the :class:`ArgumentParser` will automatically determine the
-command-line args from :data:`sys.argv`.
+command-line arguments from :data:`sys.argv`.
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
detailed description below, but in short they are:
conflicting optionals.
* prog_ - The name of the program (default:
- :data:`sys.argv[0]`)
+ ``sys.argv[0]``)
* usage_ - The string describing the program usage (default: generated)
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
-If ``-h`` or ``--help`` is supplied is at the command-line, the ArgumentParser
+If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
help will be printed::
$ python myprogram.py --help
--foo FOO foo help
The help option is typically ``-h/--help``. The exception to this is
-if the ``prefix_chars=`` is specified and does not include ``'-'``, in
+if the ``prefix_chars=`` is specified and does not include ``-``, in
which case ``-h`` and ``--help`` are not valid options. In
this case, the first character in ``prefix_chars`` is used to prefix
the help options::
prefix_chars
^^^^^^^^^^^^
-Most command-line options will use ``'-'`` as the prefix, e.g. ``-f/--foo``.
+Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
Parsers that need to support different or additional prefix
characters, e.g. for options
like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
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
+characters that does not include ``-`` will cause ``-f/--foo`` options to be
disallowed.
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']``.
+:meth:`~ArgumentParser.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.
^^^^^^^^^^^^^^^^
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 :class:`ArgumentParser`.
-For example, to globally suppress attribute creation on :meth:`parse_args`
+:meth:`~ArgumentParser.add_argument` or by calling the
+:meth:`~ArgumentParser.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 :class:`ArgumentParser`. For example,
+to globally suppress attribute creation on :meth:`~ArgumentParser.parse_args`
calls, we supply ``argument_default=SUPPRESS``::
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
:class:`ArgumentParser` will see two ``-h/--help`` options (one in the parent
and one in the child) and raise an error.
+.. note::
+ You must fully initialize the parsers before passing them via ``parents=``.
+ If you change the parent parsers after the child parser, those changes will
+ not be reflected in the child.
+
formatter_class
^^^^^^^^^^^^^^^
: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.
+classes:
+
+.. class:: RawDescriptionHelpFormatter
+ RawTextHelpFormatter
+ 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, :class:`ArgumentParser` objects line-wrap the description_ and
epilog_ texts in command-line help messages::
likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
-Passing :class:`argparse.RawDescriptionHelpFormatter` as ``formatter_class=``
+Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=``
indicates that description_ and epilog_ are already correctly formatted and
should not be line-wrapped::
optional arguments:
-h, --help show this help message and exit
-:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text
+:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
including argument descriptions.
The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`,
The add_argument() method
-------------------------
-.. method:: ArgumentParser.add_argument(name or flags..., [action], [nargs], [const], [default], [type], [choices], [required], [help], [metavar], [dest])
+.. method:: ArgumentParser.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:
* `name or flags`_ - Either a name or a list of option strings, e.g. ``foo``
- or ``-f, --foo``
+ or ``-f, --foo``.
* action_ - The basic type of action to be taken when this argument is
- encountered at the command-line.
+ 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.
+ command line.
- * type_ - The type to which the command-line arg should be converted.
+ * type_ - The type to which the command-line argument should be converted.
* choices_ - A container of the allowable values for the argument.
name or flags
^^^^^^^^^^^^^
-The :meth:`add_argument` method must know whether an optional argument, like
-``-f`` or ``--foo``, or a positional argument, like a list of filenames, is
-expected. 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::
+The :meth:`~ArgumentParser.add_argument` method must know whether an optional
+argument, like ``-f`` or ``--foo``, or a positional argument, like a list of
+filenames, is expected. The first arguments passed to
+:meth:`~ArgumentParser.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')
>>> 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::
+When :meth:`~ArgumentParser.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')
action
^^^^^^
-:class:`ArgumentParser` objects associate command-line args with actions. These
-actions can do just about anything with the command-line args associated with
+:class:`ArgumentParser` objects associate command-line arguments with actions. These
+actions can do just about anything with the command-line arguments associated with
them, though most actions simply add an attribute to the object returned by
-:meth:`parse_args`. The ``action`` keyword argument specifies how the
-command-line args should be handled. The supported actions are:
+:meth:`~ArgumentParser.parse_args`. The ``action`` keyword argument specifies
+how the command-line arguments should be handled. The supported actions are:
* ``'store'`` - This just stores the argument's value. This is the default
- action. For example::
+ action. For example::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
Namespace(foo='1')
* ``'store_const'`` - This stores the value specified by the const_ keyword
- argument. (Note that the const_ keyword argument defaults to the rather
- unhelpful ``None``.) The ``'store_const'`` action is most commonly used with
- optional arguments that specify some sort of flag. For example::
+ argument. (Note that the const_ keyword argument defaults to the rather
+ unhelpful ``None``.) 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 special cases of ``'store_const'``. For
- example::
+* ``'store_true'`` and ``'store_false'`` - These are special cases of
+ ``'store_const'`` using for storing the values ``True`` and ``False``
+ respectively. In addition, they create default values of *False* and *True*
+ respectively. For example::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
+ >>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
- Namespace(bar=False, foo=True)
+ Namespace(bar=False, baz=True, foo=True)
* ``'append'`` - This stores a list, and appends each argument value to the
list. This is useful to allow an option to be specified multiple times.
>>> parser.parse_args('--str --int'.split())
Namespace(types=[<type 'str'>, <type 'int'>])
+* ``'count'`` - This counts the number of times a keyword argument occurs. For
+ example, this is useful for increasing verbosity levels::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--verbose', '-v', action='count')
+ >>> parser.parse_args('-vvv'.split())
+ Namespace(verbose=3)
+
+* ``'help'`` - This prints a complete help message for all the options in the
+ current parser and then exits. By default a help action is automatically
+ added to the parser. See :class:`ArgumentParser` for details of how the
+ output is created.
+
* ``'version'`` - This expects a ``version=`` keyword argument in the
- :meth:`add_argument` call, and prints version information and exits when
- invoked.
+ :meth:`~ArgumentParser.add_argument` call, and prints version information
+ and exits when invoked::
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
* ``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.
+* ``namespace`` - The :class:`Namespace` object that will be returned by
+ :meth:`~ArgumentParser.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`.
+* ``values`` - The associated command-line arguments, with any type conversions
+ applied. (Type conversions are specified with the type_ keyword argument to
+ :meth:`~ArgumentParser.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
ArgumentParser objects usually associate a single command-line argument with a
single action to be taken. The ``nargs`` keyword argument associates a
-different number of command-line arguments with a single action.. The supported
+different number of command-line arguments with a single action. The supported
values are:
-* N (an integer). N args from the command-line will be gathered together into a
- list. For example::
+* ``N`` (an integer). ``N`` arguments from the command line will be gathered
+ together into a list. For example::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
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
+* ``'?'``. One argument will be consumed from the command line if possible, and
+ produced as a single item. If no command-line argument 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
+ command-line argument. In this case the value from const_ will be produced. Some
examples to illustrate this::
>>> parser = argparse.ArgumentParser()
>>> 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...>)
+ 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...>)
+ 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 arguments 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::
* ``'+'``. 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::
+ least one command-line argument present. For example::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
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
+* ``argparse.REMAINDER``. All the remaining command-line arguments are gathered
+ into a list. This is commonly useful for command line utilities that dispatch
+ to other command line utilities::
+
+ >>> parser = argparse.ArgumentParser(prog='PROG')
+ >>> parser.add_argument('--foo')
+ >>> parser.add_argument('command')
+ >>> parser.add_argument('args', nargs=argparse.REMAINDER)
+ >>> print parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())
+ Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
+
+If the ``nargs`` keyword argument is not provided, the number of arguments consumed
+is determined by the action_. Generally this means a single command-line argument
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:
+The ``const`` argument of :meth:`~ArgumentParser.add_argument` is used to hold
+constant values that are not read from the command line but are required for
+the various :class:`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:`~ArgumentParser.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:`~ArgumentParser.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.
+* When :meth:`~ArgumentParser.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 arguments.
+ When parsing the command line, if the option string is encountered with no
+ command-line argument following it, the value of ``const`` will be assumed instead.
+ See the nargs_ description for examples.
The ``const`` keyword argument defaults to ``None``.
^^^^^^^
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::
+command line. The ``default`` keyword argument of
+:meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``,
+specifies what value should be used if the command-line argument 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(''.split())
Namespace(foo=42)
-For positional arguments with nargs_ ``='?'`` or ``'*'``, the ``default`` value
-is used when no command-line arg was present::
+For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value
+is used when no command-line argument was present::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
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, like a :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 built-in types
-can be used directly as the value of the ``type`` argument::
+By default, :class:`ArgumentParser` objects read command-line arguments in as simple
+strings. However, quite often the command-line string should instead be
+interpreted as another type, like a :class:`float` or :class:`int`. The
+``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any
+necessary type-checking and type conversions to be performed. Common built-in
+types and functions can be used directly as the value of the ``type`` argument::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)
``type=`` can take any callable that takes a single string argument and returns
-the type-converted value::
+the converted value::
>>> def perfect_square(string):
... value = int(string)
choices
^^^^^^^
-Some command-line args should be selected from a restricted set of values.
+Some command-line arguments should be selected from a restricted set of values.
These can be handled by passing a container object as the ``choices`` keyword
-argument to :meth:`add_argument`. When the command-line is parsed, arg values
-will be checked, and an error message will be displayed if the arg was not one
-of the acceptable values::
+argument to :meth:`~ArgumentParser.add_argument`. When the command line is
+parsed, argument values will be checked, and an error message will be displayed if
+the argument was not one of the acceptable values::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', choices='abc')
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.
+In general, the :mod:`argparse` module assumes that flags like ``-f`` and ``--bar``
+indicate *optional* arguments, which can always be omitted at the command line.
To make an option *required*, ``True`` can be specified for the ``required=``
-keyword argument to :meth:`add_argument`::
+keyword argument to :meth:`~ArgumentParser.add_argument`::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
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.
+As the example shows, if an option is marked as ``required``,
+:meth:`~ArgumentParser.parse_args` will report an error if that option is not
+present at the command line.
.. note::
The ``help`` value is a string containing a brief description of the argument.
When a user requests help (usually by using ``-h`` or ``--help`` at the
-command-line), these ``help`` descriptions will be displayed with each
+command line), these ``help`` descriptions will be displayed with each
argument::
>>> parser = argparse.ArgumentParser(prog='frobble')
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.::
+:meth:`~ArgumentParser.add_argument`, e.g. ``%(default)s``, ``%(type)s``, etc.::
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
optional arguments:
-h, --help show this help message and exit
+:mod:`argparse` supports silencing the help entry for certain options, by
+setting the ``help`` value to ``argparse.SUPPRESS``::
+
+ >>> parser = argparse.ArgumentParser(prog='frobble')
+ >>> parser.add_argument('--foo', help=argparse.SUPPRESS)
+ >>> parser.print_help()
+ usage: frobble [-h]
+
+ optional arguments:
+ -h, --help show this help message and exit
+
metavar
^^^^^^^
value as the "name" of each object. By default, for positional argument
actions, the dest_ value is used directly, and for optional argument actions,
the dest_ value is uppercased. So, a single positional argument with
-``dest='bar'`` will that argument will be referred to as ``bar``. A single
-optional argument ``--foo`` that should be followed by a single command-line arg
+``dest='bar'`` will be referred to as ``bar``. A single
+optional argument ``--foo`` that should be followed by a single command-line argument
will be referred to as ``FOO``. An example::
>>> parser = argparse.ArgumentParser()
--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.
+attribute on the :meth:`~ArgumentParser.parse_args` object is still determined
+by the dest_ value.
Different values of ``nargs`` may cause the metavar to be used multiple times.
Providing a tuple to ``metavar`` specifies a different display for each of the
^^^^
Most :class:`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`::
+object returned by :meth:`~ArgumentParser.parse_args`. The name of this
+attribute is determined by the ``dest`` keyword argument of
+:meth:`~ArgumentParser.add_argument`. For positional argument actions,
+``dest`` is normally supplied as the first argument to
+:meth:`~ArgumentParser.add_argument`::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
For optional argument actions, the value of ``dest`` is normally inferred from
the option strings. :class:`ArgumentParser` generates 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
-the first short option string by stripping the initial ``'-'`` character. Any
-internal ``'-'`` characters will be converted to ``'_'`` characters to make sure
+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::
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
+ By default, the argument strings are taken from :data:`sys.argv`, and a new empty
:class:`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::
+The :meth:`~ArgumentParser.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')
Namespace(foo='FOO', x=None)
For long options (options with names longer than a single character), the option
-and value can also be passed as a single command line argument, using ``=`` to
+and value can also be passed as a single command-line argument, using ``=`` to
separate them::
>>> parser.parse_args('--foo=FOO'.split())
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::
+While parsing the command line, :meth:`~ArgumentParser.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)
PROG: error: extra arguments found: badger
-Arguments containing ``"-"``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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::
+The :meth:`~ArgumentParser.parse_args` method attempts to give errors whenever
+the user has clearly made a mistake, but some situations are inherently
+ambiguous. For example, the command-line argument ``-1`` could either be an
+attempt to specify an option or an attempt to provide a positional argument.
+The :meth:`~ArgumentParser.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')
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
+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::
+:meth:`~ArgumentParser.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 long options to be abbreviated if the
-abbreviation is unambiguous::
+The :meth:`~ArgumentParser.parse_args` method allows long options to be
+abbreviated if the abbreviation is unambiguous::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
Beyond ``sys.argv``
^^^^^^^^^^^^^^^^^^^
-Sometimes it may be useful to have an ArgumentParser parse args other than those
+Sometimes it may be useful to have an ArgumentParser parse arguments other than those
of :data:`sys.argv`. This can be accomplished by passing a list of strings to
-``parse_args``. This is useful for testing at the interactive prompt::
+:meth:`~ArgumentParser.parse_args`. This is useful for testing at the
+interactive prompt::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
-Custom namespaces
-^^^^^^^^^^^^^^^^^
+The Namespace object
+^^^^^^^^^^^^^^^^^^^^
+
+.. class:: Namespace
+
+ Simple class used by default by :meth:`~ArgumentParser.parse_args` to create
+ an object holding attributes and return it.
+
+This class is deliberately simple, just an :class:`object` subclass with a
+readable string representation. If you prefer to have dict-like view of the
+attributes, you can use the standard Python idiom, :func:`vars`::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--foo')
+ >>> args = parser.parse_args(['--foo', 'BAR'])
+ >>> vars(args)
+ {'foo': 'BAR'}
It may also be useful to have an :class:`ArgumentParser` assign attributes to an
-already existing object, rather than the newly-created :class:`Namespace` object
-that is normally used. This can be achieved by specifying the ``namespace=``
-keyword argument::
+already existing object, rather than a new :class:`Namespace` object. This can
+be achieved by specifying the ``namespace=`` keyword argument::
>>> class C(object):
... pass
:class:`ArgumentParser` supports 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
- :class:`ArgumentParser` constructor arguments, and returns an
- :class:`ArgumentParser` object that can be modified as usual.
+ has a single method, :meth:`~ArgumentParser.add_parser`, which takes a
+ command name and any :class:`ArgumentParser` constructor arguments, and
+ returns an :class:`ArgumentParser` object that can be modified as usual.
Some example usage::
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
>>>
- >>> # parse some arg lists
+ >>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
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
+ the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are
+ present, and when the ``b`` command is specified, only the ``foo`` and
``baz`` attributes are present.
Similarly, when a help message is requested from a subparser, only the help
for that particular parser will be printed. The help message will not
include parent parser or sibling parser messages. (A help message for each
subparser command, however, can be given by supplying the ``help=`` argument
- to ``add_parser`` as above.)
+ to :meth:`add_parser` as above.)
::
>>> args.func(args)
((XYZYX))
- This way, you can let :meth:`parse_args` does the job of calling the
+ This way, you can let :meth:`parse_args` do the job of calling the
appropriate function after argument parsing is complete. Associating
functions with actions like this is typically the easiest way to handle the
different actions for each of your subparsers. However, if it is necessary
The :class:`FileType` factory creates objects that can be passed to the type
argument of :meth:`ArgumentParser.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:
+ :class:`FileType` objects as their type will open command-line arguments as files
+ with the requested modes and buffer sizes::
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('--output', type=argparse.FileType('wb', 0))
- >>> parser.parse_args(['--output', 'out'])
- Namespace(output=<open file 'out', mode 'wb' at 0x...>)
+ >>> 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:
+ ``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...>)
+ >>> 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_mutually_exclusive_group(required=False)
- Create a mutually exclusive group. argparse will make sure that only one of
- the arguments in the mutually exclusive group was present on the command
- line::
+ Create a mutually exclusive group. :mod:`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()
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`.
+ *title* and *description* arguments of
+ :meth:`~ArgumentParser.add_argument_group`.
Parser defaults
.. method:: ArgumentParser.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. :meth:`ArgumentParser.set_defaults` allows some additional
- attributes that are determined without any inspection of the command-line to
+ will be fully determined by inspecting the command-line arguments and the argument
+ actions. :meth:`set_defaults` allows some additional
+ attributes that are determined without any inspection of the command line to
be added::
>>> parser = argparse.ArgumentParser()
Printing help
^^^^^^^^^^^^^
-In most typical applications, :meth:`parse_args` will take care of formatting
-and printing any usage or error messages. However, several formatting methods
-are available:
+In most typical applications, :meth:`~ArgumentParser.parse_args` will take
+care of formatting and printing any usage or error messages. However, several
+formatting methods are available:
.. method:: ArgumentParser.print_usage(file=None)
Print a brief description of how the :class:`ArgumentParser` should be
- invoked on the command line. If *file* is ``None``, :data:`sys.stderr` is
+ invoked on the command line. If *file* is ``None``, :data:`sys.stdout` is
assumed.
.. method:: ArgumentParser.print_help(file=None)
Print a help message, including the program usage and information about the
arguments registered with the :class:`ArgumentParser`. If *file* is
- ``None``, :data:`sys.stderr` is assumed.
+ ``None``, :data:`sys.stdout` is assumed.
There are also variants of these methods that simply return a string instead of
printing it:
.. method:: ArgumentParser.parse_known_args(args=None, namespace=None)
-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
-:meth:`parse_known_args` method can be useful. It works much like
+:meth:`~ArgumentParser.parse_known_args` method can be useful. It works much like
:meth:`~ArgumentParser.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.
.. method:: ArgumentParser.error(message)
This method prints a usage message including the *message* to the
- standard output and terminates the program with a status code of 2.
+ standard error and terminates the program with a status code of 2.
.. _argparse-from-optparse:
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 messages. When most everything in optparse had either been copy-pasted
-over or monkey-patched, it no longer seemed practical to try to maintain the
-backwards compatibility.
+Originally, the :mod:`argparse` module had attempted to maintain compatibility
+with :mod:`optparse`. However, :mod:`optparse` was difficult to extend
+transparently, particularly with the changes required to support the new
+``nargs=`` specifiers and better usage messages. When most everything in
+:mod:`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:
+A partial upgrade path from :mod:`optparse` to :mod:`argparse`:
-* Replace all ``add_option()`` calls with :meth:`ArgumentParser.add_argument` calls.
+* Replace all :meth:`optparse.OptionParser.add_option` calls with
+ :meth:`ArgumentParser.add_argument` calls.
* Replace ``options, args = parser.parse_args()`` with ``args =
- parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument` calls for the
- positional arguments.
+ parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
+ calls for the positional arguments.
* Replace callback actions and the ``callback_*`` keyword arguments with
``type`` or ``action`` arguments.
:exc:`ArgumentError`.
* Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
- the standard python syntax to use dictionaries to format strings, that is,
+ the standard Python syntax to use dictionaries to format strings, that is,
``%(default)s`` and ``%(prog)s``.
* Replace the OptionParser constructor ``version`` argument with a call to
projects / profile / ivi / python.git / blobdiff