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
