Comparing with optparse¶

The API for argparse is similar to the one provided by
optparse, and in many cases argparse can be used as a
straightforward replacement by updating the names of the classes and
methods used. There are a few places where direct compatibility could
not be preserved as new features were added, however.

You will have to decide whether to upgrade existing programs on a
case-by-case basis. If you have written extra code to work around
limitations of optparse, you may want to upgrade to reduce the
amount of code you need to maintain. New programs should probably use
argparse, if it is available on all deployment platforms.

Setting up a Parser¶

The first step when using argparse is to create a parser object
and tell it what arguments to expect. The parser can then be used to
process the command line arguments when your program runs.

The parser class is ArgumentParser. The constructor takes
several arguments to set up the description used in the help text for
the program and other global behaviors or settings.

import argparse
parser = argparse.ArgumentParser(description='This is a PyMOTW sample program')

Defining Arguments¶

argparse is a complete argument processing library. Arguments
can trigger different actions, specified by the action argument to
add_argument(). Supported actions include storing the argument
(singly, or as part of a list), storing a constant value when the
argument is encountered (including special handling for true/false
values for boolean switches), counting the number of times an argument
is seen, and calling a callback.

The default action is to store the argument value. In this case, if a
type is provided, the value is converted to that type before it is
stored. If the dest argument is provided, the value is saved to an
attribute of that name on the Namespace object returned when the
command line arguments are parsed.

Parsing a Command Line¶

Once all of the arguments are defined, you can parse the command line
by passing a sequence of argument strings to parse_args(). By
default, the arguments are taken from sys.argv[1:], but you can
also pass your own list. The options are processed using the GNU/POSIX
syntax, so option and argument values can be mixed in the sequence.

The return value from parse_args() is a Namespace
containing the arguments to the command. The object holds the argument
values as attributes, so if your argument dest is "myoption",
you access the value as args.myoption.

Simple Examples¶

Here is a simple example with 3 different options: a boolean option
(-a), a simple string option (-b), and an integer option
(-c).

import argparse
parser = argparse.ArgumentParser(description='Short sample app')
parser.add_argument('-a', action="store_true", default=False)
parser.add_argument('-b', action="store", dest="b")
parser.add_argument('-c', action="store", dest="c", type=int)
print parser.parse_args(['-a', '-bval', '-c', '3'])

There are a few ways to pass values to single character options. The
example above uses two different forms, -bval and -c val.

$ python argparse_short.py
Namespace(a=True, b='val', c=3)

The type of the value associated with 'c' in the output is an
integer, since the ArgumentParser was told to convert the
argument before storing it.

“Long” option names, with more than a single character in their name,
are handled in the same way.

import argparse
parser = argparse.ArgumentParser(description='Example with long option names')
parser.add_argument('--noarg', action="store_true", default=False)
parser.add_argument('--witharg', action="store", dest="witharg")
parser.add_argument('--witharg2', action="store", dest="witharg2", type=int)
print parser.parse_args([ '--noarg', '--witharg', 'val', '--witharg2=3' ])

And the results are similar:

$ python argparse_long.py
Namespace(noarg=True, witharg='val', witharg2=3)

One area in which argparse differs from optparse is the
treatment of non-optional argument values. While optparse
sticks to option parsing, argparse is a full command-line
argument parser tool, and handles non-optional arguments as well.

import argparse
parser = argparse.ArgumentParser(description='Example with non-optional arguments')
parser.add_argument('count', action="store", type=int)
parser.add_argument('units', action="store")
print parser.parse_args()

In this example, the “count” argument is an integer and the “units”
argument is saved as a string. If either is not provided on the
command line, or the value given cannot be converted to the right
type, an error is reported.

$ python argparse_arguments.py 3 inches
Namespace(count=3, units='inches')
$ python argparse_arguments.py some inches
usage: argparse_arguments.py [-h] count units
argparse_arguments.py: error: argument count: invalid int value: 'some'
$ python argparse_arguments.py
usage: argparse_arguments.py [-h] count units
argparse_arguments.py: error: too few arguments

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-s', action='store', dest='simple_value',
                    help='Store a simple value')
parser.add_argument('-c', action='store_const', dest='constant_value',
                    const='value-to-store',
                    help='Store a constant value')
parser.add_argument('-t', action='store_true', default=False,
                    dest='boolean_switch',
                    help='Set a switch to true')
parser.add_argument('-f', action='store_false', default=False,
                    dest='boolean_switch',
                    help='Set a switch to false')
parser.add_argument('-a', action='append', dest='collection',
                    default=[],
                    help='Add repeated values to a list',
                    )
parser.add_argument('-A', action='append_const', dest='const_collection',
                    const='value-1-to-append',
                    default=[],
                    help='Add different values to list')
parser.add_argument('-B', action='append_const', dest='const_collection',
                    const='value-2-to-append',
                    help='Add different values to list')
parser.add_argument('--version', action='version', version='%(prog)s 1.0')
results = parser.parse_args()
print 'simple_value     =', results.simple_value
print 'constant_value   =', results.constant_value
print 'boolean_switch   =', results.boolean_switch
print 'collection       =', results.collection
print 'const_collection =', results.const_collection

$ python argparse_action.py -h
usage: argparse_action.py [-h] [-s SIMPLE_VALUE] [-c] [-t] [-f]
                          [-a COLLECTION] [-A] [-B] [--version]
optional arguments:
  -h, --help       show this help message and exit
  -s SIMPLE_VALUE  Store a simple value
  -c               Store a constant value
  -t               Set a switch to true
  -f               Set a switch to false
  -a COLLECTION    Add repeated values to a list
  -A               Add different values to list
  -B               Add different values to list
  --version        show program's version number and exit
$ python argparse_action.py -s value
simple_value     = value
constant_value   = None
boolean_switch   = False
collection       = []
const_collection = []
$ python argparse_action.py -c
simple_value     = None
constant_value   = value-to-store
boolean_switch   = False
collection       = []
const_collection = []
$ python argparse_action.py -t
simple_value     = None
constant_value   = None
boolean_switch   = True
collection       = []
const_collection = []
$ python argparse_action.py -f
simple_value     = None
constant_value   = None
boolean_switch   = False
collection       = []
const_collection = []
$ python argparse_action.py -a one -a two -a three
simple_value     = None
constant_value   = None
boolean_switch   = False
collection       = ['one', 'two', 'three']
const_collection = []
$ python argparse_action.py -B -A
simple_value     = None
constant_value   = None
boolean_switch   = False
collection       = []
const_collection = ['value-2-to-append', 'value-1-to-append']
$ python argparse_action.py --version
argparse_action.py 1.0

import argparse
parser = argparse.ArgumentParser(description='Change the option prefix characters',
                                 prefix_chars='-+/',
                                 )
parser.add_argument('-a', action="store_false", default=None,
                    help='Turn A off',
                    )
parser.add_argument('+a', action="store_true", default=None,
                    help='Turn A on',
                    )
parser.add_argument('//noarg', '++noarg', action="store_true", default=False)
print parser.parse_args()

$ python argparse_prefix_chars.py -h
usage: argparse_prefix_chars.py [-h] [-a] [+a] [//noarg]
Change the option prefix characters
optional arguments:
  -h, --help        show this help message and exit
  -a                Turn A off
  +a                Turn A on
  //noarg, ++noarg
$ python argparse_prefix_chars.py +a
Namespace(a=True, noarg=False)
$ python argparse_prefix_chars.py -a
Namespace(a=False, noarg=False)
$ python argparse_prefix_chars.py //noarg
Namespace(a=None, noarg=True)
$ python argparse_prefix_chars.py ++noarg
Namespace(a=None, noarg=True)
$ python argparse_prefix_chars.py --noarg
usage: argparse_prefix_chars.py [-h] [-a] [+a] [//noarg]
argparse_prefix_chars.py: error: unrecognized arguments: --noarg

import argparse
from ConfigParser import ConfigParser
import shlex
parser = argparse.ArgumentParser(description='Short sample app')
parser.add_argument('-a', action="store_true", default=False)
parser.add_argument('-b', action="store", dest="b")
parser.add_argument('-c', action="store", dest="c", type=int)
config = ConfigParser()
config.read('argparse_witH_shlex.ini')
config_value = config.get('cli', 'options')
print 'Config  :', config_value
argument_list = shlex.split(config_value)
print 'Arg List:', argument_list
print 'Results :', parser.parse_args(argument_list)

$ python argparse_with_shlex.py
Config  : -a -b 2
Arg List: ['-a', '-b', '2']
Results : Namespace(a=True, b='2', c=None)