Doc/lib/liboptparse.tex

\section{\module{optparse} ---
        Powerful parser for command line options.}

\declaremodule{standard}{optparse}
\moduleauthor{Greg Ward}{gward@python.net}
\sectionauthor{Johannes Gijsbers}{jlgijsbers@users.sf.net}
\sectionauthor{Greg Ward}{gward@python.net}

\modulesynopsis{Powerful, flexible, extensible, easy-to-use command-line
                parsing library.}

\versionadded{2.3}

The \module{optparse} module is a powerful, flexible, extensible,
easy-to-use command-line parsing library for Python.  Using
\module{optparse}, you can add intelligent, sophisticated handling of
command-line options to your scripts with very little overhead.

Here's an example of using \module{optparse} to add some command-line
options to a simple script:

\begin{verbatim}
from optparse import OptionParser

parser = OptionParser()
parser.add_option("-f", "--file", dest="filename",
                  help="write report to FILE", metavar="FILE")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose", default=1,
                  help="don't print status messages to stdout")

(options, args) = parser.parse_args()
\end{verbatim}

With these few lines of code, users of your script can now do the
"usual thing" on the command-line:

\begin{verbatim}
$ <yourscript> -f outfile --quiet
$ <yourscript> -qfoutfile
$ <yourscript> --file=outfile -q
$ <yourscript> --quiet --file outfile
\end{verbatim}

(All of these result in \code{options.filename == "outfile"} and
\code{options.verbose == 0} ...just as you might expect.)

Even niftier, users can run one of
\begin{verbatim}
$ <yourscript> -h
$ <yourscript> --help
\end{verbatim}
and \module{optparse} will print out a brief summary of your script's
options:

\begin{verbatim}
usage: <yourscript> [options]

options:
  -h, --help           show this help message and exit
  -fFILE, --file=FILE  write report to FILE
  -q, --quiet          don't print status messages to stdout
\end{verbatim}

That's just a taste of the flexibility \module{optparse} gives you in
parsing your command-line.

\subsection{The Tao of Option Parsing\label{optparse-tao}}

\module{optparse} is an implementation of what I have always
considered the most obvious, straightforward, and user-friendly way to
design a user interface for command-line programs.  In short, I have
fairly firm ideas of the Right Way (and the many Wrong Ways) to do
argument parsing, and \module{optparse} reflects many of those ideas.
This section is meant to explain this philosophy, which in turn is
heavily influenced by the \UNIX{} and GNU toolkits.

\subsubsection{Terminology\label{optparse-terminology}}

First, we need to establish some terminology.

\begin{definitions}
\term{argument}
a chunk of text that a user enters on the command-line, and that the
shell passes to \cfunction{execl()} or \cfunction{execv()}.  In
Python, arguments are elements of
\var{sys.argv[1:]}. (\var{sys.argv[0]} is the name of the program
being executed; in the context of parsing arguments, it's not very
important.)  \UNIX{} shells also use the term ``word''.

It's occasionally desirable to substitute an argument list other
than \var{sys.argv[1:]}, so you should read ``argument'' as ``an element of
\var{sys.argv[1:]}, or of some other list provided as a substitute for
\var{sys.argv[1:]}''.

\term{option}
  an argument used to supply extra information to guide or customize
  the execution of a program.  There are many different syntaxes for
  options; the traditional \UNIX{} syntax is \programopt{-} followed by a
  single letter, e.g. \programopt{-x} or \programopt{-F}.  Also,
  traditional \UNIX{} syntax allows multiple options to be merged into a
  single argument, e.g.  \programopt{-x -F} is equivalent to
  \programopt{-xF}.  The GNU project introduced \longprogramopt{}
  followed by a series of hyphen-separated words,
  e.g. \longprogramopt{file} or \longprogramopt{dry-run}.  These are
  the only two option syntaxes provided by \module{optparse}.

  Some other option syntaxes that the world has seen include:

\begin{itemize}
\item a hyphen followed by a few letters, e.g. \programopt{-pf} (this is
      \emph{not} the same as multiple options merged into a single
      argument.)
\item a hyphen followed by a whole word, e.g. \programopt{-file} (this is
      technically equivalent to the previous syntax, but they aren't
      usually seen in the same program.)
\item a plus sign followed by a single letter, or a few letters,
      or a word, e.g. \programopt{+f}, \programopt{+rgb}.
\item a slash followed by a letter, or a few letters, or a word, e.g.
      \programopt{/f}, \programopt{/file}.
\end{itemize}

These option syntaxes are not supported by \module{optparse}, and they
never will be.  (If you really want to use one of those option
syntaxes, you'll have to subclass OptionParser and override all the
difficult bits.  But please don't!  \module{optparse} does things the
traditional \UNIX/GNU way deliberately; the first three are
non-standard anywhere, and the last one makes sense only if you're
exclusively targeting MS-DOS/Windows and/or VMS.)

\term{option argument}
an argument that follows an option, is closely associated with that
option, and is consumed from the argument list when the option is.
Often, option arguments may also be included in the same argument as
the option, e.g. :

\begin{verbatim}
    ["-f", "foo"]
\end{verbatim}

may be equivalent to:

\begin{verbatim}
    ["-ffoo"]
\end{verbatim}

(\module{optparse} supports this syntax.)

Some options never take an argument.  Some options always take an
argument.  Lots of people want an ``optional option arguments'' feature,
meaning that some options will take an argument if they see it, and
won't if they don't.  This is somewhat controversial, because it makes
parsing ambiguous: if \programopt{-a} takes an optional argument and
\programopt{-b} is another option entirely, how do we interpret
\programopt{-ab}?  \module{optparse} does not currently support this.

\term{positional argument}
something leftover in the argument list after options have been
parsed, ie. after options and their arguments have been parsed and
removed from the argument list.

\term{required option}
an option that must be supplied on the command-line; the phrase
``required option'' is an oxymoron and is usually considered poor UI
design.  \module{optparse} doesn't prevent you from implementing
required options, but doesn't give you much help with it either.  See
``Extending Examples'' (section~\ref{optparse-extending-examples}) for
two ways to implement required options with \module{optparse}.

\end{definitions}

For example, consider this hypothetical command-line:

\begin{verbatim}
  prog -v --report /tmp/report.txt foo bar
\end{verbatim}

\programopt{-v} and \longprogramopt{report} are both options.  Assuming
the \longprogramopt{report} option takes one argument,
``/tmp/report.txt'' is an option argument.  ``foo'' and ``bar'' are
positional arguments.

\subsubsection{What are options for?\label{optparse-options}}

Options are used to provide extra information to tune or customize the
execution of a program.  In case it wasn't clear, options are usually
\emph{optional}.  A program should be able to run just fine with no
options whatsoever.  (Pick a random program from the \UNIX{} or GNU
toolsets.  Can it run without any options at all and still make sense?
The only exceptions I can think of are \program{find}, \program{tar},
and \program{dd} --- all of which are mutant oddballs that have been
rightly criticized for their non-standard syntax and confusing
interfaces.)

Lots of people want their programs to have ``required options''.
Think about it.  If it's required, then it's \emph{not optional}!  If
there is a piece of information that your program absolutely requires
in order to run successfully, that's what positional arguments are
for.  (However, if you insist on adding ``required options'' to your
programs, look in ``Extending Examples''
(section~\ref{optparse-extending-examples}) for two ways of
implementing them with \module{optparse}.)

Consider the humble \program{cp} utility, for copying files.  It
doesn't make much sense to try to copy files without supplying a
destination and at least one source.  Hence, \program{cp} fails if you
run it with no arguments.  However, it has a flexible, useful syntax
that does not rely on options at all:

\begin{verbatim}
$ cp SOURCE DEST
$ cp SOURCE ... DEST-DIR
\end{verbatim}

You can get pretty far with just that.  Most \program{cp}
implementations provide a bunch of options to tweak exactly how the
files are copied: you can preserve mode and modification time, avoid
following symlinks, ask before clobbering existing files, etc.  But
none of this distracts from the core mission of \program{cp}, which is
to copy one file to another, or N files to another directory.

\subsubsection{What are positional arguments for? \label{optparse-positional-arguments}}

In case it wasn't clear from the above example: positional arguments
are for those pieces of information that your program absolutely,
positively requires to run.

A good user interface should have as few absolute requirements as
possible.  If your program requires 17 distinct pieces of information in
order to run successfully, it doesn't much matter \emph{how} you get that
information from the user --- most people will give up and walk away
before they successfully run the program.  This applies whether the user
interface is a command-line, a configuration file, a GUI, or whatever:
if you make that many demands on your users, most of them will just give
up.

In short, try to minimize the amount of information that users are
absolutely required to supply --- use sensible defaults whenever
possible.  Of course, you also want to make your programs reasonably
flexible.  That's what options are for.  Again, it doesn't matter if
they are entries in a config file, checkboxes in the ``Preferences''
dialog of a GUI, or command-line options --- the more options you
implement, the more flexible your program is, and the more complicated
its implementation becomes.  It's quite easy to overwhelm users (and
yourself!) with too much flexibility, so be careful there.

\subsection{Basic Usage\label{optparse-basic-usage}}

While \module{optparse} is quite flexible and powerful, you don't have
to jump through hoops or read reams of documentation to get it working
in basic cases.  This document aims to demonstrate some simple usage
patterns that will get you started using \module{optparse} in your
scripts.

To parse a command line with \module{optparse}, you must create an
\class{OptionParser} instance and populate it.  Obviously, you'll have
to import the \class{OptionParser} classes in any script that uses
\module{optparse}:

\begin{verbatim}
from optparse import OptionParser
\end{verbatim}

Early on in the main program, create a parser:

\begin{verbatim}
parser = OptionParser()
\end{verbatim}

Then you can start populating the parser with options.  Each option is
really a set of synonymous option strings; most commonly, you'll have
one short option string and one long option string ---
e.g. \programopt{-f} and \longprogramopt{file}:

\begin{verbatim}
parser.add_option("-f", "--file", ...)
\end{verbatim}

The interesting stuff, of course, is what comes after the option
strings.  In this document, we'll only cover four of the things you
can put there: \var{action}, \var{type}, \var{dest} (destination), and
\var{help}.

\subsubsection{The "store" action\label{optparse-store-action}}

The action tells \module{optparse} what to do when it sees one of the
option strings for this option on the command-line.  For example, the
action \var{store} means: take the next argument (or the remainder of
the current argument), ensure that it is of the correct type, and
store it to your chosen destination.

For example, let's fill in the "..." of that last option:

\begin{verbatim}
parser.add_option("-f", "--file",
                  action="store", type="string", dest="filename")
\end{verbatim}

Now let's make up a fake command-line and ask \module{optparse} to
parse it:

\begin{verbatim}
args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)
\end{verbatim}

(Note that if you don't pass an argument list to
\function{parse_args()}, it automatically uses \var{sys.argv[1:]}.)

When \module{optparse} sees the \programopt{-f}, it sucks in the next
argument --- ``foo.txt'' --- and stores it in the \var{filename}
attribute of a special object.  That object is the first return value
from \function{parse_args()}, so:

\begin{verbatim}
print options.filename
\end{verbatim}

will print ``foo.txt''.

Other option types supported by \module{optparse} are ``int'' and
``float''.  Here's an option that expects an integer argument:

\begin{verbatim}
parser.add_option("-n", type="int", dest="num")
\end{verbatim}

Note that I didn't supply a long option, which is perfectly acceptable.
I also didn't specify the action --- it defaults to ``store''.
  
Let's parse another fake command-line.  This time, we'll jam the
option argument right up against the option --- \programopt{-n42} (one
argument) is equivalent to \programopt{-n 42} (two arguments). :

\begin{verbatim}
(options, args) = parser.parse_args(["-n42"])
print options.num
\end{verbatim}

will print ``42''.

Trying out the ``float'' type is left as an exercise for the reader.

If you don't specify a type, \module{optparse} assumes ``string''.
Combined with the fact that the default action is ``store'', that
means our first example can be a lot shorter:

\begin{verbatim}
parser.add_option("-f", "--file", dest="filename")
\end{verbatim}

If you don't supply a destination, \module{optparse} figures out a
sensible default from the option strings: if the first long option
string is \longprogramopt{foo-bar}, then the default destination is
\var{foo_bar}.  If there are no long option strings,
\module{optparse} looks at the first short option: the default
destination for \programopt{-f} is \var{f}.

Adding types is fairly easy; please refer to
section~\ref{optparse-adding-types}, ``Adding new types.''

\subsubsection{Other "store_*" actions\label{optparse-other-store-actions}}

Flag options --- set a variable to true or false when a particular
option is seen --- are quite common.  \module{optparse} supports them
with two separate actions, ``store_true'' and ``store_false''.  For
example, you might have a \var{verbose} flag that is turned on with
\programopt{-v} and off with \programopt{-q}:

\begin{verbatim}
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")
\end{verbatim}

Here we have two different options with the same destination, which is
perfectly OK.  (It just means you have to be a bit careful when setting
default values --- see below.)

When \module{optparse} sees \programopt{-v} on the command line, it
sets the \var{verbose} attribute of the special {option values}
object to 1; when it sees \programopt{-q}, it sets \var{verbose} to
0.

\subsubsection{Setting default values\label{optparse-setting-default-values}}

All of the above examples involve setting some variable (the
``destination'') when certain command-line options are seen.  What
happens if those options are never seen?  Since we didn't supply any
defaults, they are all set to None.  Sometimes, this is just fine
(which is why it's the default), but sometimes, you want more control.
To address that need, \module{optparse} lets you supply a default
value for each destination, which is assigned before the command-line
is parsed.

First, consider the verbose/quiet example.  If we want
\module{optparse} to set \var{verbose} to 1 unless \programopt{-q} is
seen, then we can do this:

\begin{verbatim}
parser.add_option("-v", action="store_true", dest="verbose", default=1)
parser.add_option("-q", action="store_false", dest="verbose")
\end{verbatim}

Oddly enough, this is exactly equivalent:

\begin{verbatim}
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=1)
\end{verbatim}

Those are equivalent because you're supplying a default value for the
option's \emph{destination}, and these two options happen to have the same
destination (the \var{verbose} variable).

Consider this:

\begin{verbatim}
parser.add_option("-v", action="store_true", dest="verbose", default=0)
parser.add_option("-q", action="store_false", dest="verbose", default=1)
\end{verbatim}

Again, the default value for \var{verbose} will be 1: the last
default value supplied for any particular destination attribute is the
one that counts.

\subsubsection{Generating help\label{optparse-generating-help}}

The last feature that you will use in every script is
\module{optparse}'s ability to generate help messages.  All you have
to do is supply a \var{help} value when you add an option.  Let's
create a new parser and populate it with user-friendly (documented)
options:

\begin{verbatim}
usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
                  action="store_true", dest="verbose", default=1,
                  help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose", 
                  help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--file", dest="filename",
                  metavar="FILE", help="write output to FILE"),
parser.add_option("-m", "--mode",
                  default="intermediate",
                  help="interaction mode: one of 'novice', "
                       "'intermediate' [default], 'expert'")
\end{verbatim}

If \module{optparse} encounters either \programopt{-h} or
\longprogramopt{help} on the command-line, or if you just call
\method{parser.print_help()}, it prints the following to stdout:

\begin{verbatim}
usage: <yourscript> [options] arg1 arg2

options:
  -h, --help           show this help message and exit
  -v, --verbose        make lots of noise [default]
  -q, --quiet          be vewwy quiet (I'm hunting wabbits)
  -fFILE, --file=FILE  write output to FILE
  -mMODE, --mode=MODE  interaction mode: one of 'novice', 'intermediate'
                       [default], 'expert'
\end{verbatim}

There's a lot going on here to help \module{optparse} generate the
best possible help message:

\begin{itemize}
\item the script defines its own usage message:

\begin{verbatim}
usage = "usage: %prog [options] arg1 arg2"
\end{verbatim}

\module{optparse} expands "\%prog" in the usage string to the name of the
current script, ie. \code{os.path.basename(sys.argv[0])}.  The
expanded string is then printed before the detailed option help.

If you don't supply a usage string, \module{optparse} uses a bland but
sensible default: ``usage: \%prog [options]'', which is fine if your
script doesn't take any positional arguments.

\item every option defines a help string, and doesn't worry about 
line-wrapping --- \module{optparse} takes care of wrapping lines and 
making the help output look good.

\item options that take a value indicate this fact in their
automatically-generated help message, e.g. for the ``mode'' option:

\begin{verbatim}
-mMODE, --mode=MODE
\end{verbatim}

Here, ``MODE'' is called the meta-variable: it stands for the argument
that the user is expected to supply to
\programopt{-m}/\longprogramopt{mode}.  By default, \module{optparse}
converts the destination variable name to uppercase and uses that for
the meta-variable.  Sometimes, that's not what you want --- for
example, the \var{filename} option explicitly sets
\code{metavar="FILE"}, resulting in this automatically-generated
option description:

\begin{verbatim}
-fFILE, --file=FILE
\end{verbatim}

This is important for more than just saving space, though: the
manually written help text uses the meta-variable ``FILE'', to clue
the user in that there's a connection between the formal syntax
``-fFILE'' and the informal semantic description ``write output to
FILE''.  This is a simple but effective way to make your help text a
lot clearer and more useful for end users.
\end{itemize}

When dealing with many options, it is convenient to group these
options for better help output.  An \class{OptionParser} can contain
several option groups, each of which can contain several options.

Continuing with the parser defined above, adding an
\class{OptionGroup} to a parser is easy:

\begin{verbatim}
group = OptionGroup(parser, "Dangerous Options",
                    "Caution: use these options at your own risk."
                    "  It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)
\end{verbatim}

This would result in the following help output:

\begin{verbatim}
usage:  [options] arg1 arg2

options:
  -h, --help           show this help message and exit
  -v, --verbose        make lots of noise [default]
  -q, --quiet          be vewwy quiet (I'm hunting wabbits)
  -fFILE, --file=FILE  write output to FILE
  -mMODE, --mode=MODE  interaction mode: one of 'novice', 'intermediate'
                       [default], 'expert'

  Dangerous Options:
    Caution: use of these options is at your own risk.  It is believed that
    some of them bite.
    -g                 Group option.
\end{verbatim}


\subsubsection{Print a version number\label{optparse-print-version}}

Similar to the brief usage string, \module{optparse} can also print a
version string for your program.  You have to supply the string, as
the \var{version} argument to \class{OptionParser}:

\begin{verbatim}
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
\end{verbatim}

Note that ``\%prog'' is expanded just like it is in \var{usage}.  Apart from
that, \var{version} can contain anything you like.  When you supply it,
\module{optparse} automatically adds a \longprogramopt{version} option to your
parser. If it encounters this option on the command line, it expands
your \var{version} string (by replacing ``\%prog''), prints it to
stdout, and exits.

For example, if your script is called /usr/bin/foo, a user might do:

\begin{verbatim}
$ /usr/bin/foo --version
foo 1.0
$
\end{verbatim}

\subsubsection{Error-handling\label{optparse-error-handling}}

The one thing you need to know for basic usage is how
\module{optparse} behaves when it encounters an error on the
command-line --- e.g. \programopt{-n4x} where \programopt{-n} is an
integer-valued option.  \module{optparse} prints your usage message to
stderr, followed by a useful and human-readable error message.  Then
it terminates (calls \function{sys.exit()}) with a non-zero exit
status.

If you don't like this, subclass \class{OptionParser} and override the
\method{error()} method.  See section~\ref{optparse-extending},
``Extending \module{optparse}.''

\subsubsection{Putting it all together\label{optparse-basic-summary}}

Here's what my \module{optparse}-based scripts usually look like:

\begin{verbatim}
from optparse import OptionParser

...

def main ():
    usage = "usage: %prog [options] arg"
    parser = OptionParser(usage)
    parser.add_option("-f", "--file", type="string", dest="filename",
                      help="read data from FILENAME")
    parser.add_option("-v", "--verbose",
                      action="store_true", dest="verbose")
    parser.add_option("-q", "--quiet",
                      action="store_false", dest="verbose")
    # more options ...

    (options, args) = parser.parse_args()
    if len(args) != 1:
        parser.error("incorrect number of arguments")

    if options.verbose:
        print "reading %s..." % options.filename

    # go to work ...

if __name__ == "__main__":
    main()
\end{verbatim}

\subsection{Advanced Usage\label{optparse-advanced-usage}}

This is reference documentation.  If you haven't read the basic
documentation in section~\ref{optparse-basic-usage}, do so now.

\subsubsection{Creating and populating the
               parser\label{optparse-creating-the-parser}}

There are several ways to populate the parser with options.  One way
is to pass a list of \class{Options} to the \class{OptionParser}
constructor:

\begin{verbatim}
parser = OptionParser(option_list=[
    make_option("-f", "--filename",
                action="store", type="string", dest="filename"),
    make_option("-q", "--quiet",
                action="store_false", dest="verbose")])
\end{verbatim}

(\function{make_option()} is an alias for
the \class{Option} class, ie. this just calls the \class{Option}
constructor.  A future version of \module{optparse} will probably
split \class{Option} into several classes, and
\function{make_option()} will become a factory function that picks the
right class to instantiate.)

For long option lists, it's often more convenient/readable to create the
list separately:

\begin{verbatim}
option_list = [make_option("-f", "--filename",
                           action="store", type="string", dest="filename"),
               # 17 other options ...
               make_option("-q", "--quiet",
                           action="store_false", dest="verbose")]
parser = OptionParser(option_list=option_list)
\end{verbatim}

Or, you can use the \method{add_option()} method of
\class{OptionParser} to add options one-at-a-time:

\begin{verbatim}
parser = OptionParser()
parser.add_option("-f", "--filename",
                  action="store", type="string", dest="filename")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose")
\end{verbatim}

This method makes it easier to track down exceptions raised by the
\class{Option} constructor, which are common because of the complicated
interdependencies among the various keyword arguments --- if you get it
wrong, \module{optparse} raises \exception{OptionError}.

\method{add_option()} can be called in one of two ways:

\begin{itemize}
\item pass it an \class{Option} instance  (as returned by \function{make_option()})
\item pass it any combination of positional and keyword arguments that
are acceptable to \function{make_option()} (ie., to the \class{Option}
constructor), and it will create the \class{Option} instance for you
(shown above).
\end{itemize}

\subsubsection{Defining options\label{optparse-defining-options}}

Each \class{Option} instance represents a set of synonymous
command-line options, ie. options that have the same meaning and
effect, but different spellings.  You can specify any number of short
or long option strings, but you must specify at least one option
string.

To define an option with only a short option string:

\begin{verbatim}
make_option("-f", ...)
\end{verbatim}

And to define an option with only a long option string:

\begin{verbatim}
make_option("--foo", ...)
\end{verbatim}

The ``...'' represents a set of keyword arguments that define
attributes of the \class{Option} object.  Just which keyword args you
must supply for a given \class{Option} is fairly complicated (see the
various \method{_check_*()} methods in the \class{Option} class if you
don't believe me), but you always have to supply \emph{some}.  If you
get it wrong, \module{optparse} raises an \exception{OptionError}
exception explaining your mistake.

The most important attribute of an option is its action, ie. what to do
when we encounter this option on the command-line.  The possible actions
are:

\begin{definitions}
\term{store} [default]
store this option's argument.
\term{store_const}
store a constant value.
\term{store_true}
store a true value.
\term{store_false}
store a false value.
\term{append}
append this option's argument to a list.
\term{count}
increment a counter by one.
\term{callback}
call a specified function.
\term{help}
print a usage message including all options and the documentation for
them.
\end{definitions}

(If you don't supply an action, the default is ``store''.  For this
action, you may also supply \var{type} and \var{dest} keywords; see
below.)

As you can see, most actions involve storing or updating a value
somewhere. \module{optparse} always creates a particular object (an
instance of the \class{Values} class) specifically for this
purpose. Option arguments (and various other values) are stored as
attributes of this object, according to the \var{dest} (destination)
argument to \function{make_option()}/\method{add_option()}.

For example, when you call:

\begin{verbatim}
parser.parse_args()
\end{verbatim}

one of the first things \module{optparse} does is create a
\var{values} object:

\begin{verbatim}
values = Values()
\end{verbatim}

If one of the options in this parser is defined with:

\begin{verbatim}
make_option("-f", "--file", action="store", type="string", dest="filename")
\end{verbatim}

and the command-line being parsed includes any of the following:

\begin{verbatim}
-ffoo
-f foo
--file=foo
--file foo
\end{verbatim}

then \module{optparse}, on seeing the \programopt{-f} or
\longprogramopt{file} option, will do the equivalent of this:

\begin{verbatim}
  values.filename = "foo"
\end{verbatim}

Clearly, the \var{type} and \var{dest} arguments are (usually) almost
as important as \var{action}.  \var{action} is the only attribute that
is meaningful for \emph{all} options, though, so it is the most
important.

\subsubsection{Option actions\label{optparse-option-actions}}

The various option actions all have slightly different requirements
and effects.  Except for the ``help'' action, you must supply at least
one other keyword argument when creating the \class{Option}; the exact
requirements for each action are listed here.

\begin{definitions}
\term{store} [relevant: \var{type}, \var{dest}, \var{nargs}, \var{choices}]

The option must be followed by an argument, which is converted to a
value according to \var{type} and stored in \var{dest}.  If
\var{nargs} > 1, multiple arguments will be consumed from the command
line; all will be converted according to \var{type} and stored to
\var{dest} as a tuple.  See section~\ref{optparse-option-types},
``Option types'' below.

If \var{choices} is supplied (a list or tuple of strings), the type
defaults to ``choice''.

If \var{type} is not supplied, it defaults to ``string''.

If \var{dest} is not supplied, \module{optparse} derives a
destination from the first long option strings (e.g.,
\longprogramopt{foo-bar} becomes \var{foo_bar}).  If there are no long
option strings, \module{optparse} derives a destination from the first
short option string (e.g., \programopt{-f} becomes \var{f}).

Example:

\begin{verbatim}
make_option("-f")
make_option("-p", type="float", nargs=3, dest="point")
\end{verbatim}

Given the following command line:

\begin{verbatim}
-f foo.txt -p 1 -3.5 4 -fbar.txt
\end{verbatim}

\module{optparse} will set:

\begin{verbatim}
values.f = "bar.txt"
values.point = (1.0, -3.5, 4.0)
\end{verbatim}

(Actually, \member{values.f} will be set twice, but only the second
time is visible in the end.)

\term{store_const} [required: \var{const}, \var{dest}]

The \var{const} value supplied to the \class{Option} constructor is
stored in \var{dest}.

Example:

\begin{verbatim}
make_option("-q", "--quiet",
       action="store_const", const=0, dest="verbose"),
make_option("-v", "--verbose",
       action="store_const", const=1, dest="verbose"),
make_option(None, "--noisy",
       action="store_const", const=2, dest="verbose"),
\end{verbatim}

If \longprogramopt{noisy} is seen, \module{optparse} will set:

\begin{verbatim}
values.verbose = 2
\end{verbatim}

\term{store_true} [required: \var{dest}]

A special case of ``store_const'' that stores a true value
(specifically, the integer 1) to \var{dest}.

\term{store_false} [required: \var{dest}]

Like ``store_true'', but stores a false value (the integer 0).

Example:

\begin{verbatim}
make_option(None, "--clobber", action="store_true", dest="clobber")
make_option(None, "--no-clobber", action="store_false", dest="clobber")
\end{verbatim}

\term{append} [relevant: \var{type}, \var{dest}, \var{nargs}, \var{choices}]

The option must be followed by an argument, which is appended to the
list in \var{dest}. If no default value for \var{dest} is supplied
(ie. the default is None), an empty list is automatically created when
\module{optparse} first encounters this option on the command-line.
If \samp{nargs > 1}, multiple arguments are consumed, and a tuple of
length \var{nargs} is appended to \var{dest}.

The defaults for \var{type} and \var{dest} are the same as for the
``store'' action.

Example:

\begin{verbatim}
make_option("-t", "--tracks", action="append", type="int")
\end{verbatim}

If \programopt{-t3} is seen on the command-line, \module{optparse} does the equivalent of:

\begin{verbatim}
values.tracks = []
values.tracks.append(int("3"))
\end{verbatim}

If, a little later on, \longprogramopt{tracks=4} is seen, it does:

\begin{verbatim}
values.tracks.append(int("4"))
\end{verbatim}

See ``Error handling'' (section~\ref{optparse-error-handling}) for
information on how \module{optparse} deals with something like
\longprogramopt{tracks=x}.

\term{count} [required: \var{dest}]

Increment the integer stored at \var{dest}. \var{dest} is set to zero
before being incremented the first time (unless you supply a default
value).

Example:

\begin{verbatim}
make_option("-v", action="count", dest="verbosity")
\end{verbatim}

The first time \programopt{-v} is seen on the command line,
\module{optparse} does the equivalent of:

\begin{verbatim}
values.verbosity = 0
values.verbosity += 1
\end{verbatim}

Every subsequent occurrence of \programopt{-v} results in:

\begin{verbatim}
values.verbosity += 1
\end{verbatim}

\term{callback} [required: \var{'callback'};
      relevant: \var{type}, \var{nargs}, \var{callback_args},
      \var{callback_kwargs}]

Call the function specified by \var{callback}.  The signature of
this function should be:

\begin{verbatim}
func(option : Option,
     opt : string,
     value : any,
     parser : OptionParser,
     *args, **kwargs)
\end{verbatim}

Callback options are covered in detail in
section~\ref{optparse-callback-options} ``Callback Options.''

\term{help} [required: none]

Prints a complete help message for all the options in the current
option parser.  The help message is constructed from the \var{usage}
string passed to \class{OptionParser}'s constructor and the \var{help}
string passed to every option.

If no \var{help} string is supplied for an option, it will still be
listed in the help message.  To omit an option entirely, use the
special value \constant{optparse.SUPPRESS_HELP}.

Example:

\begin{verbatim}
from optparse import Option, OptionParser, SUPPRESS_HELP

usage = "usage: %prog [options]"
parser = OptionParser(usage, option_list=[
  make_option("-h", "--help", action="help"),
  make_option("-v", action="store_true", dest="verbose",
              help="Be moderately verbose")
  make_option("--file", dest="filename",
              help="Input file to read data from"),
  make_option("--secret", help=SUPPRESS_HELP)
\end{verbatim}

If \module{optparse} sees either \programopt{-h} or
\longprogramopt{help} on the command line, it will print something
like the following help message to stdout:

\begin{verbatim}
usage: <yourscript> [options]

options:
  -h, --help        Show this help message and exit
  -v                Be moderately verbose
  --file=FILENAME   Input file to read data from
\end{verbatim}

After printing the help message, \module{optparse} terminates your process
with \code{sys.exit(0)}.

\term{version} [required: none]

Prints the version number supplied to the \class{OptionParser} to
stdout and exits.  The version number is actually formatted and
printed by the \method{print_version()} method of
\class{OptionParser}.  Generally only relevant if the \var{version}
argument is supplied to the \class{OptionParser} constructor.
\end{definitions}

\subsubsection{Option types\label{optparse-option-types}}

\module{optparse} supports six option types out of the box: \dfn{string},
\dfn{int}, \dfn{long}, \dfn{choice}, \dfn{float} and \dfn{complex}.
(Of these, string, int, float, and choice are the most commonly used
-- long and complex are there mainly for completeness.)  It's easy to
add new option types by subclassing the \class{Option} class; see
section~\ref{optparse-extending}, ``Extending \module{optparse}.''

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 are passed to \function{int()} to convert them to
Python integers.  If \function{int()} fails, so will
\module{optparse}, although with a more useful error message.
Internally, \module{optparse} raises \exception{OptionValueError} in
\function{optparse.check_builtin()}; at a higher level (in
\class{OptionParser}) this is caught and \module{optparse} terminates
your program with a useful error message.

Likewise, float arguments are passed to \function{float()} for
conversion, long arguments to \function{long()}, and complex arguments
to \function{complex()}.  Apart from that, they are handled
identically to integer arguments.

Choice options are a subtype of string options. A master list or
tuple of choices (strings) must be passed to the option constructor
(\function{make_option()} or \method{OptionParser.add_option()}) as
the ``choices'' keyword argument. Choice option arguments are
compared against this master list in
\function{optparse.check_choice()}, and \exception{OptionValueError}
is raised if an unknown string is given.

\subsubsection{Querying and manipulating your option parser\label{optparse-querying-and-manipulating}}

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

\begin{methoddesc}{has_option}{opt_str}
    Given an option string such as \programopt{-q} or
    \longprogramopt{verbose}, returns true if the \class{OptionParser}
    has an option with that option string.
\end{methoddesc}

\begin{methoddesc}{get_option}{opt_str}
    Returns the \class{Option} instance that implements the option
    string you supplied, or None if no options implement it.
\end{methoddesc}

\begin{methoddesc}{remove_option}{opt_str}
    If the \class{OptionParser} has an option corresponding to
    \var{opt_str}, that option is removed.  If that option provided
    any other option strings, all of those option strings become
    invalid.

    If \var{opt_str} does not occur in any option belonging to this
    \class{OptionParser}, raises \exception{ValueError}.
\end{methoddesc}

\subsubsection{Conflicts between options\label{optparse-conflicts}}

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

\begin{verbatim}
parser.add_option("-n", "--dry-run", ...)
...
parser.add_option("-n", "--noisy", ...)
\end{verbatim} 

(This is even easier to do if you've defined your own
\class{OptionParser} subclass with some standard options.)

On the assumption that this is usually a mistake, \module{optparse}
raises an exception (\exception{OptionConflictError}) by default when
this happens.  Since this is an easily-fixed programming error, you
shouldn't try to catch this exception --- fix your mistake and get on
with life.

Sometimes, you want newer options to deliberately replace the option
strings used by older options.  You can achieve this by calling:

\begin{verbatim}
parser.set_conflict_handler("resolve")
\end{verbatim}

which instructs \module{optparse} to resolve option conflicts
intelligently.

Here's how it works: every time you add an option, \module{optparse}
checks for conflicts with previously-added options.  If it finds any,
it invokes the conflict-handling mechanism you specify either to the
\class{OptionParser} constructor:

\begin{verbatim}
parser = OptionParser(..., conflict_handler="resolve")
\end{verbatim}

or via the \method{set_conflict_handler()} method.

The default conflict-handling mechanism is ``error''.  The only other
one is ``ignore'', which restores the (arguably broken) behaviour of
\module{optparse} 1.1 and earlier.

Here's an example: first, define an \class{OptionParser} set to
resolve conflicts intelligently:

\begin{verbatim}
parser = OptionParser(conflict_handler="resolve")
\end{verbatim}

Now add all of our options:

\begin{verbatim}
parser.add_option("-n", "--dry-run", ..., help="original dry-run option")
...
parser.add_option("-n", "--noisy", ..., help="be noisy")
\end{verbatim} 

At this point, \module{optparse} detects that a previously-added option is already
using the \programopt{-n} option string.  Since \code{conflict_handler
== "resolve"}, it resolves the situation by removing \programopt{-n}
from the earlier option's list of option strings.  Now,
\longprogramopt{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, e.g.:

\begin{verbatim}
options:
  --dry-run     original dry-run option
  ...
  -n, --noisy   be noisy
\end{verbatim}

Note that 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,
\module{optparse} removes that option completely, so it doesn't show
up in help text or anywhere else.  E.g. if we carry on with our
existing \class{OptionParser}:

\begin{verbatim}
parser.add_option("--dry-run", ..., help="new dry-run option")
\end{verbatim}

At this point, the first \programopt{-n}/\longprogramopt{dry-run}
option is no longer accessible, so \module{optparse} removes it.  If
the user asks for help, they'll get something like this:

\begin{verbatim}
options:
  ...
  -n, --noisy   be noisy
  --dry-run     new dry-run option
\end{verbatim}

\subsection{Callback Options\label{optparse-callback-options}}

If \module{optparse}'s built-in actions and types just don't fit the
bill for you, but it's not worth extending \module{optparse} to define
your own actions or types, you'll probably need to define a callback
option.  Defining callback options is quite easy; the tricky part is
writing a good callback (the function that is called when
\module{optparse} encounters the option on the command line).

\subsubsection{Defining a callback option\label{optparse-defining-callback-option}}

As always, you can define a callback option either by directly
instantiating the \class{Option} class, or by using the
\method{add_option()} method of your \class{OptionParser} object. The
only option attribute you must specify is \var{callback}, the function
to call:

\begin{verbatim}
parser.add_option("-c", callback=my_callback)
\end{verbatim}

Note that you supply a function object here --- so you must have
already defined a function \function{my_callback()} when you define
the callback option.  In this simple case, \module{optparse} knows
nothing about the arguments the \programopt{-c} option expects to
take.  Usually, this means that the option doesn't take any arguments
-- the mere presence of \programopt{-c} on the command-line is all it
needs to know.  In some circumstances, though, you might want your
callback to consume an arbitrary number of command-line arguments.
This is where writing callbacks gets tricky; it's covered later in
this document.

There are several other option attributes that you can supply when you
define an option attribute:

\begin{definitions}
\term{type}
has its usual meaning: as with the ``store'' or ``append'' actions, it
instructs \module{optparse} to consume one argument that must be
convertible to \var{type}.  Rather than storing the value(s) anywhere,
though, \module{optparse} converts it to \var{type} and passes it to
your callback function.

\term{nargs}
also has its usual meaning: if it is supplied and \samp{nargs > 1},
\module{optparse} will consume \var{nargs} arguments, each of which
must be convertible to \var{type}.  It then passes a tuple of
converted values to your callback.

\term{callback_args}
a tuple of extra positional arguments to pass to the callback.
    
\term{callback_kwargs}
a dictionary of extra keyword arguments to pass to the callback.
\end{definitions}

\subsubsection{How callbacks are called\label{optparse-callbacks-called}}

All callbacks are called as follows:

\begin{verbatim}
func(option, opt, value, parser, *args, **kwargs)
\end{verbatim}

where

\begin{definitions}
\term{option}
is the \class{Option} instance that's calling the callback.

\term{opt}
is the option string seen on the command-line that's triggering the
callback.  (If an abbreviated long option was used, \var{opt} will be
the full, canonical option string --- e.g. if the user puts
\longprogramopt{foo} on the command-line as an abbreviation for
\longprogramopt{foobar}, then \var{opt} will be
\longprogramopt{foobar}.)

\term{value}
is the argument to this option seen on the command-line.
\module{optparse} will only expect an argument if \var{type} is
set; the type of \var{value} will be the type implied by the
option's type (see~\ref{optparse-option-types}, ``Option types'').  If
\var{type} for this option is None (no argument expected), then
\var{value} will be None.  If \samp{nargs > 1}, \var{value} will
be a tuple of values of the appropriate type.

\term{parser}
is the \class{OptionParser} instance driving the whole thing, mainly
useful because you can access some other interesting data through it,
as instance attributes:

\begin{definitions}
\term{parser.rargs}
the current remaining argument list, ie. with \var{opt} (and
\var{value}, if any) removed, and only the arguments following
them still there.  Feel free to modify \member{parser.rargs},
e.g. by consuming more arguments.
    
\term{parser.largs}
the current set of leftover arguments, ie. arguments that have been
processed but have not been consumed as options (or arguments to
options).  Feel free to modify \member{parser.largs} e.g. by adding
more arguments to it.
    
\term{parser.values}
the object where option values are by default stored.  This is useful
because it lets callbacks use the same mechanism as the rest of
\module{optparse} for storing option values; you don't need to mess
around with globals or closures.  You can also access the value(s) of
any options already encountered on the command-line.
\end{definitions}

\term{args}
is a tuple of arbitrary positional arguments supplied via the
\var{callback}_args option attribute.

\term{kwargs}
is a dictionary of arbitrary keyword arguments supplied via
\var{callback_kwargs}.
\end{definitions}

Since \var{args} and \var{kwargs} are optional (they are only passed
if you supply \var{callback_args} and/or \var{callback_kwargs} when
you define your callback option), the minimal callback function is:

\begin{verbatim}
def my_callback (option, opt, value, parser):
    pass
\end{verbatim}

\subsubsection{Error handling\label{optparse-callback-error-handling}}

The callback function should raise \exception{OptionValueError} if
there are any problems with the option or its
argument(s). \module{optparse} catches this and terminates the
program, printing the error message you supply to stderr.  Your
message should be clear, concise, accurate, and mention the option at
fault.  Otherwise, the user will have a hard time figuring out what he
did wrong.

\subsubsection{Examples\label{optparse-callback-examples}}

Here's an example of a callback option that takes no arguments, and
simply records that the option was seen:

\begin{verbatim}
def record_foo_seen (option, opt, value, parser):
    parser.saw_foo = 1

parser.add_option("--foo", action="callback", callback=record_foo_seen)
\end{verbatim}

Of course, you could do that with the ``store_true'' action.  Here's a
slightly more interesting example: record the fact that
\programopt{-a} is seen, but blow up if it comes after \programopt{-b}
in the command-line.

\begin{verbatim}
def check_order (option, opt, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use -a after -b")
    parser.values.a = 1
...
parser.add_option("-a", action="callback", callback=check_order)
parser.add_option("-b", action="store_true", dest="b")
\end{verbatim}

If you want to reuse this callback for several similar options (set a
flag, but blow up if \programopt{-b} has already been seen), it needs
a bit of work: the error message and the flag that it sets must be
generalized.

\begin{verbatim}
def check_order (option, opt, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use %s after -b" % opt)
    setattr(parser.values, option.dest, 1)
...
parser.add_option("-a", action="callback", callback=check_order, dest='a')
parser.add_option("-b", action="store_true", dest="b")
parser.add_option("-c", action="callback", callback=check_order, dest='c')
\end{verbatim}

Of course, you could put any condition in there --- you're not limited
to checking the values of already-defined options.  For example, if
you have options that should not be called when the moon is full, all
you have to do is this:

\begin{verbatim}
def check_moon (option, opt, value, parser):
    if is_full_moon():
        raise OptionValueError("%s option invalid when moon full" % opt)
    setattr(parser.values, option.dest, 1)
...
parser.add_option("--foo",
                  action="callback", callback=check_moon, dest="foo")
\end{verbatim}

(The definition of is_full_moon() is left as an exercise for the
reader.)

\strong{Fixed arguments}

Things get slightly more interesting when you define callback options
that take a fixed number of arguments.  Specifying that a callback
option takes arguments is similar to defining a ``store'' or
``append'' option: if you define \var{type}, then the option takes one
argument that must be convertible to that type; if you further define
\var{nargs}, then the option takes that many arguments.

Here's an example that just emulates the standard ``store'' action:

\begin{verbatim}
def store_value (option, opt, value, parser):
    setattr(parser.values, option.dest, value)
...
parser.add_option("--foo",
                  action="callback", callback=store_value,
                  type="int", nargs=3, dest="foo")
\end{verbatim}

Note that \module{optparse} takes care of consuming 3 arguments and
converting them to integers for you; all you have to do is store them.
(Or whatever: obviously you don't need a callback for this example.
Use your imagination!)

\strong{Variable arguments}

Things get hairy when you want an option to take a variable number of
arguments.  For this case, you have to write a callback;
\module{optparse} doesn't provide any built-in capabilities for it.
You have to deal with the full-blown syntax for conventional \UNIX{}
command-line parsing.  (Previously, \module{optparse} took care of
this for you, but I got it wrong.  It was fixed at the cost of making
this kind of callback more complex.)  In particular, callbacks have to
worry about bare \longprogramopt{} and \programopt{-} arguments; the
convention is:

\begin{itemize}
\item bare \longprogramopt{}, if not the argument to some option,
causes command-line processing to halt and the \longprogramopt{}
itself is lost.

\item bare \programopt{-} similarly causes command-line processing to
halt, but the \programopt{-} itself is kept.

\item either \longprogramopt{} or \programopt{-} can be option
arguments.
\end{itemize}

If you want an option that takes a variable number of arguments, there
are several subtle, tricky issues to worry about.  The exact
implementation you choose will be based on which trade-offs you're
willing to make for your application (which is why \module{optparse}
doesn't support this sort of thing directly).

Nevertheless, here's a stab at a callback for an option with variable
arguments:

\begin{verbatim}
def varargs (option, opt, value, parser):
    assert value is None
    done = 0
    value = []
    rargs = parser.rargs
    while rargs:
        arg = rargs[0]

        # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",
        # etc.  Note that this also stops on "-3" or "-3.0", so if
        # your option takes numeric values, you will need to handle
        # this.
        if ((arg[:2] == "--" and len(arg) > 2) or
            (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
            break
        else:
            value.append(arg)
            del rargs[0]

     setattr(parser.values, option.dest, value)

...
parser.add_option("-c", "--callback",
                  action="callback", callback=varargs)
\end{verbatim}

The main weakness with this particular implementation is that negative
numbers in the arguments following \programopt{-c} will be interpreted
as further options, rather than as arguments to \programopt{-c}.
Fixing this is left as an exercise for the reader.

\subsection{Extending \module{optparse}\label{optparse-extending}}

Since the two major controlling factors in how \module{optparse}
interprets command-line options are the action and type of each
option, the most likely direction of extension is to add new actions
and new types.

Also, the examples section includes several demonstrations of
extending \module{optparse} in different ways: eg. a case-insensitive
option parser, or two kinds of option parsers that implement
``required options''.

\subsubsection{Adding new types\label{optparse-adding-types}}

To add new types, you need to define your own subclass of
\module{optparse}'s \class{Option} class.  This class has a couple of
attributes that define \module{optparse}'s types: \member{TYPES} and
\member{TYPE_CHECKER}.

\member{TYPES} is a tuple of type names; in your subclass, simply
define a new tuple \member{TYPES} that builds on the standard one.

\member{TYPE_CHECKER} is a dictionary mapping type names to
type-checking functions.  A type-checking function has the following
signature:

\begin{verbatim}
def check_foo (option : Option, opt : string, value : string)
               -> foo
\end{verbatim}

You can name it whatever you like, and make it return any type you
like.  The value returned by a type-checking function will wind up in
the \class{OptionValues} instance returned by
\method{OptionParser.parse_args()}, or be passed to callbacks as the
\var{value} parameter.

Your type-checking function should raise \exception{OptionValueError}
if it encounters any problems.  \exception{OptionValueError} takes a
single string argument, which is passed as-is to
\class{OptionParser}'s \method{error()} method, which in turn prepends
the program name and the string ``error:'' and prints everything to
stderr before terminating the process.

Here's a silly example that demonstrates adding a ``complex'' option
type to parse Python-style complex numbers on the command line.  (This
is even sillier than it used to be, because \module{optparse} 1.3 adds
built-in support for complex numbers [purely for completeness], but
never mind.)

First, the necessary imports:

\begin{verbatim}
from copy import copy
from optparse import Option, OptionValueError
\end{verbatim}

You need to define your type-checker first, since it's referred to
later (in the \member{TYPE_CHECKER} class attribute of your
\class{Option} subclass):

\begin{verbatim}
def check_complex (option, opt, value):
    try:
        return complex(value)
    except ValueError:
        raise OptionValueError(
            "option %s: invalid complex value: %r" % (opt, value))
\end{verbatim}

Finally, the \class{Option} subclass:

\begin{verbatim}
class MyOption (Option):
    TYPES = Option.TYPES + ("complex",)
    TYPE_CHECKER = copy(Option.TYPE_CHECKER)
    TYPE_CHECKER["complex"] = check_complex
\end{verbatim}

(If we didn't make a \function{copy()} of
\member{Option.TYPE_CHECKER}, we would end up modifying the
\member{TYPE_CHECKER} attribute of \module{optparse}'s Option class.
This being Python, nothing stops you from doing that except good
manners and common sense.)

That's it!  Now you can write a script that uses the new option type
just like any other \module{optparse}-based script, except you have to
instruct your \class{OptionParser} to use \class{MyOption} instead of
\class{Option}:

\begin{verbatim}
parser = OptionParser(option_class=MyOption)
parser.add_option("-c", action="store", type="complex", dest="c")
\end{verbatim}

Alternately, you can build your own option list and pass it to
\class{OptionParser}; if you don't use \method{add_option()} in the
above way, you don't need to tell \class{OptionParser} which option
class to use:

\begin{verbatim}
option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)
\end{verbatim}

\subsubsection{Adding new actions\label{optparse-adding-actions}}

Adding new actions is a bit trickier, because you have to understand
that \module{optparse} has a couple of classifications for actions:

\begin{definitions}
\term{"store" actions}
    actions that result in \module{optparse} storing a value to an attribute
    of the OptionValues instance; these options require a 'dest'
    attribute to be supplied to the Option constructor
\term{"typed" actions}
    actions that take a value from the command line and expect it to be
    of a certain type; or rather, a string that can be converted to a
    certain type.  These options require a 'type' attribute to the
    Option constructor.
\end{definitions}

Some default ``store'' actions are ``store'', ``store_const'',
``append'', and ``count''. The default ``typed'' actions are
``store'', ``append'', and ``callback''.

When you add an action, you need to decide if it's a ``store'' action,
a ``typed'', neither, or both.  Three class attributes of
\class{Option} (or your \class{Option} subclass) control this:

\begin{memberdesc}{ACTIONS}
    All actions must be listed as strings in ACTIONS.
\end{memberdesc}
\begin{memberdesc}{STORE_ACTIONS}
    "store" actions are additionally listed here.
\end{memberdesc}
\begin{memberdesc}{TYPED_ACTIONS}
    "typed" actions are additionally listed here.
\end{memberdesc}

In order to actually implement your new action, you must override
\class{Option}'s \method{take_action()} method and add a case that
recognizes your action.

For example, let's add an ``extend'' action.  This is similar to the
standard ``append'' action, but instead of taking a single value from
the command-line and appending it to an existing list, ``extend'' will
take multiple values in a single comma-delimited string, and extend an
existing list with them.  That is, if \longprogramopt{names} is an
``extend'' option of type string, the command line:

\begin{verbatim}
--names=foo,bar --names blah --names ding,dong
\end{verbatim}

would result in a list:

\begin{verbatim}
["foo", "bar", "blah", "ding", "dong"]
\end{verbatim}

Again we define a subclass of \class{Option}:

\begin{verbatim}
class MyOption (Option):

    ACTIONS = Option.ACTIONS + ("extend",)
    STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
    TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)

    def take_action (self, action, dest, opt, value, values, parser):
        if action == "extend":
            lvalue = value.split(",")
            values.ensure_value(dest, []).extend(lvalue)
        else:
            Option.take_action(
                self, action, dest, opt, value, values, parser)
\end{verbatim}

Features of note:

\begin{itemize}
\item ``extend'' both expects a value on the command-line and stores that
value somewhere, so it goes in both \member{STORE_ACTIONS} and
\member{TYPED_ACTIONS}.

\item \method{MyOption.take_action()} implements just this one new
action, and passes control back to \method{Option.take_action()} for
the standard \module{optparse} actions.

\item \var{values} is an instance of the \class{Values} class, which
provides the very useful \method{ensure_value()}
method. \method{ensure_value()} is essentially \function{getattr()}
with a safety valve; it is called as:

\begin{verbatim}
values.ensure_value(attr, value)
\end{verbatim}
\end{itemize}

If the \member{attr} attribute of \var{values} doesn't exist or is
None, then \method{ensure_value()} first sets it to \var{value}, and
then returns \var{value}. This is very handy for actions like
``extend'', ``append'', and ``count'', all of which accumulate data in
a variable and expect that variable to be of a certain type (a list
for the first two, an integer for the latter).  Using
\method{ensure_value()} means that scripts using your action don't
have to worry about setting a default value for the option
destinations in question; they can just leave the default as None and
\method{ensure_value()} will take care of getting it right when it's
needed.

\subsubsection{Other reasons to extend \module{optparse}\label{optparse-extending-other-reasons}}

Adding new types and new actions are the big, obvious reasons why you
might want to extend \module{optparse}.  I can think of at least two
other areas to play with.

First, the simple one: \class{OptionParser} tries to be helpful by
calling \function{sys.exit()} when appropriate, ie. when there's an
error on the command-line or when the user requests help.  In the
former case, the traditional course of letting the script crash with a
traceback is unacceptable; it will make users think there's a bug in
your script when they make a command-line error.  In the latter case,
there's generally not much point in carrying on after printing a help
message.

If this behaviour bothers you, it shouldn't be too hard to ``fix'' it.
You'll have to

\begin{enumerate}
\item subclass OptionParser and override the error() method
\item subclass Option and override the take_action() method --- you'll
      need to provide your own handling of the "help" action that
      doesn't call sys.exit()
\end{enumerate}

The second, much more complex, possibility is to override the
command-line syntax implemented by \module{optparse}.  In this case,
you'd leave the whole machinery of option actions and types alone, but
rewrite the code that processes \var{sys.argv}.  You'll need to
subclass \class{OptionParser} in any case; depending on how radical a
rewrite you want, you'll probably need to override one or all of
\method{parse_args()}, \method{_process_long_opt()}, and
\method{_process_short_opts()}.

Both of these are left as an exercise for the reader.  I have not
tried to implement either myself, since I'm quite happy with
\module{optparse}'s default behaviour (naturally).

Happy hacking, and don't forget: Use the Source, Luke.

\subsubsection{Examples\label{optparse-extending-examples}}

Here are a few examples of extending the \module{optparse} module.

First, let's change the option-parsing to be case-insensitive:

\verbatiminput{caseless.py}

And two ways of implementing ``required options'' with
\module{optparse}.

Version 1: Add a method to \class{OptionParser} which applications
must call after parsing arguments:

\verbatiminput{required_1.py}

Version 2: Extend \class{Option} and add a \member{required}
attribute; extend \class{OptionParser} to ensure that required options
are present after parsing:

\verbatiminput{required_2.py}