Optik Reference Guide

Creating the parser

The first step in using Optik is to create an OptionParser instance:

parser = OptionParser(...)

The OptionParser constructor has no required arguments, but a number of optional keyword arguments. You should always pass them as keyword arguments, i.e. do not rely on the order in which the arguments are declared.

usage (default: "%prog [options]")
The usage summary to print when your program is run incorrectly or with a help option. When Optik prints the usage string, it expands %prog to os.path.basename(sys.argv[0]) (or to prog if you passed that keyword argument). To suppress a usage message, pass the special value optik.SUPPRESS_USAGE.
option_list (default: [])
A list of Option objects to populate the parser with. The options in option_list are added after any options in standard_option_list (a class attribute that may be set by OptionParser subclasses), but before any version or help options. Deprecated; use add_option() after creating the parser instead.
option_class (default: optik.option.Option)
Class to use when adding options to the parser in add_option().
version (default: None)
A version string to print when the user supplies a version option. If you supply a true value for version, Optik automatically adds a version option with the single option string "--version". The substring "%prog" is expanded the same as for usage.
conflict_handler (default: "error")
Specifies what to do when options with conflicting option strings are added to the parser; see Conflicts between options.
description (default: None)
A paragraph of text giving a brief overview of your program. Optik reformats this paragraph to fit the current terminal width and prints it when the user requests help (after usage, but before the list of options).
formatter (default: a new IndentedHelpFormatter)
An instance of optik.help.HelpFormatter that will be used for printing help text. Optik provides two concrete classes for this purpose: IndentedHelpFormatter and TitledHelpFormatter.
add_help_option (default: True)
If true, Optik will add a help option (with option strings "-h" and "--help") to the parser.
prog
The string to use when expanding "%prog" in usage and version instead of os.path.basename(sys.argv[0]).

Populating the parser

There are several ways to populate the parser with options. The preferred way is by using OptionParser.add_option(), as shown in the tutorial. add_option() can be called in one of two ways:

The other alternative is to pass a list of pre-constructed Option instances to the OptionParser constructor, as in:

option_list = [
    make_option("-f", "--filename",
                action="store", type="string", dest="filename"),
    make_option("-q", "--quiet",
                action="store_false", dest="verbose"),
    ]
parser = OptionParser(option_list=option_list)

(make_option() is a factory function for creating Option instances; currently it is an alias for the Option constructor. A future version of Optik may split Option into several classes, and make_option() will pick the right class to instantiate. Do not instantiate Option directly.)

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, Optik raises an OptionError exception explaining your mistake.

An options's action determines what Optik does when it encounters this option on the command-line. The standard option actions hard-coded into Optik 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. Optik always creates a special object for this, conventionally called options (it happens to be an instance of optik.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

parser.parse_args()

one of the first things Optik does is create the options object:

options = Values()

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 Optik, on seeing this option, will do the equivalent of

options.filename = "foo"

The type and dest option attributes are almost as important as action, but action is the only one that makes sense for all options.

Standard option actions

The various option actions all have slightly different requirements and effects. Most actions have several relevant option attributes which you may specify to guide Optik's behaviour; a few have required attributes, which you must specify for any option using that action.

Option attributes

The following option attributes may be passed as keyword arguments to parser.add_option(). If you pass an option attribute that is not relevant to a particular option, or fail to pass a required option attribute, Optik raises OptionError.

Standard option types

Optik has six built-in option types: string, int, long, choice, float and complex. If you need to add new option types, see Extending Optik.

Arguments to string options are not checked or converted in any way: the text on the command line is stored in the destination (or passed to the callback) as-is.

Integer arguments (type int or long) are parsed as follows:

  • if the number starts with 0x, it is parsed as a hexadecimal number
  • if the number starts with 0, it is parsed as an octal number
  • if the number starts with 0b, is is parsed as a binary number
  • otherwise, the number is parsed as a decimal number

The conversion is done by calling either int() or long() with the appropriate base (2, 8, 10, or 16). If this fails, so will Optik, although with a more useful error message.

float and complex option arguments are converted directly with float() and complex(), with similar error-handling.

choice options are a subtype of string options. The choices option attribute (a sequence of strings) defines the set of allowed option arguments. optik.option.check_choice() compares user-supplied option arguments against this master list and raises OptionValueError if an invalid string is given.

Parsing arguments

The whole point of creating and populating an OptionParser is to call its parse_args() method:

(options, args) = parser.parse_args(args=None, options=None)

where the input parameters are

args
the list of arguments to process (default: sys.argv[1:])
options
object to store option arguments in (default: a new instance of optik.Values)

and the return values are

options
the same object that was passed in as options, or the new optik.Values instance created by Optik
args
the leftover positional arguments after all options have been processed

The most common usage is to supply neither keyword argument. If you supply options, it will be modified with repeated setattr() calls (roughly one for every option argument stored to an option destination), and finally returned by parse_args().

If parse_args() encounters any errors in the argument list, it calls the OptionParser's error() method with an appropriate end-user error message. This ultimately terminates your process with an exit status of 2 (the traditional UNIX exit status for command-line errors).

Querying and manipulating your option parser

Sometimes, it's useful to poke around your option parser and see what's there. OptionParser provides a couple of methods to help you out:

has_option(opt_str)
Return true if the OptionParser has an option with option string opt_str (e.g., "-q" or "--verbose").
get_option(opt_str)
Returns the Option instance with the option string opt_str, or None if no options have that option string.
remove_option(opt_str)
If the OptionParser has an option corresponding to opt_str, that option is removed. If that option provided any other option strings, all of those option strings become invalid. If opt_str does not occur in any option belonging to this OptionParser, raises ValueError.

Conflicts between options

If you're not careful, it's easy to define options with conflicting option strings:

parser.add_option("-n", "--dry-run", ...)
[...]
parser.add_option("-n", "--noisy", ...)

(This is particularly true if you've defined your own OptionParser subclass with some standard options.)

Every time you add an option, Optik checks for conflicts with existing options. If it finds any, it invokes the current conflict-handling mechanism. You can set the conflict-handling mechanism either in the constructor:

parser = OptionParser(..., conflict_handler=handler)

or with a separate call:

parser.set_conflict_handler(handler)

The available conflict handlers are:

error (default)
assume option conflicts are a programming error and raise OptionConflictError
resolve
resolve option conflicts intelligently (see below)

As an example, let's define an OptionParser that resolves conflicts intelligently and add conflicting options to it:

parser = OptionParser(conflict_handler="resolve")
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")

At this point, Optik detects that a previously-added option is already using the "-n" option string. Since conflict_handler is "resolve", it resolves the situation by removing "-n" from the earlier option's list of option strings. Now "--dry-run" is the only way for the user to activate that option. If the user asks for help, the help message will reflect that:

options:
  --dry-run     do no harm
  [...]
  -n, --noisy   be noisy

It's possible to whittle away the option strings for a previously-added option until there are none left, and the user has no way of invoking that option from the command-line. In that case, Optik removes that option completely, so it doesn't show up in help text or anywhere else. Carrying on with our existing OptionParser:

parser.add_option("--dry-run", ..., help="new dry-run option")

At this point, the original -n/--dry-run option is no longer accessible, so Optik removes it, leaving this help text:

options:
  [...]
  -n, --noisy   be noisy
  --dry-run     new dry-run option

Cleanup

OptionParser instances have several cyclic references. This should not be a problem for Python's garbage collector, but you may wish to break the cyclic references explicitly by calling destroy() on your OptionParser once you are done with it. This is particularly useful in long-running applications where large object graphs are reachable from your OptionParser.

Other methods

OptionParser supports several other public methods: