argparse – Command line option and argument parsing.

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

The module was added to Python 2.7 as a replacement

for . The implementation of supports

features that would not have been easy to add to , and

that would have required backwards-incompatible API changes, so a new

module was brought into the library instead. is still

supported, but is not likely to receive new features.

Comparing with optparse

The API for is similar to the one provided by

, and in many cases 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 , 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 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 argparseparser = argparse.ArgumentParser(description='This is a PyMOTW sample program')

Defining Arguments

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 argparseparser = 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.pyNamespace(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 argparseparser = 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.pyNamespace(noarg=True, witharg='val', witharg2=3)

One area in which differs from is the

treatment of non-optional argument values. While

sticks to option parsing, is a full command-line

argument parser tool, and handles non-optional arguments as well.

import argparseparser = 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 inchesNamespace(count=3, units='inches')$ python argparse_arguments.py some inchesusage: argparse_arguments.py [-h] count unitsargparse_arguments.py: error: argument count: invalid int value: 'some'$ python argparse_arguments.pyusage: argparse_arguments.py [-h] count unitsargparse_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 argparseparser = 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_valueprint 'constant_value   =', results.constant_valueprint 'boolean_switch   =', results.boolean_switchprint 'collection       =', results.collectionprint 'const_collection =', results.const_collection

$ python argparse_action.py -husage: 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 valuesimple_value     = valueconstant_value   = Noneboolean_switch   = Falsecollection       = []const_collection = []$ python argparse_action.py -csimple_value     = Noneconstant_value   = value-to-storeboolean_switch   = Falsecollection       = []const_collection = []$ python argparse_action.py -tsimple_value     = Noneconstant_value   = Noneboolean_switch   = Truecollection       = []const_collection = []$ python argparse_action.py -fsimple_value     = Noneconstant_value   = Noneboolean_switch   = Falsecollection       = []const_collection = []$ python argparse_action.py -a one -a two -a threesimple_value     = Noneconstant_value   = Noneboolean_switch   = Falsecollection       = ['one', 'two', 'three']const_collection = []$ python argparse_action.py -B -Asimple_value     = Noneconstant_value   = Noneboolean_switch   = Falsecollection       = []const_collection = ['value-2-to-append', 'value-1-to-append']$ python argparse_action.py --versionargparse_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 “-”.

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 argparseparser = 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 -husage: argparse_prefix_chars.py [-h] [-a] [+a] [//noarg]Change the option prefix charactersoptional arguments:  -h, --help        show this help message and exit  -a                Turn A off  +a                Turn A on  //noarg, ++noarg$ python argparse_prefix_chars.py +aNamespace(a=True, noarg=False)$ python argparse_prefix_chars.py -aNamespace(a=False, noarg=False)$ python argparse_prefix_chars.py //noargNamespace(a=None, noarg=True)$ python argparse_prefix_chars.py ++noargNamespace(a=None, noarg=True)$ python argparse_prefix_chars.py --noargusage: 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

. Passing the list explicitly is useful

when you are using to process command line-like

instructions that do not come from the command line (such as in a

configuration file).

import argparsefrom ConfigParser import ConfigParserimport shlexparser = 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_valueargument_list = shlex.split(config_value)print 'Arg List:', argument_listprint 'Results :', parser.parse_args(argument_list)

makes it easy to split the string stored in the

configuration file.

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