Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Merged revisions 78613-78614 via svnmerge from 

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r78613 | benjamin.peterson | 2010-03-02 19:55:09 -0600 (Tue, 02 Mar 2010) | 1 line

  edit for style
........
  r78614 | benjamin.peterson | 2010-03-02 20:04:24 -0600 (Tue, 02 Mar 2010) | 1 line

  fix Sphinx warnings
........
This commit is contained in:
Benjamin Peterson 2010-03-03 02:07:08 +00:00
parent 8f3216a069
commit 98047eb806
1 changed files with 221 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

470
Doc/library/argparse.rst
View File

@ -9,17 +9,16 @@
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 :mod:`argparse` 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` will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse`
module also automatically generates help and usage messages based on the module also automatically generates help and usage messages and issues errors
arguments you have defined, and issues errors when users give your program when users give the program invalid arguments.
invalid arguments.
Example Example
------- -------
As an example, the following code is a Python program that takes a list of The following code is a Python program that takes a list of integers and
integers and produces either the sum or the max:: produces either the sum or the max::
import argparse import argparse
@ -68,24 +67,23 @@ The following sections walk you through this example.
Creating a parser Creating a parser
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
Pretty much every script that uses the :mod:`argparse` module will start out by Mose uses of the :mod:`argparse` module will start out by creating an
creating an :class:`ArgumentParser` object:: :class:`ArgumentParser` object::
>>> parser = argparse.ArgumentParser(description='Process some integers.') >>> parser = argparse.ArgumentParser(description='Process some integers.')
The :class:`ArgumentParser` object will hold all the information necessary to The :class:`ArgumentParser` object will hold all the information necessary to
parse the command line into a more manageable form for your program. parse the command line into python data types.
Adding arguments Adding arguments
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
Once you've created an :class:`ArgumentParser`, you'll want to fill it with Filling an :class:`ArgumentParser` with information about program arguments is
information about your program arguments. You typically do this by making calls done by making calls to the :meth:`~ArgumentParser.add_argument` method.
to the :meth:`add_argument` method. Generally, these calls tell the Generally, these calls tell the :class:`ArgumentParser` how to take the strings
:class:`ArgumentParser` how to take the strings on the command line and turn on the command line and turn them into objects. This information is stored and
them into objects for you. This information is stored and used when used when :meth:`~ArgumentParser.parse_args` is called. For example::
: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='+',
... help='an integer for the accumulator') ... help='an integer for the accumulator')
@ -93,7 +91,7 @@ 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 with Later, calling :meth:`parse_args` will return an object with
two attributes, ``integers`` and ``accumulate``. The ``integers`` attribute two attributes, ``integers`` and ``accumulate``. The ``integers`` attribute
will be a list of one or more ints, and the ``accumulate`` attribute will be 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, either the :func:`sum` function, if ``--sum`` was specified at the command line,
@ -102,9 +100,8 @@ or the :func:`max` function if it was not.
Parsing arguments Parsing arguments
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
Once an :class:`ArgumentParser` has been initialized with appropriate calls to :class:`ArgumentParser` parses args through the
:meth:`add_argument`, it can be instructed to parse the command-line args by :meth:`~ArgumentParser.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 action. 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 In most cases, this means a simple namespace object will be built up from
attributes parsed out of the command-line:: attributes parsed out of the command-line::
@ -112,10 +109,9 @@ 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:`~ArgumentParser.parse_args` will typically be called with no
the :class:`ArgumentParser` will automatically determine the command-line args arguments, and the :class:`ArgumentParser` will automatically determine the
from :data:`sys.argv`. That's pretty much it. You're now ready to go write command-line args from :data:`sys.argv`.
some command line interfaces!
ArgumentParser objects ArgumentParser objects
@ -130,41 +126,41 @@ ArgumentParser objects
* epilog_ - Text to display after the argument help. * epilog_ - Text to display after the argument help.
* add_help_ - Add a -h/--help option to the parser. (default: True) * add_help_ - Add a -h/--help option to the parser. (default: ``True``)
* argument_default_ - Set the global default value for arguments. * argument_default_ - Set the global default value for arguments.
(default: None) (default: ``None``)
* parents_ - A list of :class:ArgumentParser objects whose arguments should * parents_ - A list of :class:`ArgumentParser` objects whose arguments should
also be included. also be included.
* prefix_chars_ - The set of characters that prefix optional arguments. * prefix_chars_ - The set of characters that prefix optional arguments.
(default: '-') (default: '-')
* fromfile_prefix_chars_ - The set of characters that prefix files from * fromfile_prefix_chars_ - The set of characters that prefix files from
which additional arguments should be read. (default: None) which additional arguments should be read. (default: ``None``)
* formatter_class_ - A class for customizing the help output. * formatter_class_ - A class for customizing the help output.
* conflict_handler_ - Usually unnecessary, defines strategy for resolving * conflict_handler_ - Usually unnecessary, defines strategy for resolving
conflicting optionals. conflicting optionals.
* prog_ - Usually unnecessary, the name of the program * prog_ - The name of the program (default:
(default: ``sys.argv[0]``) :data:`sys.argv[0]`)
* usage_ - Usually unnecessary, the string describing the program usage * usage_ - The string describing the program usage (default: generated)
(default: generated)
The following sections describe how each of these are used. The following sections describe how each of these are used.
description description
^^^^^^^^^^^ ^^^^^^^^^^^
Most calls to the ArgumentParser constructor will use the ``description=`` Most calls to the :class:`ArgumentParser` constructor will use the
keyword argument. This argument gives a brief description of what the program ``description=`` keyword argument. This argument gives a brief description of
does and how it works. In help messages, the description is displayed between what the program does and how it works. In help messages, the description is
the command-line usage string and the help messages for the various arguments:: displayed between 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')
>>> parser.print_help() >>> parser.print_help()
@ -201,7 +197,7 @@ argument to :class:`ArgumentParser`::
As with the description_ argument, the ``epilog=`` text is by default As with the description_ argument, the ``epilog=`` text is by default
line-wrapped, but this behavior can be adjusted with the formatter_class_ line-wrapped, but this behavior can be adjusted with the formatter_class_
argument to ArgumentParser. argument to :class:`ArgumentParser`.
add_help add_help
@ -228,7 +224,7 @@ help will be printed::
Occasionally, it may be useful to disable the addition of this help option. Occasionally, it may be useful to disable the addition of this help option.
This can be achieved by passing ``False`` as the ``add_help=`` argument to This can be achieved by passing ``False`` as the ``add_help=`` argument to
ArgumentParser:: :class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help') >>> parser.add_argument('--foo', help='foo help')
@ -261,14 +257,15 @@ disallowed.
fromfile_prefix_chars fromfile_prefix_chars
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
Sometimes, e.g. for particularly long argument lists, it may make sense to keep Sometimes, for example when dealing with a particularly long argument lists, it
the list of arguments in a file rather than typing it out at the command line. may make sense to keep the list of arguments in a file rather than typing it out
If the ``fromfile_prefix_chars=`` argument is given to the ArgumentParser at the command line. If the ``fromfile_prefix_chars=`` argument is given to the
constructor, then arguments that start with any of the specified characters will :class:`ArgumentParser` constructor, then arguments that start with any of the
be treated as files, and will be replaced by the arguments they contain. For specified characters will be treated as files, and will be replaced by the
example:: arguments they contain. For example::
>>> open('args.txt', 'w').write('-f\nbar') >>> with open('args.txt', 'w') as fp:
... fp.write('-f\nbar')
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@') >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f') >>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt']) >>> parser.parse_args(['-f', 'foo', '@args.txt'])
@ -290,9 +287,9 @@ 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 :class:`ArgumentParser`.
example, to globally suppress attribute creation on :meth:`parse_args` calls, we For example, to globally suppress attribute creation on :meth:`parse_args`
supply ``argument_default=SUPPRESS``:: calls, we 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')
@ -307,12 +304,11 @@ 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, a single parser with all the
with all the shared arguments and then use the ``parents=`` argument to shared arguments and passed to ``parents=`` argument to :class:`ArgumentParser`
ArgumentParser to have these "inherited". The ``parents=`` argument takes a can be used. The ``parents=`` argument takes a list of :class:`ArgumentParser`
list of ArgumentParser objects, collects all the positional and optional actions objects, collects all the positional and optional actions from them, and adds
from them, and adds these actions to the ArgumentParser object being these actions to the :class:`ArgumentParser` object being constructed::
constructed::
>>> parent_parser = argparse.ArgumentParser(add_help=False) >>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int) >>> parent_parser.add_argument('--parent', type=int)
@ -328,23 +324,23 @@ constructed::
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 :class:`ArgumentParser` will see two ``-h/--help`` options (one in the parent
the child) and raise an error. and one in the child) and raise an error.
formatter_class formatter_class
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
ArgumentParser objects allow the help formatting to be customized by specifying :class:`ArgumentParser` objects allow the help formatting to be customized by
an alternate formatting class. Currently, there are three such classes: specifying an alternate formatting class. Currently, there are three such
:class:`argparse.RawDescriptionHelpFormatter`, classes: :class:`argparse.RawDescriptionHelpFormatter`,
:class:`argparse.RawTextHelpFormatter` and :class:`argparse.RawTextHelpFormatter` and
:class:`argparse.ArgumentDefaultsHelpFormatter`. The first two allow more :class:`argparse.ArgumentDefaultsHelpFormatter`. The first two allow more
control over how textual descriptions are displayed, while the last control over how textual descriptions are displayed, while the last
automatically adds information about argument default values. automatically adds information about argument default values.
By default, ArgumentParser objects line-wrap the description_ and epilog_ texts By default, :class:`ArgumentParser` objects line-wrap the description_ and
in command-line help messages:: epilog_ texts in command-line help messages::
>>> parser = argparse.ArgumentParser( >>> parser = argparse.ArgumentParser(
... prog='PROG', ... prog='PROG',
@ -366,10 +362,9 @@ in command-line help messages::
likewise for this epilog whose whitespace will be cleaned up and whose words likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines will be wrapped across a couple lines
When you have description_ and epilog_ that is already correctly formatted and Passing :class:`argparse.RawDescriptionHelpFormatter` as ``formatter_class=``
should not be line-wrapped, you can indicate this by passing indicates that description_ and epilog_ are already correctly formatted and
``argparse.RawDescriptionHelpFormatter`` as the ``formatter_class=`` argument to should not be line-wrapped::
ArgumentParser::
>>> parser = argparse.ArgumentParser( >>> parser = argparse.ArgumentParser(
... prog='PROG', ... prog='PROG',
@ -393,10 +388,10 @@ ArgumentParser::
optional arguments: optional arguments:
-h, --help show this help message and exit -h, --help show this help message and exit
If you want to maintain whitespace for all sorts of help text (including :class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text
argument descriptions), you can use ``argparse.RawTextHelpFormatter``. including argument descriptions.
The other formatter class available, ``argparse.ArgumentDefaultsHelpFormatter``, The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`,
will add information about the default value of each of the arguments:: will add information about the default value of each of the arguments::
>>> parser = argparse.ArgumentParser( >>> parser = argparse.ArgumentParser(
@ -418,9 +413,10 @@ will add information about the default value of each of the arguments::
conflict_handler conflict_handler
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
ArgumentParser objects do not allow two actions with the same option string. By :class:`ArgumentParser` objects do not allow two actions with the same option
default, ArgumentParser objects will raise an exception if you try to create an string. By default, :class:`ArgumentParser` objects raises an exception if an
argument with an option string that is already in use:: attempt is made to create an 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')
@ -432,7 +428,7 @@ argument with an option string that is already in use::
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:: :class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve') >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help') >>> parser.add_argument('-f', '--foo', help='old foo help')
@ -445,20 +441,20 @@ ArgumentParser::
-f FOO old foo help -f FOO old foo help
--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 :class:`ArgumentParser` objects only remove an action if all of its
strings are overridden. So, in the example above, the old ``-f/--foo`` action option strings are overridden. So, in the example above, the old ``-f/--foo``
is retained as the ``-f`` action, because only the ``--foo`` option string was action is retained as the ``-f`` action, because only the ``--foo`` option
overridden. string was overridden.
prog prog
^^^^ ^^^^
By default, ArgumentParser objects use ``sys.argv[0]`` to determine how to By default, :class:`ArgumentParser` objects uses ``sys.argv[0]`` to determine
display the name of the program in help messages. This default is almost always how to display the name of the program in help messages. This default is almost
what you want because it will make the help messages match what your users have always desirable because it will make the help messages match how the pgoram was
typed at the command line. For example, consider a file named ``myprogram.py`` invoked on the command line. For example, consider a file named
with the following code:: ``myprogram.py`` with the following code::
import argparse import argparse
parser = argparse.ArgumentParser() parser = argparse.ArgumentParser()
@ -483,7 +479,7 @@ The help for this program will display ``myprogram.py`` as the program name
--foo FOO foo help --foo FOO foo help
To change this default behavior, another value can be supplied using the To change this default behavior, another value can be supplied using the
``prog=`` argument to ArgumentParser:: ``prog=`` argument to :class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser(prog='myprogram') >>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help() >>> parser.print_help()
@ -511,7 +507,7 @@ specifier.
usage usage
^^^^^ ^^^^^
By default, ArgumentParser objects calculate the usage message from the By default, :class:`ArgumentParser` calculates the usage message from the
arguments it contains:: arguments it contains::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
@ -527,9 +523,7 @@ arguments it contains::
-h, --help show this help message and exit -h, --help show this help message and exit
--foo [FOO] foo help --foo [FOO] foo help
If the default usage message is not appropriate for your application, you can The default message can be overridden with the ``usage=`` keyword argument::
supply your own usage message using the ``usage=`` keyword argument to
ArgumentParser::
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]') >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help') >>> parser.add_argument('--foo', nargs='?', help='foo help')
@ -544,14 +538,14 @@ ArgumentParser::
-h, --help show this help message and exit -h, --help show this help message and exit
--foo [FOO] foo help --foo [FOO] foo help
Note you can use the ``%(prog)s`` format specifier to fill in the program name The ``%(prog)s`` format specifier is available to fill in the program name in
in your usage messages. your usage messages.
The add_argument() method The add_argument() method
------------------------- -------------------------
.. method:: 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: has its own more detailed description below, but in short they are:
@ -583,16 +577,16 @@ The add_argument() method
* dest_ - The name of the attribute to be added to the object returned by * dest_ - The name of the attribute to be added to the object returned by
:meth:`parse_args`. :meth:`parse_args`.
The following sections describe how each of these are used. The following sections describe how each of these are used.
name or flags name or flags
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
The :meth:`add_argument` method needs to know whether you're expecting an The :meth:`add_argument` method must know whether an optional argument, like
optional argument, e.g. ``-f`` or ``--foo``, or a positional argument, e.g. a ``-f`` or ``--foo``, or a positional argument, like a list of filenames, is
list of filenames. The first arguments passed to :meth:`add_argument` must expected. The first arguments passed to :meth:`add_argument` must therefore be
therefore be either a series of flags, or a simple argument name. For example, either a series of flags, or a simple argument name. For example, an optional
an optional argument could be created like:: argument could be created like::
>>> parser.add_argument('-f', '--foo') >>> parser.add_argument('-f', '--foo')
@ -620,10 +614,8 @@ 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`. The ``action`` keyword argument specifies how the
:meth:`add_argument` method, you can indicate how the command-line args should command-line args should be handled. The supported actions are:
be handled by specifying the ``action`` keyword argument. The supported actions
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::
@ -634,10 +626,9 @@ 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 the rather
you'll almost always need to provide a value for it. The ``'store_const'`` unhelpful ``None``.) The ``'store_const'`` action is most commonly used with
action is most commonly used with optional arguments that specify some sort optional arguments that specify some sort of flag. For example::
of flag. For example::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42) >>> parser.add_argument('--foo', action='store_const', const=42)
@ -645,8 +636,8 @@ are:
Namespace(foo=42) Namespace(foo=42)
* ``'store_true'`` and ``'store_false'`` - These store the values ``True`` and * ``'store_true'`` and ``'store_false'`` - These store the values ``True`` and
``False`` respectively. These are basically special cases of ``False`` respectively. These are special cases of ``'store_const'``. For
``'store_const'``. For example:: example::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true') >>> parser.add_argument('--foo', action='store_true')
@ -655,8 +646,8 @@ are:
Namespace(bar=False, foo=True) Namespace(bar=False, foo=True)
* ``'append'`` - This stores a list, and appends each argument value to the * ``'append'`` - This stores a list, and appends each argument value to the
list. This is useful when you want to allow an option to be specified list. This is useful to allow an option to be specified multiple times.
multiple times. Example usage:: Example usage::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append') >>> parser.add_argument('--foo', action='append')
@ -664,10 +655,10 @@ are:
Namespace(foo=['1', '2']) Namespace(foo=['1', '2'])
* ``'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 value argument defaults to ``None``.) The ``'append_const'`` action is typically
for it. The ``'append_const'`` action is typically useful when you want useful when multiple arguments need to store constants to the same list. For
multiple arguments to store constants to the same list, for example:: 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)
@ -686,9 +677,9 @@ are:
PROG 2.0 PROG 2.0
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
supplying an appropriate :meth:`__call__` method. The ``__call__`` method :class:`argparse.Action`, supplying an appropriate ``__call__`` method. The
accepts four parameters: ``__call__`` method should accept four parameters:
* ``parser`` - The ArgumentParser object which contains this action. * ``parser`` - The ArgumentParser object which contains this action.
@ -703,7 +694,7 @@ accepts four parameters:
The ``option_string`` argument is optional, and will be absent if the action The ``option_string`` argument is optional, and will be absent if the action
is associated with a positional argument. is associated with a positional argument.
So for example:: An example of a custom action::
>>> class FooAction(argparse.Action): >>> class FooAction(argparse.Action):
... def __call__(self, parser, namespace, values, option_string=None): ... def __call__(self, parser, namespace, values, option_string=None):
@ -724,9 +715,9 @@ 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. The ``nargs`` keyword argument associates a
different number of command-line arguments with a single action, you can use the different number of command-line arguments with a single action.. The supported
``nargs`` keyword argument to :meth:`add_argument`. The supported values are: values are:
* N (an integer). N args from the command-line will be gathered together into a * N (an integer). N args from the command-line will be gathered together into a
list. For example:: list. For example::
@ -846,8 +837,8 @@ is used when no command-line arg was present::
Namespace(foo=42) Namespace(foo=42)
If you don't want to see an attribute when an option was not present at the Providing ``default=argparse.SUPPRESS`` causes no attribute to be added if the
command line, you can supply ``default=argparse.SUPPRESS``:: command-line argument was not present.::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS) >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
@ -862,10 +853,10 @@ 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. :class:`float`, :class:`int` or :class:`file`. The ``type`` another type, like a :class:`float`, :class:`int` or :class:`file`. The
keyword argument of :meth:`add_argument` allows any necessary type-checking and ``type`` keyword argument of :meth:`add_argument` allows any necessary
type-conversions to be performed. Many common builtin types can be used type-checking and type-conversions to be performed. Many common builtin types
directly as the value of the ``type`` argument:: can be used directly as the value of the ``type`` argument::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int) >>> parser.add_argument('foo', type=int)
@ -883,9 +874,8 @@ writable file::
>>> parser.parse_args(['out.txt']) >>> parser.parse_args(['out.txt'])
Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>) Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)
If you need to do some special type-checking or type-conversions, you can ``type=`` can take any callable that takes a single string argument and returns
provide your own types by passing to ``type=`` a callable that takes a single the type-converted value::
string argument and returns the type-converted value::
>>> def perfect_square(string): >>> def perfect_square(string):
... value = int(string) ... value = int(string)
@ -903,8 +893,8 @@ string argument and returns the type-converted value::
usage: PROG [-h] foo usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square PROG: error: argument foo: '7' is not a perfect square
Note that if your type-checking function is just checking for a particular set The choices_ keyword argument may be more convenient for type checkers that
of values, it may be more convenient to use the choices_ keyword argument:: simply check against a range of values::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=xrange(5, 10)) >>> parser.add_argument('foo', type=int, choices=xrange(5, 10))
@ -921,11 +911,10 @@ choices
^^^^^^^ ^^^^^^^
Some command-line args should be selected from a restricted set of values. Some command-line args should be selected from a restricted set of values.
ArgumentParser objects can be told about such sets of values by passing a These can be handled by passing a container object as the ``choices`` keyword
container object as the ``choices`` keyword argument to :meth:`add_argument`. argument to :meth:`add_argument`. When the command-line is parsed, arg values
When the command-line is parsed with :meth:`parse_args`, arg values will be will be checked, and an error message will be displayed if the arg was not one
checked, and an error message will be displayed if the arg was not one of the of the acceptable values::
acceptable values::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', choices='abc') >>> parser.add_argument('foo', choices='abc')
@ -957,9 +946,8 @@ required
In general, the argparse module assumes that flags like ``-f`` and ``--bar`` In general, the argparse module assumes that flags like ``-f`` and ``--bar``
indicate *optional* arguments, which can always be omitted at the command-line. indicate *optional* arguments, which can always be omitted at the command-line.
To change this behavior, i.e. to make an option *required*, the value ``True`` To make an option *required*, ``True`` can be specified for the ``required=``
should be specified for the ``required=`` keyword argument to keyword argument to :meth:`add_argument`::
:meth:`add_argument`::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True) >>> parser.add_argument('--foo', required=True)
@ -972,20 +960,18 @@ should be specified for the ``required=`` keyword argument to
As the example shows, if an option is marked as ``required``, :meth:`parse_args` 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 .. note::
expect *options* to be *optional*. You should avoid the use of required options
whenever possible. Required options are generally considered bad form because users expect
*options* to be *optional*, and thus they should be avoided when possible.
help help
^^^^ ^^^^
A great command-line interface isn't worth anything if your users can't figure The ``help`` value is a string containing a brief description of the argument.
out which option does what. So for the end-users, ``help`` is probably the most When a user requests help (usually by using ``-h`` or ``--help`` at the
important argument to include in your :meth:`add_argument` calls. The ``help`` command-line), these ``help`` descriptions will be displayed with each
value should be a string containing a brief description of what the argument
specifies. When a user requests help (usually by using ``-h`` or ``--help`` at
the command-line), these ``help`` descriptions will be displayed with each
argument:: argument::
>>> parser = argparse.ArgumentParser(prog='frobble') >>> parser = argparse.ArgumentParser(prog='frobble')
@ -1024,15 +1010,14 @@ specifiers include the program name, ``%(prog)s`` and most keyword arguments to
metavar metavar
^^^^^^^ ^^^^^^^
When ArgumentParser objects generate help messages, they need some way to refer When :class:`ArgumentParser` generates help messages, it 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, a single positional argument with
``dest='bar'``, that argument will be referred to as ``bar``. And if we have a ``dest='bar'`` will that argument will be referred to as ``bar``. A single
single optional argument ``--foo`` that should be followed by a single optional argument ``--foo`` that should be followed by a single command-line arg
command-line arg, that arg will be referred to as ``FOO``. You can see this will be referred to as ``FOO``. An example::
behavior in the example below::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo') >>> parser.add_argument('--foo')
@ -1049,9 +1034,7 @@ behavior in the example below::
-h, --help show this help message and exit -h, --help show this help message and exit
--foo FOO --foo FOO
If you would like to provide a different name for your argument in help An alternative name can be specified with ``metavar``::
messages, you can supply a value for the ``metavar`` keyword argument to
:meth:`add_argument`::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY') >>> parser.add_argument('--foo', metavar='YYY')
@ -1073,8 +1056,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, you Providing a tuple to ``metavar`` specifies a different display for each of the
can provide a tuple to ``metavar``:: arguments::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2) >>> parser.add_argument('-x', nargs=2)
@ -1091,10 +1074,10 @@ can provide a tuple to ``metavar``::
dest dest
^^^^ ^^^^
Most ArgumentParser actions add some value as an attribute of the object Most :class:`ArgumentParser` actions add some value as an attribute of the
returned by :meth:`parse_args`. The name of this attribute is determined by the object returned by :meth:`parse_args`. The name of this attribute is determined
``dest`` keyword argument of :meth:`add_argument`. For positional argument by the ``dest`` keyword argument of :meth:`add_argument`. For positional
actions, ``dest`` is normally supplied as the first argument to argument actions, ``dest`` is normally supplied as the first argument to
:meth:`add_argument`:: :meth:`add_argument`::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
@ -1103,7 +1086,7 @@ 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. :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 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
@ -1119,9 +1102,7 @@ behavior::
>>> parser.parse_args('--foo 1 -y 2'.split()) >>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2') Namespace(foo_bar='1', x='2')
If you would like to use a different attribute name from the one automatically ``dest`` allows a custom attribute name to be provided::
inferred by the ArgumentParser, you can supply it with an explicit ``dest``
parameter::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar') >>> parser.add_argument('--foo', dest='bar')
@ -1132,9 +1113,9 @@ parameter::
The parse_args() method The parse_args() method
----------------------- -----------------------
.. method:: parse_args([args], [namespace]) .. method:: ArgumentParser.parse_args([args], [namespace])
Convert the strings to objects and assign them as attributes of the Convert argument 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
@ -1142,7 +1123,7 @@ The parse_args() method
:meth:`add_argument` for details. :meth:`add_argument` for details.
By default, the arg strings are taken from :data:`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. :class:`Namespace` object is created for the attributes.
Option value syntax Option value syntax
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
@ -1159,21 +1140,21 @@ passed as two separate arguments::
>>> parser.parse_args('--foo FOO'.split()) >>> parser.parse_args('--foo FOO'.split())
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), the option
also pass the option and value as a single command line argument, using ``=`` to and value can also be passed as a single command line argument, using ``=`` 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)
For short options (options only one character long), you may simply concatenate For short options (options only one character long), the option and its value
the option and its value:: can be concatenated::
>>> parser.parse_args('-xX'.split()) >>> parser.parse_args('-xX'.split())
Namespace(foo=None, x='X') Namespace(foo=None, x='X')
You can also combine several short options together, using only a single ``-`` Several short options can be joined together, using only a single ``-`` prefix,
prefix, as long as only the last option (or none of them) requires a value:: as long as only the last option (or none of them) requires a value::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true') >>> parser.add_argument('-x', action='store_true')
@ -1263,7 +1244,7 @@ like negative numbers, you can insert the pseudo-argument ``'--'`` which tells
Argument abbreviations Argument abbreviations
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
The :meth:`parse_args` method allows you to abbreviate long options if the The :meth:`parse_args` method allows long options to be abbreviated if the
abbreviation is unambiguous:: abbreviation is unambiguous::
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser = argparse.ArgumentParser(prog='PROG')
@ -1277,8 +1258,7 @@ abbreviation is unambiguous::
usage: PROG [-h] [-bacon BACON] [-badger BADGER] usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon PROG: error: ambiguous option: -ba could match -badger, -bacon
As you can see above, you will get an error if you pick a prefix that could An error is produced for arguments that could produce more than one options.
refer to more than one option.
Beyond ``sys.argv`` Beyond ``sys.argv``
@ -1286,9 +1266,7 @@ 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 args other than those
of :data:`sys.argv`. This can be accomplished by passing a list of strings to of :data:`sys.argv`. This can be accomplished by passing a list of strings to
``parse_args``. You may have noticed that the examples in the argparse ``parse_args``. This is useful for testing at the interactive prompt::
documentation have made heavy use of this calling style - it is much easier to
use at the interactive prompt::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument( >>> parser.add_argument(
@ -1306,9 +1284,10 @@ use at the interactive prompt::
Custom namespaces Custom namespaces
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
It may also be useful to have an ArgumentParser assign attributes to an already It may also be useful to have an :class:`ArgumentParser` assign attributes to an
existing object, rather than the newly-created Namespace object that is normally already existing object, rather than the newly-created :class:`Namespace` object
used. This can be achieved by specifying the ``namespace=`` keyword argument:: that is normally used. This can be achieved by specifying the ``namespace=``
keyword argument::
>>> class C(object): >>> class C(object):
... pass ... pass
@ -1327,19 +1306,19 @@ Other utilities
Sub-commands Sub-commands
^^^^^^^^^^^^ ^^^^^^^^^^^^
.. method:: add_subparsers() .. method:: ArgumentParser.add_subparsers()
A lot of programs split up their functionality into a number of sub-commands, Many programs split up their functionality into a number of sub-commands,
for example, the ``svn`` program can invoke sub-commands like ``svn for example, the ``svn`` program can invoke sub-commands like ``svn
checkout``, ``svn update``, ``svn commit``, etc. Splitting up functionality checkout``, ``svn update``, and ``svn commit``. Splitting up functionality
this way can be a particularly good idea when a program performs several this way can be a particularly good idea when a program performs several
different functions which require different kinds of command-line arguments. different functions which require different kinds of command-line arguments.
ArgumentParser objects support the creation of such sub-commands with the :class:`ArgumentParser` supports the creation of such sub-commands with the
:meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally :meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally
called with no arguments and returns an special action object. This object 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 has a single method, ``add_parser``, which takes a command name and any
ArgumentParser constructor arguments, and returns an ArgumentParser object :class:`ArgumentParser` constructor arguments, and returns an
that can be modified as usual. :class:`ArgumentParser` object that can be modified as usual.
Some example usage:: Some example usage::
@ -1371,9 +1350,9 @@ Sub-commands
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. (A help message for each
help message for each subparser command by suppling the ``help=`` argument to subparser command, however, can be given by supplying the ``help=`` argument
``add_parser`` as above.) to ``add_parser`` as above.)
:: ::
@ -1464,13 +1443,12 @@ Sub-commands
>>> args.func(args) >>> args.func(args)
((XYZYX)) ((XYZYX))
This way, you can let :meth:`parse_args` do all the work for you, and then This way, you can let :meth:`parse_args` does the job of calling the
just call the appropriate function after the argument parsing is complete. appropriate function after argument parsing is complete. Associating
Associating functions with actions like this is typically the easiest way to functions with actions like this is typically the easiest way to handle the
handle the different actions for each of your subparsers. However, if you different actions for each of your subparsers. However, if it is necessary
find it necessary to check the name of the subparser that was invoked, you to check the name of the subparser that was invoked, the ``dest`` keyword
can always provide a ``dest`` keyword argument to the :meth:`add_subparsers` argument to the :meth:`add_subparsers` call will work::
call::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name') >>> subparsers = parser.add_subparsers(dest='subparser_name')
@ -1488,9 +1466,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:`ArgumentParser.add_argument`. Arguments that have
objects as their type will open command-line args as files with the requested :class:`FileType` objects as their type will open command-line args as files
modes and buffer sizes: with the requested 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))
@ -1510,9 +1488,9 @@ FileType objects
Argument groups Argument groups
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
.. method:: add_argument_group([title], [description]) .. method:: ArgumentParser.add_argument_group([title], [description])
By default, ArgumentParser objects group command-line arguments into By default, :class:`ArgumentParser` groups command-line arguments into
"positional arguments" and "optional arguments" when displaying help "positional arguments" and "optional arguments" when displaying help
messages. When there is a better conceptual grouping of arguments than this messages. When there is a better conceptual grouping of arguments than this
default one, appropriate groups can be created using the default one, appropriate groups can be created using the
@ -1530,11 +1508,12 @@ Argument groups
--foo FOO foo help --foo FOO foo help
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:`~ArgumentParser.add_argument` method just like a regular
objects. When an argument is added to the group, the parser treats it just :class:`ArgumentParser`. When an argument is added to the group, the parser
like a normal argument, but displays the argument in a separate group for treats it just like a normal argument, but displays the argument in a
help messages. The :meth:`add_argument_group` method accepts ``title`` and separate group for help messages. The :meth:`add_argument_group` method
``description`` arguments which can be used to customize this display:: accepts ``title`` and ``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)
>>> group1 = parser.add_argument_group('group1', 'group1 description') >>> group1 = parser.add_argument_group('group1', 'group1 description')
@ -1554,8 +1533,8 @@ Argument groups
--bar BAR bar help --bar BAR bar help
Note that any arguments not in your user defined groups will end up back in Note that any arguments not your user defined groups will end up back in the
the usual "positional arguments" and "optional arguments" sections. usual "positional arguments" and "optional arguments" sections.
Mutual exclusion Mutual exclusion
@ -1563,10 +1542,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 Create a mutually exclusive group. argparse will make sure that only one of
is specified on the command line. You can create groups of such mutually
exclusive arguments using the :meth:`add_mutually_exclusive_group` method.
When :func:`parse_args` is called, argparse will make sure that only one of
the arguments in the mutually exclusive group was present on the command the arguments in the mutually exclusive group was present on the command
line:: line::
@ -1595,22 +1571,19 @@ 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`.
may change in the future however, so you are *strongly* recommended to
specify ``required`` as a keyword argument if you use it.
Parser defaults Parser defaults
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
.. method:: set_defaults(**kwargs) .. method:: ArgumentParser.set_defaults(**kwargs)
Most of the time, the attributes of the object returned by :meth:`parse_args` 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 will be fully determined by inspecting the command-line args and the argument
actions described in your :meth:`add_argument` calls. However, sometimes it actions. :meth:`ArgumentParser.set_defaults` allows some additional
may be useful to add some additional attributes that are determined without attributes that are determined without any inspection of the command-line to
any inspection of the command-line. The :meth:`set_defaults` method allows be added::
you to do this::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int) >>> parser.add_argument('foo', type=int)
@ -1618,9 +1591,7 @@ Parser defaults
>>> parser.parse_args(['736']) >>> parser.parse_args(['736'])
Namespace(bar=42, baz='badger', foo=736) Namespace(bar=42, baz='badger', foo=736)
Note that parser-level defaults always override argument-level defaults. So Note that parser-level defaults always override argument-level defaults::
if you set a parser-level default for a name that matches an argument, the
old argument default will no longer be used::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar') >>> parser.add_argument('--foo', default='bar')
@ -1628,14 +1599,15 @@ Parser defaults
>>> parser.parse_args([]) >>> parser.parse_args([])
Namespace(foo='spam') Namespace(foo='spam')
Parser-level defaults can be particularly useful when you're working with Parser-level defaults can be particularly useful when working with multiple
multiple parsers. See the :meth:`add_subparsers` method for an example of parsers. See the :meth:`~ArgumentParser.add_subparsers` method for an
this type. example of this type.
.. method:: get_default(dest) .. method:: ArgumentParser.get_default(dest)
Get the default value for a namespace attribute, as set by either Get the default value for a namespace attribute, as set by either
:meth:`add_argument` or by :meth:`set_defaults`:: :meth:`~ArgumentParser.add_argument` or by
:meth:`~ArgumentParser.set_defaults`::
>>> parser = argparse.ArgumentParser() >>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger') >>> parser.add_argument('--foo', default='badger')
@ -1647,16 +1619,16 @@ 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, several formatting methods
print these on your own, several methods are available: are available:
.. method:: print_usage([file]): .. method:: ArgumentParser.print_usage([file]):
Print a brief description of how the :class:`ArgumentParser` should be Print a brief description of how the :class:`ArgumentParser` should be
invoked on the command line. If ``file`` is not present, ``sys.stderr`` is invoked on the command line. If ``file`` is not present, ``sys.stderr`` is
assumed. assumed.
.. method:: print_help([file]): .. method:: ArgumentParser.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
@ -1665,12 +1637,12 @@ print these on your own, several methods are available:
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
printing it: printing it:
.. method:: format_usage(): .. method:: ArgumentParser.format_usage():
Return a string containing a brief description of how the Return a string containing a brief description of how the
:class:`ArgumentParser` should be invoked on the command line. :class:`ArgumentParser` should be invoked on the command line.
.. method:: format_help(): .. method:: ArgumentParser.format_help():
Return a string containing a help message, including the program usage and Return a string containing a help message, including the program usage and
information about the arguments registered with the :class:`ArgumentParser`. information about the arguments registered with the :class:`ArgumentParser`.
@ -1680,14 +1652,14 @@ printing it:
Partial parsing Partial parsing
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
.. method:: parse_known_args([args], [namespace]) .. method:: ArgumentParser.parse_known_args([args], [namespace])
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 arguments :meth:`~ArgumentParser.parse_args` except that it does not produce an error when
are present. Instead, it returns a two item tuple containing the populated extra arguments are present. Instead, it returns a two item tuple containing
namespace and the list of remaining argument strings. the populated namespace and the list of remaining argument strings.
:: ::
@ -1701,13 +1673,12 @@ namespace and the list of remaining argument strings.
Customizing file parsing Customizing file parsing
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
.. method:: convert_arg_line_to_args(arg_line) .. method:: ArgumentParser.convert_arg_line_to_args(arg_line)
Arguments that are read from a file (see the ``fromfile_prefix_chars`` Arguments that are read from a file (see the ``fromfile_prefix_chars``
keyword argument to the :class:`ArgumentParser` constructor) are read one keyword argument to the :class:`ArgumentParser` constructor) are read one
argument per line. If you need fancier parsing, then you can subclass the argument per line. :meth:`convert_arg_line_to_args` can be overriden for
:class:`ArgumentParser` and override the :meth:`convert_arg_line_to_args` fancier reading.
method.
This method takes a single argument ``arg_line`` which is a string read from This method takes a single argument ``arg_line`` which is a string read from
the argument file. It returns a list of arguments parsed from this string. the argument file. It returns a list of arguments parsed from this string.
@ -1735,10 +1706,10 @@ 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:`ArgumentParser.add_argument` calls.
* Replace ``options, args = parser.parse_args()`` with ``args = * Replace ``options, args = parser.parse_args()`` with ``args =
parser.parse_args()`` and add additional :meth:`add_argument` calls for the parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument` calls for the
positional arguments. positional arguments.
* Replace callback actions and the ``callback_*`` keyword arguments with * Replace callback actions and the ``callback_*`` keyword arguments with
@ -1747,8 +1718,9 @@ A partial upgrade path from optparse to argparse:
* Replace string names for ``type`` keyword arguments with the corresponding * Replace string names for ``type`` keyword arguments with the corresponding
type objects (e.g. int, float, complex, etc). type objects (e.g. int, float, complex, etc).
* Replace ``Values`` with ``Namespace`` and ``OptionError/OptionValueError`` * Replace :class:`optparse.Values` with :class:`Namespace` and
with ``ArgumentError``. :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with
:exc:`ArgumentError`.
* Replace strings with implicit arguments such as ``%default`` or ``%prog`` with * 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,