1716 lines
62 KiB
TeX
1716 lines
62 KiB
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=True,
|
|
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 == False}, 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{Philosophy\label{optparse-philosophy}}
|
|
|
|
The purpose of \module{optparse} is to make it very easy to provide the
|
|
most standard, obvious, straightforward, and user-friendly user
|
|
interface for \UNIX{} command-line programs. The \module{optparse}
|
|
philosophy is heavily influenced by the \UNIX{} and GNU toolkits, and
|
|
this section is meant to explain that philosophy.
|
|
|
|
\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
|
|
\code{sys.argv[1:]}. (\code{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 is occasionally desirable to use an argument list other than
|
|
\code{sys.argv[1:]}, so you should read ``argument'' as ``an element of
|
|
\code{sys.argv[1:]}, or of some other list provided as a substitute for
|
|
\code{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}
|
|
|
|
\module{optparse} does not support these option syntaxes, and it never
|
|
will. (If you really want to use one of those option syntaxes, you'll
|
|
have to subclass \class{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} and \programopt{-b} are both
|
|
options, and \programopt{-a} takes an optional argument, how do we
|
|
interpret \programopt{-ab}? \module{optparse} does not support optional
|
|
option arguments.
|
|
|
|
\term{positional argument}
|
|
something leftover in the argument list after options have been
|
|
parsed, i.e., 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; the presence of ``required options''
|
|
in a program is usually a sign of careless user interface 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,
|
|
\code{/tmp/report.txt} is an option argument. \code{foo} and \code{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 should be
|
|
\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. For now, we'll only cover four of the things you can put
|
|
there: \emph{action}, \emph{type}, \emph{dest} (destination), and
|
|
\emph{help}.
|
|
|
|
\subsubsection{The \emph{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 \emph{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 \code{sys.argv[1:]}.)
|
|
|
|
When \module{optparse} sees the \programopt{-f}, it consumes the next
|
|
argument---\code{foo.txt}---and stores it in the \member{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 \code{foo.txt}.
|
|
|
|
Other option types supported by \module{optparse} are \code{int} and
|
|
\code{float}. Here's an option that expects an integer argument:
|
|
|
|
\begin{verbatim}
|
|
parser.add_option("-n", type="int", dest="num")
|
|
\end{verbatim}
|
|
|
|
This example doesn't provide a long option, which is perfectly
|
|
acceptable. It also doesn'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, since \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}
|
|
|
|
This prints \code{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
|
|
\member{foo_bar}. If there are no long option strings,
|
|
\module{optparse} looks at the first short option: the default
|
|
destination for \programopt{-f} is \member{f}.
|
|
|
|
Adding types is fairly easy; please refer to
|
|
section~\ref{optparse-adding-types}, ``Adding new types.''
|
|
|
|
\subsubsection{Other \emph{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
|
|
\code{options.verbose} to \code{True}; when it sees \programopt{-q}, it
|
|
sets \code{options.verbose} to \code{False}.
|
|
|
|
\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 \code{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 \member{verbose} to \code{True} unless
|
|
\programopt{-q} is seen, then we can do this:
|
|
|
|
\begin{verbatim}
|
|
parser.add_option("-v", action="store_true", dest="verbose", default=True)
|
|
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=True)
|
|
\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 \member{verbose} variable).
|
|
|
|
Consider this:
|
|
|
|
\begin{verbatim}
|
|
parser.add_option("-v", action="store_true", dest="verbose", default=False)
|
|
parser.add_option("-q", action="store_false", dest="verbose", default=True)
|
|
\end{verbatim}
|
|
|
|
Again, the default value for \member{verbose} will be \code{True}: the last
|
|
default value supplied for any particular destination 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} argument 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=True,
|
|
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 \samp{\%prog} in the usage string to the name of the
|
|
current script, i.e. \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: \code{"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}
|
|
|
|
\var{version} can contain anything you like; \code{\%prog} is expanded
|
|
in \var{version} just as with \var{usage}. 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 \code{\%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} % $ (avoid confusing emacs)
|
|
|
|
\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{-n 4x} where \programopt{-n} is an
|
|
integer-valued option. In this case, \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 \module{optparse}-based scripts typically look like:
|
|
|
|
\begin{verbatim}
|
|
from optparse import OptionParser
|
|
[...]
|
|
def main():
|
|
usage = "usage: \%prog [-f] [-v] [-q] firstarg secondarg"
|
|
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")
|
|
|
|
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}}
|
|
|
|
\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}
|
|
from optparse import OptionParser, make_option
|
|
[...]
|
|
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 a factory function for generating
|
|
\class{Option} objects.)
|
|
|
|
For long option lists, it may be more convenient/readable to create the
|
|
list separately:
|
|
|
|
\begin{verbatim}
|
|
option_list = [make_option("-f", "--filename",
|
|
action="store", type="string", dest="filename"),
|
|
[... more 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()} (i.e., 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, i.e. 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. The rules governing which keyword args
|
|
you must supply for a given \class{Option} are fairly complicated, 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, i.e. what to do
|
|
when we encounter this option on the command-line. The possible actions
|
|
are:
|
|
|
|
\begin{tableii}{l|l}{code}{Action}{Meaning}
|
|
\lineii{store}{store this option's argument (default)}
|
|
\lineii{store_const}{store a constant value}
|
|
\lineii{store_true}{store a true value}
|
|
\lineii{store_false}{store a false value}
|
|
\lineii{append}{append this option's argument to a list}
|
|
\lineii{count}{increment a counter by one}
|
|
\lineii{callback}{call a specified function}
|
|
\lineii{help}{print a usage message including all options and the
|
|
documentation for them}
|
|
\end{tableii}
|
|
|
|
(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
|
|
\code{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 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
|
|
\code{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} (a sequence of strings) is supplied, 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 \member{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 \member{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("--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 \code{True} to \var{dest}.
|
|
|
|
\term{store_false} [required: \var{dest}]
|
|
|
|
Like ``store_true'', but stores \code{False}
|
|
|
|
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
|
|
(i.e. the default is \code{None}), an empty list is automatically created when
|
|
\module{optparse} first encounters this option on the command-line.
|
|
If \code{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}), \module{optparse} catches this exception and
|
|
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 \var{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 \code{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 \code{error}.
|
|
|
|
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---for example, 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 \code{None} (no argument expected), then
|
|
\var{value} will be \code{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, i.e. 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, i.e. 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 \code{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: e.g. 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 \var{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 \var{type} attribute to the
|
|
Option constructor.
|
|
\end{definitions}
|
|
|
|
Some default ``store'' actions are \var{store}, \var{store_const},
|
|
\var{append}, and \var{count}. The default ``typed'' actions are
|
|
\var{store}, \var{append}, and \var{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
|
|
\code{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 \code{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, i.e. 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 \code{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}
|
|
|
|
\begin{seealso}
|
|
\seemodule{getopt}{More traditional \UNIX-style command line option parsing.}
|
|
\end{seealso}
|