14.3.3.3 Defining options
Each Option instance represents a set of synonymous command-line option
strings, e.g. -f and --file. You can
specify any number of short or long option strings, but you must specify
at least one overall option string.
The canonical way to create an Option instance is with the
add_option() method of OptionParser:
parser.add_option(opt_str[, ...], attr=value, ...)
To define an option with only a short option string:
parser.add_option("-f", attr=value, ...)
And to define an option with only a long option string:
parser.add_option("--foo", attr=value, ...)
The keyword arguments define attributes of the new Option object. The
most important option attribute is action, and it largely determines
which other attributes are relevant or required. If you pass irrelevant
option attributes, or fail to pass required ones, optparse raises an
OptionError exception explaining your mistake.
An options's action determines what optparse does when it encounters this
option on the command-line. The standard option actions hard-coded into
optparse are:
store
- store this option's argument (default)
store_const
- store a constant value
store_true
- store a true value
store_false
- store a false value
append
- append this option's argument to a list
append_const
- append a constant value to a list
count
- increment a counter by one
callback
- call a specified function
- help
- print a usage message including all options and the
documentation for them
(If you don't supply an action, the default is store . For this
action, you may also supply type and dest option attributes; see
below.)
As you can see, most actions involve storing or updating a value
somewhere. optparse always creates a special object for this,
conventionally called options (it happens to be an instance of
optparse.Values ). Option arguments (and various other values) are
stored as attributes of this object, according to the dest
(destination) option attribute.
For example, when you call
one of the first things optparse does is create the options object:
If one of the options in this parser is defined with
parser.add_option("-f", "--file", action="store", type="string", dest="filename")
and the command-line being parsed includes any of the following:
-ffoo
-f foo
--file=foo
--file foo
then optparse, on seeing this option, will do the equivalent of
The type and dest option attributes are almost as important as
action, but action is the only one that makes sense for all
options.
Release 2.5.2, documentation updated on 21st February, 2008.
See About this document... for information on suggesting changes.
|