argparse – Command line option and argument parsing.¶

argparse – Command line option and argument parsing. - Python Module of the Week

argparse – Command line option and argument parsing.¶

Purpose:	Command line option and argument parsing.
Available In:	2.7 and later

The argparse module was added to Python 2.7 as a replacement
for optparse. The implementation of argparse supports
features that would not have been easy to add to optparse, and
that would have required backwards-incompatible API changes, so a new
module was brought into the library instead. optparse is still
supported, but is not likely to receive new features.

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

Argument Actions¶

There are six built-in actions that can be triggered when an argument
is encountered:

store

Save the value, after optionally converting it to a different type.
This is the default action taken if none is specified expliclity.

store_const

Save a value defined as part of the argument specification, rather
than a value that comes from the arguments being parsed. This is
typically used to implement command line flags that aren’t booleans.

store_true / store_false

Save the appropriate boolean value. These actions are used to
implement boolean switches.

append

Save the value to a list. Multiple values are saved if the argument
is repeated.

append_const

Save a value defined in the argument specification to a list.

version

Prints version details about the program and then exits.

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

Option Prefixes¶

The default syntax for options is based on the Unix convention of
signifying command line switches using a prefix of “-”.
argparse supports other prefixes, so you can make your program
conform to the local platform default (i.e., use “/” on Windows)
or follow a different convention.

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()

Set the prefix_chars parameter for the ArgumentParser to a
string containing all of the characters that should be allowed to
signify options. It is important to understand that although
prefix_chars establishes the allowed switch characters, the
individual argument definitions specify the syntax for a given switch.
This gives you explicit control over whether options using different
prefixes are aliases (such as might be the case for
platform-independent command line syntax) or alternatives (e.g., using
“+” to indicate turning a switch on and “-” to turn it off).
In the example above, +a and -a are separate arguments, and
//noarg can also be given as ++noarg, but not --noarg.

$ 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

Sources of Arguments¶

In the examples so far, the list of arguments given to the parser have
come from a list passed in explicitly, or were taken implicitly from
sys.argv. Passing the list explicitly is useful
when you are using argparse to process command line-like
instructions that do not come from the command line (such as in a
configuration file).

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)

shlex makes it easy to split the string stored in the
configuration file.

$ python argparse_with_shlex.py

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