optparse – Command line option parser to replace getopt.

Purpose:Command line option parser to replace getopt.
Available In:2.3

The optparse module is a modern alternative for command line option parsing that offers several features not available in getopt, including type conversion, option callbacks, and automatic help generation. There are many more features to optparse than can be covered here, but this section will introduce some of the more commonly used capabilities.

Creating an OptionParser

There are two phases to parsing options with optparse. First, the OptionParser instance is constructed and configured with the expected options. Then a sequence of options is fed in and processed.

import optparse
parser = optparse.OptionParser()

Usually, once the parser has been created, each option is added to the parser explicitly, with information about what to do when the option is encountered on the command line. It is also possible to pass a list of options to the OptionParser constructor, but that form is not used as frequently.

Defining Options

Options should be added one at a time using the add_option() method. Any un-named string arguments at the beginning of the argument list are treated as option names. To create aliases for an option (i.e., to have a short and long form of the same option), simply pass multiple names.

Parsing a Command Line

After all of the options are defined, the command line is parsed by passing a sequence of argument strings to parse_args(). By default, the arguments are taken from sys.argv[1:], but a list can be passed explicitly as well. 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 two-part tuple containing an Values instance and the list of arguments to the command that were not interpreted as options. The default processing action for options is to store the value using the name given in the dest argument to add_option(). The Values instance returned by parse_args() holds the option values as attributes, so if an option’s dest is set to "myoption", the value is accessed as options.myoption.

Short and Long-Form Options

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

import optparse

parser = optparse.OptionParser()
parser.add_option('-a', action="store_true", default=False)
parser.add_option('-b', action="store", dest="b")
parser.add_option('-c', action="store", dest="c", type="int")

print parser.parse_args(['-a', '-bval', '-c', '3'])

The options on the command line are parsed with the same rules that getopt.gnu_getopt() uses, so there are two ways to pass values to single character options. The example above uses both forms, -bval and -c val.

$ python optparse_short.py

(<Values at 0x1004cf488: {'a': True, 'c': 3, 'b': 'val'}>, [])

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

Unlike with getopt, “long” option names are not handled any differently by optparse:

import optparse

parser = optparse.OptionParser()
parser.add_option('--noarg', action="store_true", default=False)
parser.add_option('--witharg', action="store", dest="witharg")
parser.add_option('--witharg2', action="store", dest="witharg2", type="int")

print parser.parse_args([ '--noarg', '--witharg', 'val', '--witharg2=3' ])

And the results are similar:

$ python optparse_long.py

(<Values at 0x1004d9488: {'noarg': True, 'witharg': 'val', 'witharg2': 3}>, [])

Comparing with getopt

Since optparse is supposed to replace getopt, this example re-implements the same example program used in the section about getopt:

import optparse
import sys

print 'ARGV      :', sys.argv[1:]

parser = optparse.OptionParser()
parser.add_option('-o', '--output', 
                  dest="output_filename", 
                  default="default.out",
                  )
parser.add_option('-v', '--verbose',
                  dest="verbose",
                  default=False,
                  action="store_true",
                  )
parser.add_option('--version',
                  dest="version",
                  default=1.0,
                  type="float",
                  )
options, remainder = parser.parse_args()

print 'VERSION   :', options.version
print 'VERBOSE   :', options.verbose
print 'OUTPUT    :', options.output_filename
print 'REMAINING :', remainder

Notice how the options -o and --output are aliased by being added at the same time. Either option can be used on the command line. The short form:

$ python optparse_getoptcomparison.py -o output.txt

ARGV      : ['-o', 'output.txt']
VERSION   : 1.0
VERBOSE   : False
OUTPUT    : output.txt
REMAINING : []

or the long form:

$ python optparse_getoptcomparison.py --output output.txt

ARGV      : ['--output', 'output.txt']
VERSION   : 1.0
VERBOSE   : False
OUTPUT    : output.txt
REMAINING : []

Any unique prefix of the long option can also be used:

$ python optparse_getoptcomparison.py --out output.txt

ARGV      : ['--out', 'output.txt']
VERSION   : 1.0
VERBOSE   : False
OUTPUT    : output.txt
REMAINING : []

Option Values

The default processing action is to store the argument to the option. If a type is provided, the argument value is converted to that type before it is stored.

Setting Defaults

Since options are by definition optional, applications should establish default behavior when an option is not given on the command line. A default value for an individual option can be provided when the option is defined.

import optparse

parser = optparse.OptionParser()
parser.add_option('-o', action="store", default="default value")

options, args = parser.parse_args()

print options.o
$ python optparse_default.py

default value

$ python optparse_default.py -o "different value"

different value

Defaults can also be loaded after the options are defined using keyword arguments to set_defaults().

import optparse

parser = optparse.OptionParser()
parser.add_option('-o', action="store")

parser.set_defaults(o='default value')

options, args = parser.parse_args()

print options.o

This form is useful when loading defaults from a configuration file or other source, instead of hard-coding them.

$ python optparse_set_defaults.py

default value

$ python optparse_set_defaults.py -o "different value"

different value

All defined options are available as attributes of the Values instance returned by parse_args() so applications do not need to check for the presence of an option before trying to use its value.

import optparse

parser = optparse.OptionParser()
parser.add_option('-o', action="store")

options, args = parser.parse_args()

print options.o

If no default value is given for an option, and the option is not specified on the command line, its value is None.

$ python optparse_no_default.py

None

$ python optparse_no_default.py -o "different value"

different value

Type Conversion

optparse will convert option values from strings to integers, floats, longs, and complex values. To enable the conversion, specify the type of the option as an argument to add_option().

import optparse

parser = optparse.OptionParser()
parser.add_option('-i', action="store", type="int")
parser.add_option('-f', action="store", type="float")
parser.add_option('-l', action="store", type="long")
parser.add_option('-c', action="store", type="complex")

options, args = parser.parse_args()

print 'int    : %-16r %s' % (type(options.i), options.i)
print 'float  : %-16r %s' % (type(options.f), options.f)
print 'long   : %-16r %s' % (type(options.l), options.l)
print 'complex: %-16r %s' % (type(options.c), options.c)

If an option’s value cannot be converted to the specified type, an error is printed and the program exits.

$ python optparse_types.py -i 1 -f 3.14 -l 1000000 -c 1+2j

int    : <type 'int'>     1
float  : <type 'float'>   3.14
long   : <type 'long'>    1000000
complex: <type 'complex'> (1+2j)

$ python optparse_types.py -i a

Usage: optparse_types.py [options]

optparse_types.py: error: option -i: invalid integer value: 'a'

Custom conversions can be created by subclassing the Option class. See the standard library documentation for complete details.

Enumerations

The choice type provides validation using a list of candidate strings. Set type to choice and provide the list of valid values using the choices argument to add_option().

import optparse

parser = optparse.OptionParser()

parser.add_option('-c', type='choice', choices=['a', 'b', 'c'])

options, args = parser.parse_args()

print 'Choice:', options.c

Invalid inputs result in an error message that shows the allowed list of values.

$ python optparse_choice.py -c a

Choice: a

$ python optparse_choice.py -c b

Choice: b

$ python optparse_choice.py -c d

Usage: optparse_choice.py [options]

optparse_choice.py: error: option -c: invalid choice: 'd' (choose from
 'a', 'b', 'c')

Option Actions

Unlike getopt, which only parses the options, optparse is a full option processing library. Options can trigger different actions, specified by the action argument to add_option(). Supported actions include storing the argument (singly, or as part of a list), storing a constant value when the option is encountered (including special handling for true/false values for boolean switches), counting the number of times an option is seen, and calling a callback. The default action is store, and does not need to be specified explicitly.

Constants

When options represent a selection of fixed alternatives, such as operating modes of an application, creating separate explicit options makes it easier to document them. The store_const action is intended for this purpose.

import optparse

parser = optparse.OptionParser()
parser.add_option('--earth', action="store_const", const='earth', dest='element', default='earth')
parser.add_option('--air', action='store_const', const='air', dest='element')
parser.add_option('--water', action='store_const', const='water', dest='element')
parser.add_option('--fire', action='store_const', const='fire', dest='element')

options, args = parser.parse_args()

print options.element

The store_const action associates a constant value in the application with the option specified by the user. Several options can be configured to store different constant values to the same dest name, so the application only has to check a single setting.

$ python optparse_store_const.py

earth

$ python optparse_store_const.py --fire

fire

Boolean Flags

Boolean options are implemented using special actions for storing true and false constant values.

import optparse

parser = optparse.OptionParser()
parser.add_option('-t', action='store_true', default=False, dest='flag')
parser.add_option('-f', action='store_false', default=False, dest='flag')

options, args = parser.parse_args()

print 'Flag:', options.flag

True and false versions of the same flag can be created by configuring their dest name to the same value.

$ python optparse_boolean.py

Flag: False

$ python optparse_boolean.py -t

Flag: True

$ python optparse_boolean.py -f

Flag: False

Repeating Options

There are three ways to handle repeated options. The default is to overwrite any existing value so that the last option specified is used. The store action works this way.

Using the append action, it is possible to accumulate values as an option is repeated, creating a list of values. Append mode is useful when multiple responses are allowed, and specifying them separately is easier for the user than constructing a parsable syntax.

import optparse

parser = optparse.OptionParser()
parser.add_option('-o', action="append", dest='outputs', default=[])

options, args = parser.parse_args()

print options.outputs

The order of the values given on the command line is preserved, in case it is important for the application.

$ python optparse_append.py

[]

$ python optparse_append.py -o a.out

['a.out']

$ python optparse_append.py -o a.out -o b.out

['a.out', 'b.out']

Sometimes it is enough to know how many times an option was given, and the associated value is not needed. For example, many applications allow the user to repeat the -v option to increase the level of verbosity of their output. The count action increments a value each time the option appears.

import optparse

parser = optparse.OptionParser()
parser.add_option('-v', action="count", dest='verbosity', default=1)
parser.add_option('-q', action='store_const', const=0, dest='verbosity')

options, args = parser.parse_args()

print options.verbosity

Since the -v option doesn’t take an argument, it can be repeated using the syntax -vv as well as through separate individual options.

$ python optparse_count.py

1

$ python optparse_count.py -v

2

$ python optparse_count.py -v -v

3

$ python optparse_count.py -vv

3

$ python optparse_count.py -q

0

Callbacks

Beside saving the arguments for options directly, it is possible to define callback functions to be invoked when the option is encountered on the command line. Callbacks for options take four arguments: the Option instance causing the callback, the option string from the command line, any argument value associated with the option, and the OptionParser instance doing the parsing work.

import optparse

def flag_callback(option, opt_str, value, parser):
    print 'flag_callback:'
    print '\toption:', repr(option)
    print '\topt_str:', opt_str
    print '\tvalue:', value
    print '\tparser:', parser
    return

def with_callback(option, opt_str, value, parser):
    print 'with_callback:'
    print '\toption:', repr(option)
    print '\topt_str:', opt_str
    print '\tvalue:', value
    print '\tparser:', parser
    return

parser = optparse.OptionParser()
parser.add_option('--flag', action="callback", callback=flag_callback)
parser.add_option('--with', 
                  action="callback",
                  callback=with_callback,
                  type="string",
                  help="Include optional feature")

parser.parse_args(['--with', 'foo', '--flag'])

In this example, the --with option is configured to take a string argument (other types such as integers and floats are support as well).

$ python optparse_callback.py

with_callback:
        option: <Option at 0x1004cf2d8: --with>
        opt_str: --with
        value: foo
        parser: <optparse.OptionParser instance at 0x1004675a8>
flag_callback:
        option: <Option at 0x100467830: --flag>
        opt_str: --flag
        value: None
        parser: <optparse.OptionParser instance at 0x1004675a8>

Callbacks can be configured to take multiple arguments using the nargs option.

import optparse

def with_callback(option, opt_str, value, parser):
    print 'with_callback:'
    print '\toption:', repr(option)
    print '\topt_str:', opt_str
    print '\tvalue:', value
    print '\tparser:', parser
    return

parser = optparse.OptionParser()
parser.add_option('--with', 
                  action="callback",
                  callback=with_callback,
                  type="string",
                  nargs=2,
                  help="Include optional feature")

parser.parse_args(['--with', 'foo', 'bar'])

In this case, the arguments are passed to the callback function as a tuple via the value argument.

$ python optparse_callback_nargs.py

with_callback:
        option: <Option at 0x100467758: --with>
        opt_str: --with
        value: ('foo', 'bar')
        parser: <optparse.OptionParser instance at 0x1004674d0>

Help Messages

The OptionParser automatically includes a help option to all option sets, so the user can pass --help on the command line to see instructions for running the program. The help message includes all of the options with an indication of whether or not they take an argument. It is also possible to pass help text to add_option() to give a more verbose description of an option.

import optparse

parser = optparse.OptionParser()
parser.add_option('--no-foo', action="store_true", 
                  default=False, 
                  dest="foo",
                  help="Turn off foo",
                  )
parser.add_option('--with', action="store", help="Include optional feature")

parser.parse_args()

The options are listed in alphabetical order, with aliases included on the same line. When the option takes an argument, the dest name is included as an argument name in the help output. The help text is printed in the right column.

$ python optparse_help.py --help

Usage: optparse_help.py [options]

Options:
  -h, --help   show this help message and exit
  --no-foo     Turn off foo
  --with=WITH  Include optional feature

The name WITH printed with the option --with comes from the destination variable for the option. For cases where the internal variable name is descriptive enough to serve in the documentation, the metavar argument can be used to set a different name.

import optparse

parser = optparse.OptionParser()
parser.add_option('--no-foo', action="store_true", 
                  default=False, 
                  dest="foo",
                  help="Turn off foo",
                  )
parser.add_option('--with', action="store", help="Include optional feature",
                  metavar='feature_NAME')

parser.parse_args()

The value is printed exactly as it is given, without any changes to capitalization or punctuation.

$ python optparse_metavar.py -h

Usage: optparse_metavar.py [options]

Options:
  -h, --help           show this help message and exit
  --no-foo             Turn off foo
  --with=feature_NAME  Include optional feature

Organizing Options

Many applications include sets of related options. For example, rpm includes separate options for each of its operating modes. optparse uses option groups to organize options in the help output. The option values are all still saved in a single Values instance, so the namespace for option names is still flat.

import optparse

parser = optparse.OptionParser()

parser.add_option('-q', action='store_const', const='query', dest='mode',
                  help='Query')
parser.add_option('-i', action='store_const', const='install', dest='mode',
                  help='Install')

query_opts = optparse.OptionGroup(
    parser, 'Query Options',
    'These options control the query mode.',
    )
query_opts.add_option('-l', action='store_const', const='list', dest='query_mode',
                      help='List contents')
query_opts.add_option('-f', action='store_const', const='file', dest='query_mode',
                      help='Show owner of file')
query_opts.add_option('-a', action='store_const', const='all', dest='query_mode',
                      help='Show all packages')
parser.add_option_group(query_opts)

install_opts = optparse.OptionGroup(
    parser, 'Installation Options',
    'These options control installation.',
    )
install_opts.add_option('--hash', action='store_true', default=False,
                        help='Show hash marks as progress indication')
install_opts.add_option('--force', dest='install_force', action='store_true', default=False,
                        help='Install, regardless of depdencies or existing version')
parser.add_option_group(install_opts)

print parser.parse_args()

Each group has its own section title and description, and the options are displayed together.

$ python optparse_groups.py -h

Usage: optparse_groups.py [options]

Options:
  -h, --help  show this help message and exit
  -q          Query
  -i          Install

  Query Options:
    These options control the query mode.

    -l        List contents
    -f        Show owner of file
    -a        Show all packages

  Installation Options:
    These options control installation.

    --hash    Show hash marks as progress indication
    --force   Install, regardless of depdencies or existing version

Application Settings

The automatic help generation facilities support configuration settings to control several aspects of the help output. The program’s usage string, which shows how the positional arguments are expected, can be set when the OptionParser is created.

import optparse

parser = optparse.OptionParser(usage='%prog [options] <arg1> <arg2> [<arg3>...]')
parser.add_option('-a', action="store_true", default=False)
parser.add_option('-b', action="store", dest="b")
parser.add_option('-c', action="store", dest="c", type="int")

parser.parse_args()

The literal value %prog is expanded to the name of the program at runtime, so it can reflect the full path to the script. If the script is run by python, instead of running directly, the script name is used.

$ python optparse_usage.py -h

Usage: optparse_usage.py [options] <arg1> <arg2> [<arg3>...]

Options:
  -h, --help  show this help message and exit
  -a
  -b B
  -c C

The program name can be changed using the prog argument.

import optparse

parser = optparse.OptionParser(usage='%prog [options] <arg1> <arg2> [<arg3>...]',
                               prog='my_program_name',
                               )
parser.add_option('-a', action="store_true", default=False)
parser.add_option('-b', action="store", dest="b")
parser.add_option('-c', action="store", dest="c", type="int")

parser.parse_args()

It is generally a bad idea to hard-code the program name in this way, though, because if the program is renamed the help will not reflect the change.

$ python optparse_prog.py -h

Usage: my_program_name [options] <arg1> <arg2> [<arg3>...]

Options:
  -h, --help  show this help message and exit
  -a
  -b B
  -c C

The application version can be set using the version argument. When a value is provided, optparse automatically adds a --version option to the parser.

import optparse

parser = optparse.OptionParser(usage='%prog [options] <arg1> <arg2> [<arg3>...]',
                               version='1.0',
                               )

parser.parse_args()

When the user runs the program with the --version option, optparse prints the version string and then exits.

$ python optparse_version.py -h

Usage: optparse_version.py [options] <arg1> <arg2> [<arg3>...]

Options:
  --version   show program's version number and exit
  -h, --help  show this help message and exit

$ python optparse_version.py --version

1.0

See also

optparse
Standard library documentation for this module.
getopt
The getopt module, replaced by optparse.
argparse
Newer replacement for optparse.