1427 lines
54 KiB
TeX
1427 lines
54 KiB
TeX
\section{\module{optparse} --- More powerful command line option parser}
|
|
\declaremodule{standard}{optparse}
|
|
\moduleauthor{Greg Ward}{gward@python.net}
|
|
\modulesynopsis{More convenient, flexible, and powerful command-line parsing library.}
|
|
\versionadded{2.3}
|
|
\sectionauthor{Greg Ward}{gward@python.net}
|
|
% An intro blurb used only when generating LaTeX docs for the Python
|
|
% manual (based on README.txt).
|
|
|
|
\code{optparse} is a more convenient, flexible, and powerful library for
|
|
parsing command-line options than \code{getopt}. \code{optparse} uses a more
|
|
declarative style of command-line parsing: you create an instance of
|
|
\class{OptionParser}, populate it with options, and parse the command line.
|
|
\code{optparse} allows users to specify options in the conventional GNU/POSIX
|
|
syntax, and additionally generates usage and help messages for you.
|
|
|
|
Here's an example of using \code{optparse} in 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, for example:
|
|
\begin{verbatim}
|
|
<yourscript> --file=outfile -q
|
|
\end{verbatim}
|
|
|
|
As it parses the command line, \code{optparse} sets attributes of the
|
|
\var{options} object returned by \method{parse{\_}args()} based on user-supplied
|
|
command-line values. When \method{parse{\_}args()} returns from parsing this
|
|
command line, \var{options.filename} will be \code{"outfile"} and
|
|
\code{options.verbose} will be \code{False}. \code{optparse} supports both long
|
|
and short options, allows short options to be merged together, and
|
|
allows options to be associated with their arguments in a variety of
|
|
ways. Thus, the following command lines are all equivalent to the above
|
|
example:
|
|
\begin{verbatim}
|
|
<yourscript> -f outfile --quiet
|
|
<yourscript> --quiet --file outfile
|
|
<yourscript> -q -foutfile
|
|
<yourscript> -qfoutfile
|
|
\end{verbatim}
|
|
|
|
Additionally, users can run one of
|
|
\begin{verbatim}
|
|
<yourscript> -h
|
|
<yourscript> --help
|
|
\end{verbatim}
|
|
|
|
and \code{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
|
|
-f FILE, --file=FILE write report to FILE
|
|
-q, --quiet don't print status messages to stdout
|
|
\end{verbatim}
|
|
|
|
where the value of \emph{yourscript} is determined at runtime (normally
|
|
from \code{sys.argv{[}0]}).
|
|
% $Id: intro.txt 413 2004-09-28 00:59:13Z greg $
|
|
|
|
|
|
\subsection{Background\label{optparse-background}}
|
|
|
|
\module{optparse} was explicitly designed to encourage the creation of programs with
|
|
straightforward, conventional command-line interfaces. To that end, it
|
|
supports only the most common command-line syntax and semantics
|
|
conventionally used under \UNIX{}. If you are unfamiliar with these
|
|
conventions, read this section to acquaint yourself with them.
|
|
|
|
|
|
\subsubsection{Terminology\label{optparse-terminology}}
|
|
\begin{description}
|
|
\item[argument]
|
|
a string entered on the command-line, and passed by the shell to
|
|
\code{execl()} or \code{execv()}. In Python, arguments are elements of
|
|
\code{sys.argv{[}1:]} (\code{sys.argv{[}0]} is the name of the program being
|
|
executed). \UNIX{} shells also use the term ``word''.
|
|
|
|
It is occasionally desirable to substitute 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:]}''.
|
|
\item[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 a hyphen (``-'') followed by a
|
|
single letter, e.g. \code{"-x"} or \code{"-F"}. Also, traditional \UNIX{}
|
|
syntax allows multiple options to be merged into a single argument,
|
|
e.g. \code{"-x -F"} is equivalent to \code{"-xF"}. The GNU project
|
|
introduced \code{"-{}-"} followed by a series of hyphen-separated words,
|
|
e.g. \code{"-{}-file"} or \code{"-{}-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. \code{"-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. \code{"-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. \code{"+f"}, \code{"+rgb"}
|
|
|
|
\item {}
|
|
a slash followed by a letter, or a few letters, or a word, e.g.
|
|
\code{"/f"}, \code{"/file"}
|
|
|
|
\end{itemize}
|
|
|
|
These option syntaxes are not supported by \module{optparse}, and they never will
|
|
be. This is deliberate: the first three are non-standard on any
|
|
environment, and the last only makes sense if you're exclusively
|
|
targeting VMS, MS-DOS, and/or Windows.
|
|
\item[option argument]
|
|
an argument that follows an option, is closely associated with that
|
|
option, and is consumed from the argument list when that option is.
|
|
With \module{optparse}, option arguments may either be in a separate argument
|
|
from their option:
|
|
\begin{verbatim}
|
|
-f foo
|
|
--file foo
|
|
\end{verbatim}
|
|
|
|
or included in the same argument:
|
|
\begin{verbatim}
|
|
-ffoo
|
|
--file=foo
|
|
\end{verbatim}
|
|
|
|
Typically, a given option either takes an argument or it doesn't.
|
|
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 \code{"-a"} takes an optional argument and \code{"-b"} is
|
|
another option entirely, how do we interpret \code{"-ab"}? Because of
|
|
this ambiguity, \module{optparse} does not support this feature.
|
|
\item[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.
|
|
\item[required option]
|
|
an option that must be supplied on the command-line; note that the
|
|
phrase ``required option'' is self-contradictory in English. \module{optparse}
|
|
doesn't prevent you from implementing required options, but doesn't
|
|
give you much help at it either. See \code{examples/required{\_}1.py} and
|
|
\code{examples/required{\_}2.py} in the \module{optparse} source distribution for two
|
|
ways to implement required options with \module{optparse}.
|
|
\end{description}
|
|
|
|
For example, consider this hypothetical command-line:
|
|
\begin{verbatim}
|
|
prog -v --report /tmp/report.txt foo bar
|
|
\end{verbatim}
|
|
|
|
\code{"-v"} and \code{"-{}-report"} are both options. Assuming that
|
|
\longprogramopt{report} 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-what-options-for}}
|
|
|
|
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 main
|
|
exceptions are \code{find}, \code{tar}, and \code{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.
|
|
|
|
As an example of good command-line interface design, consider the humble
|
|
\code{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, \code{cp} fails if you run it with no arguments. However, it has a
|
|
flexible, useful syntax that does not require any options at all:
|
|
\begin{verbatim}
|
|
cp SOURCE DEST
|
|
cp SOURCE ... DEST-DIR
|
|
\end{verbatim}
|
|
|
|
You can get pretty far with just that. Most \code{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 \code{cp}, which is to copy either one file to
|
|
another, or several files to another directory.
|
|
|
|
|
|
\subsubsection{What are positional arguments for?\label{optparse-what-positional-arguments-for}}
|
|
|
|
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, or a GUI: if you make
|
|
that many demands on your users, most of them will simply 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, widgets 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. Too much flexibility has drawbacks as well, of
|
|
course; too many options can overwhelm users and make your code much
|
|
harder to maintain.
|
|
% $Id: tao.txt 413 2004-09-28 00:59:13Z greg $
|
|
|
|
|
|
\subsection{Tutorial\label{optparse-tutorial}}
|
|
|
|
While \module{optparse} is quite flexible and powerful, it's also straightforward to
|
|
use in most cases. This section covers the code patterns that are
|
|
common to any \module{optparse}-based program.
|
|
|
|
First, you need to import the OptionParser class; then, early in the
|
|
main program, create an OptionParser instance:
|
|
\begin{verbatim}
|
|
from optparse import OptionParser
|
|
[...]
|
|
parser = OptionParser()
|
|
\end{verbatim}
|
|
|
|
Then you can start defining options. The basic syntax is:
|
|
\begin{verbatim}
|
|
parser.add_option(opt_str, ...,
|
|
attr=value, ...)
|
|
\end{verbatim}
|
|
|
|
Each option has one or more option strings, such as \code{"-f"} or
|
|
\code{"-{}-file"}, and several option attributes that tell \module{optparse} what to
|
|
expect and what to do when it encounters that option on the command
|
|
line.
|
|
|
|
Typically, each option will have one short option string and one long
|
|
option string, e.g.:
|
|
\begin{verbatim}
|
|
parser.add_option("-f", "--file", ...)
|
|
\end{verbatim}
|
|
|
|
You're free to define as many short option strings and as many long
|
|
option strings as you like (including zero), as long as there is at
|
|
least one option string overall.
|
|
|
|
The option strings passed to \method{add{\_}option()} are effectively labels for
|
|
the option defined by that call. For brevity, we will frequently refer
|
|
to \emph{encountering an option} on the command line; in reality, \module{optparse}
|
|
encounters \emph{option strings} and looks up options from them.
|
|
|
|
Once all of your options are defined, instruct \module{optparse} to parse your
|
|
program's command line:
|
|
\begin{verbatim}
|
|
(options, args) = parser.parse_args()
|
|
\end{verbatim}
|
|
|
|
(If you like, you can pass a custom argument list to \method{parse{\_}args()},
|
|
but that's rarely necessary: by default it uses \code{sys.argv{[}1:]}.)
|
|
|
|
\method{parse{\_}args()} returns two values:
|
|
\begin{itemize}
|
|
\item {}
|
|
\var{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then
|
|
\var{options.file} will be the filename supplied by the user, or
|
|
\code{None} if the user did not supply that option
|
|
|
|
\item {}
|
|
\var{args}, the list of positional arguments leftover after parsing
|
|
options
|
|
|
|
\end{itemize}
|
|
|
|
This tutorial section only covers the four most important option
|
|
attributes: \member{action}, \member{type}, \member{dest} (destination), and \member{help}.
|
|
Of these, \member{action} is the most fundamental.
|
|
|
|
|
|
\subsubsection{Understanding option actions\label{optparse-understanding-option-actions}}
|
|
|
|
Actions tell \module{optparse} what to do when it encounters an option on the
|
|
command line. There is a fixed set of actions hard-coded into \module{optparse};
|
|
adding new actions is an advanced topic covered in section~\ref{optparse-extending}, Extending \module{optparse}.
|
|
Most actions tell \module{optparse} to store a value in some variable{---}for
|
|
example, take a string from the command line and store it in an
|
|
attribute of \var{options}.
|
|
|
|
If you don't specify an option action, \module{optparse} defaults to \code{store}.
|
|
|
|
|
|
\subsubsection{The store action\label{optparse-store-action}}
|
|
|
|
The most common option action is \code{store}, which tells \module{optparse} to 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:
|
|
\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}
|
|
|
|
When \module{optparse} sees the option string \code{"-f"}, it consumes the next
|
|
argument, \code{"foo.txt"}, and stores it in \var{options.filename}. So,
|
|
after this call to \method{parse{\_}args()}, \var{options.filename} is
|
|
\code{"foo.txt"}.
|
|
|
|
Some 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}
|
|
|
|
Note that this option has no long option string, which is perfectly
|
|
acceptable. Also, there's no explicit action, since the default is
|
|
\code{store}.
|
|
|
|
Let's parse another fake command-line. This time, we'll jam the option
|
|
argument right up against the option: since \code{"-n42"} (one argument) is
|
|
equivalent to \code{"-n 42"} (two arguments), the code
|
|
\begin{verbatim}
|
|
(options, args) = parser.parse_args(["-n42"])
|
|
print options.num
|
|
\end{verbatim}
|
|
|
|
will print \code{"42"}.
|
|
|
|
If you don't specify a type, \module{optparse} assumes \code{string}. Combined with the
|
|
fact that the default action is \code{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
|
|
\code{"-{}-foo-bar"}, then the default destination is \code{foo{\_}bar}. If there
|
|
are no long option strings, \module{optparse} looks at the first short option
|
|
string: the default destination for \code{"-f"} is \code{f}.
|
|
|
|
\module{optparse} also includes built-in \code{long} and \code{complex} types. Adding
|
|
types is covered in section~\ref{optparse-extending}, Extending \module{optparse}.
|
|
|
|
|
|
\subsubsection{Handling boolean (flag) options\label{optparse-handling-boolean-options}}
|
|
|
|
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, \code{store{\_}true} and \code{store{\_}false}. For example, you might have a
|
|
\var{verbose} flag that is turned on with \code{"-v"} and off with \code{"-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} encounters \code{"-v"} on the command line, it sets
|
|
\code{options.verbose} to \code{True}; when it encounters \code{"-q"},
|
|
\code{options.verbose} is set to \code{False}.
|
|
|
|
|
|
\subsubsection{Other actions\label{optparse-other-actions}}
|
|
|
|
Some other actions supported by \module{optparse} are:
|
|
\begin{description}
|
|
\item[\code{store{\_}const}]
|
|
store a constant value
|
|
\item[\code{append}]
|
|
append this option's argument to a list
|
|
\item[\code{count}]
|
|
increment a counter by one
|
|
\item[\code{callback}]
|
|
call a specified function
|
|
\end{description}
|
|
|
|
These are covered in section~\ref{optparse-reference-guide}, Reference Guide and section~\ref{optparse-option-callbacks}, Option Callbacks.
|
|
|
|
|
|
\subsubsection{Default values\label{optparse-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}. This is usually fine, but sometimes you
|
|
want more control. \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 \code{True} unless \code{"-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}
|
|
|
|
Since default values apply to the \emph{destination} rather than to any
|
|
particular option, and these two options happen to have the same
|
|
destination, 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}
|
|
|
|
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 \var{verbose} will be \code{True}: the last
|
|
default value supplied for any particular destination is the one that
|
|
counts.
|
|
|
|
A clearer way to specify default values is the \method{set{\_}defaults()}
|
|
method of OptionParser, which you can call at any time before calling
|
|
\method{parse{\_}args()}:
|
|
\begin{verbatim}
|
|
parser.set_defaults(verbose=True)
|
|
parser.add_option(...)
|
|
(options, args) = parser.parse_args()
|
|
\end{verbatim}
|
|
|
|
As before, the last value specified for a given option destination is
|
|
the one that counts. For clarity, try to use one method or the other of
|
|
setting default values, not both.
|
|
|
|
|
|
\subsubsection{Generating help\label{optparse-generating-help}}
|
|
|
|
\module{optparse}'s ability to generate help and usage text automatically is useful
|
|
for creating user-friendly command-line interfaces. All you have to do
|
|
is supply a \member{help} value for each option, and optionally a short usage
|
|
message for your whole program. Here's an OptionParser populated 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", "--filename",
|
|
metavar="FILE", help="write output to FILE"),
|
|
parser.add_option("-m", "--mode",
|
|
default="intermediate",
|
|
help="interaction mode: novice, intermediate, "
|
|
"or expert [default: %default]")
|
|
\end{verbatim}
|
|
|
|
If \module{optparse} encounters either \code{"-h"} or \code{"-{}-help"} on the command-line,
|
|
or if you just call \method{parser.print{\_}help()}, it prints the following to
|
|
standard output:
|
|
\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)
|
|
-f FILE, --filename=FILE
|
|
write output to FILE
|
|
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
|
|
expert [default: intermediate]
|
|
\end{verbatim}
|
|
|
|
(If the help output is triggered by a help option, \module{optparse} exits after
|
|
printing the help text.)
|
|
|
|
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 \code{"{\%}prog"} in the usage string to the name of the current
|
|
program, 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}
|
|
-m MODE, --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 \longprogramopt{filename} option explicitly sets
|
|
\code{metavar="FILE"}, resulting in this automatically-generated option
|
|
description:
|
|
\begin{verbatim}
|
|
-f FILE, --filename=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 semi-formal syntax ``-f
|
|
FILE'' 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.
|
|
|
|
\item {}
|
|
options that have a default value can include \code{{\%}default} in
|
|
the help string{---}\module{optparse} will replace it with \function{str()} of the
|
|
option's default value. If an option has no default value (or the
|
|
default value is \code{None}), \code{{\%}default} expands to \code{none}.
|
|
|
|
\end{itemize}
|
|
|
|
|
|
\subsubsection{Printing a version string\label{optparse-printing-version-string}}
|
|
|
|
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 \code{version}
|
|
argument to OptionParser:
|
|
\begin{verbatim}
|
|
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
|
|
\end{verbatim}
|
|
|
|
Note that \code{"{\%}prog"} is expanded just like it is in \var{usage}. Apart
|
|
from that, \code{version} can contain anything you like. When you supply
|
|
it, \module{optparse} automatically adds a \code{"-{}-version"} option to your parser.
|
|
If it encounters this option on the command line, it expands your
|
|
\code{version} string (by replacing \code{"{\%}prog"}), prints it to stdout, and
|
|
exits.
|
|
|
|
For example, if your script is called \code{/usr/bin/foo}:
|
|
\begin{verbatim}
|
|
$ /usr/bin/foo --version
|
|
foo 1.0
|
|
\end{verbatim}
|
|
|
|
|
|
\subsubsection{How \module{optparse} handles errors\label{optparse-how-optik-handles-errors}}
|
|
|
|
There are two broad classes of errors that \module{optparse} has to worry about:
|
|
programmer errors and user errors. Programmer errors are usually
|
|
erroneous calls to \code{parse.add{\_}option()}, e.g. invalid option strings,
|
|
unknown option attributes, missing option attributes, etc. These are
|
|
dealt with in the usual way: raise an exception (either
|
|
\code{optparse.OptionError} or \code{TypeError}) and let the program crash.
|
|
|
|
Handling user errors is much more important, since they are guaranteed
|
|
to happen no matter how stable your code is. \module{optparse} can automatically
|
|
detect some user errors, such as bad option arguments (passing \code{"-n
|
|
4x"} where \programopt{-n} takes an integer argument), missing arguments
|
|
(\code{"-n"} at the end of the command line, where \programopt{-n} takes an argument
|
|
of any type). Also, you can call \code{parser.error()} to signal an
|
|
application-defined error condition:
|
|
\begin{verbatim}
|
|
(options, args) = parser.parse_args()
|
|
[...]
|
|
if options.a and options.b:
|
|
parser.error("options -a and -b are mutually exclusive")
|
|
\end{verbatim}
|
|
|
|
In either case, \module{optparse} handles the error the same way: it prints the
|
|
program's usage message and an error message to standard error and
|
|
exits with error status 2.
|
|
|
|
Consider the first example above, where the user passes \code{"4x"} to an
|
|
option that takes an integer:
|
|
\begin{verbatim}
|
|
$ /usr/bin/foo -n 4x
|
|
usage: foo [options]
|
|
|
|
foo: error: option -n: invalid integer value: '4x'
|
|
\end{verbatim}
|
|
|
|
Or, where the user fails to pass a value at all:
|
|
\begin{verbatim}
|
|
$ /usr/bin/foo -n
|
|
usage: foo [options]
|
|
|
|
foo: error: -n option requires an argument
|
|
\end{verbatim}
|
|
|
|
\module{optparse}-generated error messages take care always to mention the option
|
|
involved in the error; be sure to do the same when calling
|
|
\code{parser.error()} from your application code.
|
|
|
|
If \module{optparse}'s default error-handling behaviour does not suite your needs,
|
|
you'll need to subclass OptionParser and override \code{exit()} and/or
|
|
\method{error()}.
|
|
|
|
|
|
\subsubsection{Putting it all together\label{optparse-putting-it-all-together}}
|
|
|
|
Here's what \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", 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
|
|
[...]
|
|
|
|
if __name__ == "__main__":
|
|
main()
|
|
\end{verbatim}
|
|
% $Id: tutorial.txt 415 2004-09-30 02:26:17Z greg $
|
|
|
|
|
|
\subsection{Reference Guide\label{optparse-reference-guide}}
|
|
|
|
|
|
\subsubsection{Populating the parser\label{optparse-populating-parser}}
|
|
|
|
There are several ways to populate the parser with options. The
|
|
preferred way is by using \code{OptionParser.add{\_}option()}, as shown in
|
|
section~\ref{optparse-tutorial}, the tutorial. \method{add{\_}option()} can be called in one of two
|
|
ways:
|
|
\begin{itemize}
|
|
\item {}
|
|
pass it an 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 Option constructor),
|
|
and it will create the Option instance for you
|
|
|
|
\end{itemize}
|
|
|
|
The other alternative is to pass a list of pre-constructed Option
|
|
instances to the OptionParser constructor, as in:
|
|
\begin{verbatim}
|
|
option_list = [
|
|
make_option("-f", "--filename",
|
|
action="store", type="string", dest="filename"),
|
|
make_option("-q", "--quiet",
|
|
action="store_false", dest="verbose"),
|
|
]
|
|
parser = OptionParser(option_list=option_list)
|
|
\end{verbatim}
|
|
|
|
(\function{make{\_}option()} is a factory function for creating Option instances;
|
|
currently it is an alias for the Option constructor. A future version
|
|
of \module{optparse} may split Option into several classes, and \function{make{\_}option()}
|
|
will pick the right class to instantiate. Do not instantiate Option
|
|
directly.)
|
|
|
|
|
|
\subsubsection{Defining options\label{optparse-defining-options}}
|
|
|
|
Each Option instance represents a set of synonymous command-line option
|
|
strings, e.g. \programopt{-f} and \longprogramopt{file}. You can
|
|
specify any number of short or long option strings, but you must specify
|
|
at least one overall option string.
|
|
|
|
The canonical way to create an Option instance is by calling
|
|
\function{make{\_}option()}, so that is what will be shown here. However, the
|
|
most common and convenient way is to use \code{parser.add{\_}option()}. Note
|
|
that \function{make{\_}option()} and \code{parser.add{\_}option()} have identical call
|
|
signatures:
|
|
\begin{verbatim}
|
|
make_option(opt_str, ..., attr=value, ...)
|
|
parser.add_option(opt_str, ..., attr=value, ...)
|
|
\end{verbatim}
|
|
|
|
To define an option with only a short option string:
|
|
\begin{verbatim}
|
|
make_option("-f", attr=value, ...)
|
|
\end{verbatim}
|
|
|
|
And to define an option with only a long option string:
|
|
\begin{verbatim}
|
|
make_option("--foo", attr=value, ...)
|
|
\end{verbatim}
|
|
|
|
The \code{attr=value} keyword arguments define option attributes,
|
|
i.e. attributes of the Option object. The most important option
|
|
attribute is \member{action}, and it largely determines what other attributes
|
|
are relevant or required. If you pass irrelevant option attributes, or
|
|
fail to pass required ones, \module{optparse} raises an OptionError exception
|
|
explaining your mistake.
|
|
|
|
An options's \emph{action} determines what \module{optparse} does when it encounters
|
|
this option on the command-line. The actions hard-coded into \module{optparse} are:
|
|
\begin{description}
|
|
\item[\code{store}]
|
|
store this option's argument {[}default]
|
|
\item[\code{store{\_}const}]
|
|
store a constant value
|
|
\item[\code{store{\_}true}]
|
|
store a true value
|
|
\item[\code{store{\_}false}]
|
|
store a false value
|
|
\item[\code{append}]
|
|
append this option's argument to a list
|
|
\item[\code{count}]
|
|
increment a counter by one
|
|
\item[\code{callback}]
|
|
call a specified function
|
|
\item[\member{help}]
|
|
print a usage message including all options and the
|
|
documentation for them
|
|
\end{description}
|
|
|
|
(If you don't supply an action, the default is \code{store}. For this
|
|
action, you may also supply \member{type} and \member{dest} option attributes; see
|
|
below.)
|
|
|
|
As you can see, most actions involve storing or updating a value
|
|
somewhere. \module{optparse} always creates an instance of \code{optparse.Values}
|
|
specifically for this purpose; we refer to this instance as \var{options}.
|
|
Option arguments (and various other values) are stored as attributes of
|
|
this object, according to the \member{dest} (destination) option attribute.
|
|
|
|
For example, when you call
|
|
\begin{verbatim}
|
|
parser.parse_args()
|
|
\end{verbatim}
|
|
|
|
one of the first things \module{optparse} does is create the \var{options} object:
|
|
\begin{verbatim}
|
|
options = 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
|
|
\begin{verbatim}
|
|
options.filename = "foo"
|
|
\end{verbatim}
|
|
|
|
The \member{type} and \member{dest} option attributes are almost as important as
|
|
\member{action}, but \member{action} is the only one that makes sense for \emph{all}
|
|
options.
|
|
|
|
|
|
\subsubsection{Standard option actions\label{optparse-standard-option-actions}}
|
|
|
|
The various option actions all have slightly different requirements and
|
|
effects. Most actions have several relevant option attributes which you
|
|
may specify to guide \module{optparse}'s behaviour; a few have required attributes,
|
|
which you must specify for any option using that action.
|
|
\begin{itemize}
|
|
\item {}
|
|
\code{store} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
|
|
|
|
The option must be followed by an argument, which is
|
|
converted to a value according to \member{type} and stored in
|
|
\member{dest}. If \code{nargs} {\textgreater} 1, multiple arguments will be consumed
|
|
from the command line; all will be converted according to
|
|
\member{type} and stored to \member{dest} as a tuple. See the ``Option
|
|
types'' section below.
|
|
|
|
If \code{choices} is supplied (a list or tuple of strings), the type
|
|
defaults to \code{choice}.
|
|
|
|
If \member{type} is not supplied, it defaults to \code{string}.
|
|
|
|
If \member{dest} is not supplied, \module{optparse} derives a destination from the
|
|
first long option string (e.g., \code{"-{}-foo-bar"} implies \code{foo{\_}bar}).
|
|
If there are no long option strings, \module{optparse} derives a destination from
|
|
the first short option string (e.g., \code{"-f"} implies \code{f}).
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
parser.add_option("-f")
|
|
parser.add_option("-p", type="float", nargs=3, dest="point")
|
|
\end{verbatim}
|
|
|
|
As it parses the command line
|
|
\begin{verbatim}
|
|
-f foo.txt -p 1 -3.5 4 -fbar.txt
|
|
\end{verbatim}
|
|
|
|
\module{optparse} will set
|
|
\begin{verbatim}
|
|
options.f = "foo.txt"
|
|
options.point = (1.0, -3.5, 4.0)
|
|
options.f = "bar.txt"
|
|
\end{verbatim}
|
|
|
|
\item {}
|
|
\code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}]
|
|
|
|
The value \code{const} is stored in \member{dest}.
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
parser.add_option("-q", "--quiet",
|
|
action="store_const", const=0, dest="verbose")
|
|
parser.add_option("-v", "--verbose",
|
|
action="store_const", const=1, dest="verbose")
|
|
parser.add_option("--noisy",
|
|
action="store_const", const=2, dest="verbose")
|
|
\end{verbatim}
|
|
|
|
If \code{"-{}-noisy"} is seen, \module{optparse} will set
|
|
\begin{verbatim}
|
|
options.verbose = 2
|
|
\end{verbatim}
|
|
|
|
\item {}
|
|
\code{store{\_}true} {[}relevant: \member{dest}]
|
|
|
|
A special case of \code{store{\_}const} that stores a true value
|
|
to \member{dest}.
|
|
|
|
\item {}
|
|
\code{store{\_}false} {[}relevant: \member{dest}]
|
|
|
|
Like \code{store{\_}true}, but stores a false value.
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
parser.add_option("--clobber", action="store_true", dest="clobber")
|
|
parser.add_option("--no-clobber", action="store_false", dest="clobber")
|
|
\end{verbatim}
|
|
|
|
\item {}
|
|
\code{append} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
|
|
|
|
The option must be followed by an argument, which is appended to the
|
|
list in \member{dest}. If no default value for \member{dest} is supplied, an
|
|
empty list is automatically created when \module{optparse} first encounters this
|
|
option on the command-line. If \code{nargs} {\textgreater} 1, multiple arguments are
|
|
consumed, and a tuple of length \code{nargs} is appended to \member{dest}.
|
|
|
|
The defaults for \member{type} and \member{dest} are the same as for the
|
|
\code{store} action.
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
parser.add_option("-t", "--tracks", action="append", type="int")
|
|
\end{verbatim}
|
|
|
|
If \code{"-t3"} is seen on the command-line, \module{optparse} does the equivalent of:
|
|
\begin{verbatim}
|
|
options.tracks = []
|
|
options.tracks.append(int("3"))
|
|
\end{verbatim}
|
|
|
|
If, a little later on, \code{"-{}-tracks=4"} is seen, it does:
|
|
\begin{verbatim}
|
|
options.tracks.append(int("4"))
|
|
\end{verbatim}
|
|
|
|
\item {}
|
|
\code{count} {[}relevant: \member{dest}]
|
|
|
|
Increment the integer stored at \member{dest}. If no default value is
|
|
supplied, \member{dest} is set to zero before being incremented the first
|
|
time.
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
parser.add_option("-v", action="count", dest="verbosity")
|
|
\end{verbatim}
|
|
|
|
The first time \code{"-v"} is seen on the command line, \module{optparse} does the
|
|
equivalent of:
|
|
\begin{verbatim}
|
|
options.verbosity = 0
|
|
options.verbosity += 1
|
|
\end{verbatim}
|
|
|
|
Every subsequent occurrence of \code{"-v"} results in
|
|
\begin{verbatim}
|
|
options.verbosity += 1
|
|
\end{verbatim}
|
|
|
|
\item {}
|
|
\code{callback} {[}required: \code{callback};
|
|
relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}]
|
|
|
|
Call the function specified by \code{callback}. The signature of
|
|
this function should be
|
|
\begin{verbatim}
|
|
func(option : Option,
|
|
opt : string,
|
|
value : any,
|
|
parser : OptionParser,
|
|
*args, **kwargs)
|
|
\end{verbatim}
|
|
|
|
See section~\ref{optparse-option-callbacks}, Option Callbacks for more detail.
|
|
|
|
\item {}
|
|
\member{help}
|
|
|
|
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 OptionParser's constructor and
|
|
the \member{help} string passed to every option.
|
|
|
|
If no \member{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 \code{optparse.SUPPRESS{\_}HELP}.
|
|
|
|
\module{optparse} automatically adds a \member{help} option to all OptionParsers, so
|
|
you do not normally need to create one.
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
from optparse import OptionParser, SUPPRESS_HELP
|
|
|
|
parser = OptionParser()
|
|
parser.add_option("-h", "--help", action="help"),
|
|
parser.add_option("-v", action="store_true", dest="verbose",
|
|
help="Be moderately verbose")
|
|
parser.add_option("--file", dest="filename",
|
|
help="Input file to read data from"),
|
|
parser.add_option("--secret", help=SUPPRESS_HELP)
|
|
\end{verbatim}
|
|
|
|
If \module{optparse} sees either \code{"-h"} or \code{"-{}-help"} on the command line, it
|
|
will print something like the following help message to stdout
|
|
(assuming \code{sys.argv{[}0]} is \code{"foo.py"}):
|
|
\begin{verbatim}
|
|
usage: foo.py [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)}.
|
|
|
|
\item {}
|
|
\code{version}
|
|
|
|
Prints the version number supplied to the OptionParser to stdout and
|
|
exits. The version number is actually formatted and printed by the
|
|
\code{print{\_}version()} method of OptionParser. Generally only relevant
|
|
if the \code{version} argument is supplied to the OptionParser
|
|
constructor. As with \member{help} options, you will rarely create
|
|
\code{version} options, since \module{optparse} automatically adds them when needed.
|
|
|
|
\end{itemize}
|
|
|
|
|
|
\subsubsection{Standard option types\label{optparse-standard-option-types}}
|
|
|
|
\module{optparse} has six built-in option types: \code{string}, \code{int}, \code{long},
|
|
\code{choice}, \code{float} and \code{complex}. If you need to add new option
|
|
types, 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 \code{int()} to convert them to Python
|
|
integers. If \code{int()} fails, so will \module{optparse}, although with a more
|
|
useful error message. (Internally, \module{optparse} raises OptionValueError;
|
|
OptionParser catches this exception higher up and terminates your
|
|
program with a useful error message.)
|
|
|
|
Likewise, \code{float} arguments are passed to \code{float()} for conversion,
|
|
\code{long} arguments to \code{long()}, and \code{complex} arguments to
|
|
\code{complex()}. Apart from that, they are handled identically to integer
|
|
arguments.
|
|
|
|
\code{choice} options are a subtype of \code{string} options. The \code{choices}
|
|
option attribute (a sequence of strings) defines the set of allowed
|
|
option arguments. \code{optparse.option.check{\_}choice()} compares
|
|
user-supplied option arguments against this master list and raises
|
|
OptionValueError if an invalid string is given.
|
|
|
|
|
|
\subsubsection{Querying and manipulating your option parser\label{optparse-querying-manipulating-option-parser}}
|
|
|
|
Sometimes, it's useful to poke around your option parser and see what's
|
|
there. OptionParser provides a couple of methods to help you out:
|
|
\begin{description}
|
|
\item[\code{has{\_}option(opt{\_}str)}]
|
|
Return true if the OptionParser has an option with
|
|
option string \code{opt{\_}str} (e.g., \code{"-q"} or \code{"-{}-verbose"}).
|
|
\item[\code{get{\_}option(opt{\_}str)}]
|
|
Returns the Option instance with the option string \code{opt{\_}str}, or
|
|
\code{None} if no options have that option string.
|
|
\item[\code{remove{\_}option(opt{\_}str)}]
|
|
If the OptionParser has an option corresponding to \code{opt{\_}str},
|
|
that option is removed. If that option provided any other
|
|
option strings, all of those option strings become invalid.
|
|
|
|
If \code{opt{\_}str} does not occur in any option belonging to this
|
|
OptionParser, raises ValueError.
|
|
\end{description}
|
|
|
|
|
|
\subsubsection{Conflicts between options\label{optparse-conflicts-between-options}}
|
|
|
|
If you're not careful, it's easy to define options with conflicting
|
|
option strings:
|
|
\begin{verbatim}
|
|
parser.add_option("-n", "--dry-run", ...)
|
|
[...]
|
|
parser.add_option("-n", "--noisy", ...)
|
|
\end{verbatim}
|
|
|
|
(This is particularly true if you've defined your own OptionParser
|
|
subclass with some standard options.)
|
|
|
|
Every time you add an option, \module{optparse} checks for conflicts with existing
|
|
options. If it finds any, it invokes the current conflict-handling
|
|
mechanism. You can set the conflict-handling mechanism either in the
|
|
constructor:
|
|
\begin{verbatim}
|
|
parser = OptionParser(..., conflict_handler="...")
|
|
\end{verbatim}
|
|
|
|
or with a separate call:
|
|
\begin{verbatim}
|
|
parser.set_conflict_handler("...")
|
|
\end{verbatim}
|
|
|
|
The available conflict-handling mechanisms are:
|
|
\begin{quote}
|
|
\begin{description}
|
|
\item[\code{error} (default)]
|
|
assume option conflicts are a programming error and raise
|
|
OptionConflictError
|
|
\item[\code{resolve}]
|
|
resolve option conflicts intelligently (see below)
|
|
\end{description}
|
|
\end{quote}
|
|
|
|
As an example, let's define an OptionParser that resolves conflicts
|
|
intelligently and add conflicting options to it:
|
|
\begin{verbatim}
|
|
parser = OptionParser(conflict_handler="resolve")
|
|
parser.add_option("-n", "--dry-run", ..., help="do no harm")
|
|
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 \code{"-n"} option string. Since \code{conflict{\_}handler} is
|
|
\code{"resolve"}, it resolves the situation by removing \code{"-n"} from the
|
|
earlier option's list of option strings. Now \code{"-{}-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:
|
|
\begin{verbatim}
|
|
options:
|
|
--dry-run do no harm
|
|
[...]
|
|
-n, --noisy be noisy
|
|
\end{verbatim}
|
|
|
|
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.
|
|
Carrying on with our existing OptionParser:
|
|
\begin{verbatim}
|
|
parser.add_option("--dry-run", ..., help="new dry-run option")
|
|
\end{verbatim}
|
|
|
|
At this point, the original \programopt{-n/-{}-dry-run} option is no longer
|
|
accessible, so \module{optparse} removes it, leaving this help text:
|
|
\begin{verbatim}
|
|
options:
|
|
[...]
|
|
-n, --noisy be noisy
|
|
--dry-run new dry-run option
|
|
\end{verbatim}
|
|
% $Id: reference.txt 415 2004-09-30 02:26:17Z greg $
|
|
|
|
|
|
\subsection{Option Callbacks\label{optparse-option-callbacks}}
|
|
|
|
When \module{optparse}'s built-in actions and types aren't quite enough for your
|
|
needs, you have two choices: extend \module{optparse} or define a callback option.
|
|
Extending \module{optparse} is more general, but overkill for a lot of simple
|
|
cases. Quite often a simple callback is all you need.
|
|
|
|
There are two steps to defining a callback option:
|
|
\begin{itemize}
|
|
\item {}
|
|
define the option itself using the \code{callback} action
|
|
|
|
\item {}
|
|
write the callback; this is a function (or method) that
|
|
takes at least four arguments, as described below
|
|
|
|
\end{itemize}
|
|
|
|
|
|
\subsubsection{Defining a callback option\label{optparse-defining-callback-option}}
|
|
|
|
As always, the easiest way to define a callback option is by using the
|
|
\code{parser.add{\_}option()} method. Apart from \member{action}, the only option
|
|
attribute you must specify is \code{callback}, the function to call:
|
|
\begin{verbatim}
|
|
parser.add_option("-c", action="callback", callback=my_callback)
|
|
\end{verbatim}
|
|
|
|
\code{callback} is a function (or other callable object), so you must have
|
|
already defined \code{my{\_}callback()} when you create this callback option.
|
|
In this simple case, \module{optparse} doesn't even know if \programopt{-c} takes any
|
|
arguments, which usually means that the option takes no 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 section.
|
|
|
|
\module{optparse} always passes four particular arguments to your callback, and it
|
|
will only pass additional arguments if you specify them via
|
|
\code{callback{\_}args} and \code{callback{\_}kwargs}. Thus, the minimal callback
|
|
function signature is:
|
|
\begin{verbatim}
|
|
def my_callback(option, opt, value, parser):
|
|
\end{verbatim}
|
|
|
|
The four arguments to a callback are described below.
|
|
|
|
There are several other option attributes that you can supply when you
|
|
define a callback option:
|
|
\begin{description}
|
|
\item[\member{type}]
|
|
has its usual meaning: as with the \code{store} or \code{append} actions,
|
|
it instructs \module{optparse} to consume one argument and convert it to
|
|
\member{type}. Rather than storing the converted value(s) anywhere,
|
|
though, \module{optparse} passes it to your callback function.
|
|
\item[\code{nargs}]
|
|
also has its usual meaning: if it is supplied and {\textgreater} 1, \module{optparse} will
|
|
consume \code{nargs} arguments, each of which must be convertible to
|
|
\member{type}. It then passes a tuple of converted values to your
|
|
callback.
|
|
\item[\code{callback{\_}args}]
|
|
a tuple of extra positional arguments to pass to the callback
|
|
\item[\code{callback{\_}kwargs}]
|
|
a dictionary of extra keyword arguments to pass to the callback
|
|
\end{description}
|
|
|
|
|
|
\subsubsection{How callbacks are called\label{optparse-how-callbacks-called}}
|
|
|
|
All callbacks are called as follows:
|
|
\begin{verbatim}
|
|
func(option, opt_str, value, parser, *args, **kwargs)
|
|
\end{verbatim}
|
|
|
|
where
|
|
\begin{description}
|
|
\item[\code{option}]
|
|
is the Option instance that's calling the callback
|
|
\item[\code{opt{\_}str}]
|
|
is the option string seen on the command-line that's triggering the
|
|
callback. (If an abbreviated long option was used, \code{opt{\_}str} will
|
|
be the full, canonical option string{---}e.g. if the user puts
|
|
\code{"-{}-foo"} on the command-line as an abbreviation for
|
|
\code{"-{}-foobar"}, then \code{opt{\_}str} will be \code{"-{}-foobar"}.)
|
|
\item[\code{value}]
|
|
is the argument to this option seen on the command-line. \module{optparse} will
|
|
only expect an argument if \member{type} is set; the type of \code{value}
|
|
will be the type implied by the option's type. If \member{type} for this
|
|
option is \code{None} (no argument expected), then \code{value} will be
|
|
\code{None}. If \code{nargs} {\textgreater} 1, \code{value} will be a tuple of values of
|
|
the appropriate type.
|
|
\item[\code{parser}]
|
|
is the OptionParser instance driving the whole thing, mainly
|
|
useful because you can access some other interesting data through
|
|
its instance attributes:
|
|
\begin{description}
|
|
\item[\code{parser.largs}]
|
|
the current list of leftover arguments, ie. arguments that have
|
|
been consumed but are neither options nor option arguments.
|
|
Feel free to modify \code{parser.largs}, e.g. by adding more
|
|
arguments to it. (This list will become \var{args}, the second
|
|
return value of \method{parse{\_}args()}.)
|
|
\item[\code{parser.rargs}]
|
|
the current list of remaining arguments, ie. with \code{opt{\_}str} and
|
|
\code{value} (if applicable) removed, and only the arguments
|
|
following them still there. Feel free to modify
|
|
\code{parser.rargs}, e.g. by consuming more arguments.
|
|
\item[\code{parser.values}]
|
|
the object where option values are by default stored (an
|
|
instance of optparse.OptionValues). This 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 or modify the value(s) of any options already
|
|
encountered on the command-line.
|
|
\end{description}
|
|
\item[\code{args}]
|
|
is a tuple of arbitrary positional arguments supplied via the
|
|
\code{callback{\_}args} option attribute.
|
|
\item[\code{kwargs}]
|
|
is a dictionary of arbitrary keyword arguments supplied via
|
|
\code{callback{\_}kwargs}.
|
|
\end{description}
|
|
|
|
|
|
\subsubsection{Raising errors in a callback\label{optparse-raising-errors-in-callback}}
|
|
|
|
The callback function should raise 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{Callback example 1: trivial callback\label{optparse-callback-example-1}}
|
|
|
|
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_str, value, parser):
|
|
parser.saw_foo = True
|
|
|
|
parser.add_option("--foo", action="callback", callback=record_foo_seen)
|
|
\end{verbatim}
|
|
|
|
Of course, you could do that with the \code{store{\_}true} action.
|
|
|
|
|
|
\subsubsection{Callback example 2: check option order\label{optparse-callback-example-2}}
|
|
|
|
Here's a slightly more interesting example: record the fact that
|
|
\code{"-a"} is seen, but blow up if it comes after \code{"-b"} in the
|
|
command-line.
|
|
\begin{verbatim}
|
|
def check_order(option, opt_str, 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}
|
|
|
|
|
|
\subsubsection{Callback example 3: check option order (generalized)\label{optparse-callback-example-3}}
|
|
|
|
If you want to re-use this callback for several similar options (set a
|
|
flag, but blow up if \code{"-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_str, value, parser):
|
|
if parser.values.b:
|
|
raise OptionValueError("can't use %s after -b" % opt_str)
|
|
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}
|
|
|
|
|
|
\subsubsection{Callback example 4: check arbitrary condition\label{optparse-callback-example-4}}
|
|
|
|
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_str, value, parser):
|
|
if is_moon_full():
|
|
raise OptionValueError("%s option invalid when moon is full"
|
|
% opt_str)
|
|
setattr(parser.values, option.dest, 1)
|
|
[...]
|
|
parser.add_option("--foo",
|
|
action="callback", callback=check_moon, dest="foo")
|
|
\end{verbatim}
|
|
|
|
(The definition of \code{is{\_}moon{\_}full()} is left as an exercise for the
|
|
reader.)
|
|
|
|
|
|
\subsubsection{Callback example 5: fixed arguments\label{optparse-callback-example-5}}
|
|
|
|
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 \code{store} or \code{append}
|
|
option: if you define \member{type}, then the option takes one argument that
|
|
must be convertible to that type; if you further define \code{nargs}, then
|
|
the option takes \code{nargs} arguments.
|
|
|
|
Here's an example that just emulates the standard \code{store} action:
|
|
\begin{verbatim}
|
|
def store_value(option, opt_str, 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.)
|
|
|
|
|
|
\subsubsection{Callback example 6: variable arguments\label{optparse-callback-example-6}}
|
|
|
|
Things get hairy when you want an option to take a variable number of
|
|
arguments. For this case, you must write a callback, as \module{optparse} doesn't
|
|
provide any built-in capabilities for it. And you have to deal with
|
|
certain intricacies of conventional \UNIX{} command-line parsing that \module{optparse}
|
|
normally handles for you. In particular, callbacks should implement
|
|
the conventional rules for bare \code{"-{}-"} and \code{"-"} arguments:
|
|
\begin{itemize}
|
|
\item {}
|
|
either \code{"-{}-"} or \code{"-"} can be option arguments
|
|
|
|
\item {}
|
|
bare \code{"-{}-"} (if not the argument to some option): halt command-line
|
|
processing and discard the \code{"-{}-"}
|
|
|
|
\item {}
|
|
bare \code{"-"} (if not the argument to some option): halt command-line
|
|
processing but keep the \code{"-"} (append it to \code{parser.largs})
|
|
|
|
\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 vararg_callback(option, opt_str, 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 \code{"-c"} will be interpreted as
|
|
further options (probably causing an error), rather than as arguments to
|
|
\code{"-c"}. Fixing this is left as an exercise for the reader.
|
|
% $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $
|
|
|