Major overhaul to reflect Optik 1.5. Section references currently broken.
diff --git a/Doc/lib/liboptparse.tex b/Doc/lib/liboptparse.tex
index c99d235..bc3186f 100644
--- a/Doc/lib/liboptparse.tex
+++ b/Doc/lib/liboptparse.tex
@@ -1,27 +1,23 @@
-\section{\module{optparse} ---
- Powerful parser for command line options.}
-
+\section{\module{optparse} --- More powerful command line option parser}
\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.}
-
+\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).
-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.
+\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 \module{optparse} to add some command-line
-options to a simple script:
-
+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")
@@ -29,347 +25,361 @@
action="store_false", dest="verbose", default=True,
help="don't print status messages to stdout")
-options, args = parser.parse_args()
+(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:
-
+``usual thing'' on the command-line, for example:
\begin{verbatim}
-$ <yourscript> -f outfile --quiet
-$ <yourscript> -qfoutfile
-$ <yourscript> --file=outfile -q
-$ <yourscript> --quiet --file outfile
+<yourscript> --file=outfile -q
\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
+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> -h
-$ <yourscript> --help
+<yourscript> -f outfile --quiet
+<yourscript> --quiet --file outfile
+<yourscript> -q -foutfile
+<yourscript> -qfoutfile
\end{verbatim}
-and \module{optparse} will print out a brief summary of your script's
+
+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
- -fFILE, --file=FILE write report to FILE
- -q, --quiet don't print status messages to stdout
+ -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}
-That's just a taste of the flexibility \module{optparse} gives you in
-parsing your command-line.
+where the value of \emph{yourscript} is determined at runtime (normally
+from \code{sys.argv{[}0]}).
+% $Id$
-\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.
+\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''.
-First, we need to establish some terminology.
+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}.
-\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:
-
+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}.
+\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}
-\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}
+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 the option is.
-Often, option arguments may also be included in the same argument as
-the option, e.g. :
-
+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"]
+-f foo
+--file foo
\end{verbatim}
-may be equivalent to:
-
+or included in the same argument:
\begin{verbatim}
- ["-ffoo"]
+-ffoo
+--file=foo
\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}
+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
+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}
+\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
+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.
+\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-options}}
+
+\subsubsection{What are options for?\label{optparse-what-are-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 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.)
+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. (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}.)
+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.
-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:
-
+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
+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.
+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-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.
+\subsubsection{What are positional arguments for?\label{optparse-what-are-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
+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.
+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
+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.
+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$
-\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.
+\subsection{Tutorial\label{optparse-tutorial}}
-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}:
+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
-\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}:
+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}
-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}.
+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.
-\subsubsection{The \emph{store} action%
- \label{optparse-store-action}}
+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.
-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.
+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}
-For example, let's fill in the ``...'' of that last option:
+(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{Option actions\label{optparse-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-the-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:
-
+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)
+(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 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"}.
-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:
-
+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}
-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).
+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"])
+(options, args) = parser.parse_args(["-n42"])
print options.num
\end{verbatim}
-This prints \code{42}.
+will print \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:
-
+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 \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}.
+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}.
-Adding types is fairly easy; please refer to
-section~\ref{optparse-adding-types}, ``Adding new types.''
+\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{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}:
+\subsubsection{Handling flag (boolean) options\label{optparse-handling-flag-(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")
@@ -377,61 +387,86 @@
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.)
+default values{---}see section~\ref{optparse-default-values}, Default values, 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}.
+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{Setting default values\label{optparse-setting-default-values}}
+
+\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 the section~\ref{None}, Reference Guide and section~\ref{None}, Option Callbacks
+documents.
+
+
+\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}. 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.
+``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 \member{verbose} to \code{True} unless
-\programopt{-q} is seen, then we can do this:
-
+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}
-Oddly enough, this is exactly equivalent:
-
+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}
-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
+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}}
-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:
-
+\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)
@@ -441,317 +476,314 @@
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",
+parser.add_option("-f", "--filename",
metavar="FILE", help="write output to FILE"),
parser.add_option("-m", "--mode",
default="intermediate",
- help="interaction mode: one of 'novice', "
- "'intermediate' [default], 'expert'")
+ help="interaction mode: novice, intermediate, "
+ "or expert [default: %default]")
\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:
-
+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)
- -fFILE, --file=FILE write output to FILE
- -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
- [default], 'expert'
+ -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}
-There's a lot going on here to help \module{optparse} generate the
-best possible help message:
+(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:
-
+\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.
+\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.
+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 {}
+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
+\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
+-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 \var{filename} option explicitly sets
-\code{metavar="FILE"}, resulting in this automatically-generated
-option description:
-
+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}
--fFILE, --file=FILE
+-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 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.
+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}
-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:
+\subsubsection{Printing a version string\label{optparse-printing-a-version-string}}
-\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}:
-
+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}
-\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.
+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 /usr/bin/foo, a user might do:
-
+For example, if your script is called \code{/usr/bin/foo}:
\begin{verbatim}
$ /usr/bin/foo --version
foo 1.0
-\end{verbatim} % $ (avoid confusing emacs)
+\end{verbatim}
+
\subsubsection{Error-handling\label{optparse-error-handling}}
-The one thing you need to know for basic usage is how
-\module{optparse} behaves when it encounters an error on the
-command-line---e.g. \programopt{-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.
+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.
-If you don't like this, subclass \class{OptionParser} and override the
-\method{error()} method. See section~\ref{optparse-extending},
-``Extending \module{optparse}.''
+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}
-\subsubsection{Putting it all together\label{optparse-basic-summary}}
+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.
-Here's what \module{optparse}-based scripts typically look like:
+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 [-f] [-v] [-q] firstarg secondarg"
+ usage = "usage: %prog [options] arg"
parser = OptionParser(usage)
- parser.add_option("-f", "--file", type="string", dest="filename",
+ 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) != 2:
+ [...]
+ (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}
+% $Id$
-\subsection{Advanced Usage\label{optparse-advanced-usage}}
-\subsubsection{Creating and populating the
- parser\label{optparse-creating-the-parser}}
+\subsection{Reference Guide\label{optparse-reference-guide}}
-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:
+\subsubsection{Populating the parser\label{optparse-populating-the-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{None}, the tutorial section. \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}
-from optparse import OptionParser, make_option
-[...]
-parser = OptionParser(option_list=[
+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")]
+ 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:
+(\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.)
-\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.
+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", ...)
+make_option("-f", attr=value, ...)
\end{verbatim}
And to define an option with only a long option string:
-
\begin{verbatim}
-make_option("--foo", ...)
+make_option("--foo", attr=value, ...)
\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 \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.
-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:
+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}
-\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
+(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 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()}.
+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:
-
+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:
-
+one of the first things \module{optparse} does is create the \var{options} object:
\begin{verbatim}
-values = Values()
+options = Values()
\end{verbatim}
-If one of the options in this parser is defined with:
-
+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
@@ -759,174 +791,157 @@
--file foo
\end{verbatim}
-then \module{optparse}, on seeing the \programopt{-f} or
-\longprogramopt{file} option, will do the equivalent of this:
-
+then \module{optparse}, on seeing the \programopt{-f} or \longprogramopt{file} option, will do the
+equivalent of
\begin{verbatim}
- values.filename = "foo"
+options.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.
+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{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.
+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}]
-\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 \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.
-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 \code{choices} is supplied (a list or tuple of strings), the type
+defaults to \code{choice}.
-If \var{choices} (a sequence of strings) is supplied, the type
-defaults to ``choice''.
+If \member{type} is not supplied, it defaults to \code{string}.
-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}).
+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}
-make_option("-f")
-make_option("-p", type="float", nargs=3, dest="point")
+parser.add_option("-f")
+parser.add_option("-p", type="float", nargs=3, dest="point")
\end{verbatim}
-Given the following command line:
-
+As it parses the command line
\begin{verbatim}
-f foo.txt -p 1 -3.5 4 -fbar.txt
\end{verbatim}
-\module{optparse} will set:
-
+\module{optparse} will set
\begin{verbatim}
-values.f = "bar.txt"
-values.point = (1.0, -3.5, 4.0)
+options.f = "foo.txt"
+options.point = (1.0, -3.5, 4.0)
+options.f = "bar.txt"
\end{verbatim}
-(Actually, \member{values.f} will be set twice, but only the second
-time is visible in the end.)
+\item {}
+\code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}]
-\term{store_const} [required: \var{const}, \var{dest}]
-
-The \var{const} value supplied to the \class{Option} constructor is
-stored in \var{dest}.
+The value \code{const} is stored in \member{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"),
+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 \longprogramopt{noisy} is seen, \module{optparse} will set:
-
+If \code{"-{}-noisy"} is seen, \module{optparse} will set
\begin{verbatim}
-values.verbose = 2
+options.verbose = 2
\end{verbatim}
-\term{store_true} [required: \var{dest}]
+\item {}
+\code{store{\_}true} {[}relevant: \member{dest}]
-A special case of ``store_const'' that stores \code{True} to \var{dest}.
+A special case of \code{store{\_}const} that stores a true value
+to \member{dest}.
-\term{store_false} [required: \var{dest}]
+\item {}
+\code{store{\_}false} {[}relevant: \member{dest}]
-Like ``store_true'', but stores \code{False}
+Like \code{store{\_}true}, but stores a false value.
Example:
-
\begin{verbatim}
-make_option(None, "--clobber", action="store_true", dest="clobber")
-make_option(None, "--no-clobber", action="store_false", dest="clobber")
+parser.add_option("--clobber", action="store_true", dest="clobber")
+parser.add_option("--no-clobber", action="store_false", dest="clobber")
\end{verbatim}
-\term{append} [relevant: \var{type}, \var{dest}, \var{nargs}, \var{choices}]
+\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 \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}.
+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 \var{type} and \var{dest} are the same as for the
-``store'' action.
+The defaults for \member{type} and \member{dest} are the same as for the
+\code{store} action.
Example:
-
\begin{verbatim}
-make_option("-t", "--tracks", action="append", type="int")
+parser.add_option("-t", "--tracks", action="append", type="int")
\end{verbatim}
-If \programopt{-t3} is seen on the command-line, \module{optparse} does the equivalent of:
-
+If \code{"-t3"} is seen on the command-line, \module{optparse} does the equivalent of:
\begin{verbatim}
-values.tracks = []
-values.tracks.append(int("3"))
+options.tracks = []
+options.tracks.append(int("3"))
\end{verbatim}
-If, a little later on, \longprogramopt{tracks=4} is seen, it does:
-
+If, a little later on, \code{"-{}-tracks=4"} is seen, it does:
\begin{verbatim}
-values.tracks.append(int("4"))
+options.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}.
+\item {}
+\code{count} {[}relevant: \member{dest}]
-\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).
+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}
-make_option("-v", action="count", dest="verbosity")
+parser.add_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:
-
+The first time \code{"-v"} is seen on the command line, \module{optparse} does the
+equivalent of:
\begin{verbatim}
-values.verbosity = 0
-values.verbosity += 1
+options.verbosity = 0
+options.verbosity += 1
\end{verbatim}
-Every subsequent occurrence of \programopt{-v} results in:
-
+Every subsequent occurrence of \code{"-v"} results in
\begin{verbatim}
-values.verbosity += 1
+options.verbosity += 1
\end{verbatim}
-\term{callback} [required: \var{callback};
- relevant: \var{type}, \var{nargs}, \var{callback_args},
- \var{callback_kwargs}]
+\item {}
+\code{callback} {[}required: \code{callback};
+relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}]
-Call the function specified by \var{callback}. The signature of
-this function should be:
-
+Call the function specified by \code{callback}. The signature of
+this function should be
\begin{verbatim}
func(option : Option,
opt : string,
@@ -935,42 +950,41 @@
*args, **kwargs)
\end{verbatim}
-Callback options are covered in detail in
-section~\ref{optparse-callback-options}, ``Callback Options.''
+See section~\ref{None}, Option Callbacks for more detail.
-\term{help} [required: none]
+\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 \class{OptionParser}'s constructor and the \var{help}
-string passed to every option.
+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 \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}.
+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 Option, OptionParser, SUPPRESS_HELP
+from optparse import 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)
-])
+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 \programopt{-h} or
-\longprogramopt{help} on the command line, it will print something
-like the following help message to stdout:
-
+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: <yourscript> [options]
+usage: foo.py [options]
options:
-h, --help Show this help message and exit
@@ -981,431 +995,405 @@
After printing the help message, \module{optparse} terminates your process
with \code{sys.exit(0)}.
-\term{version} [required: none]
+\item {}
+\code{version}
-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}
+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{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}.''
+\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.
+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.
+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, 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.
+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.
-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.
+\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-and-manipulating}}
+
+\subsubsection{Querying and manipulating your option parser\label{optparse-querying-and-manipulating-your-option-parser}}
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:
+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.
-\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}
+If \code{opt{\_}str} does not occur in any option belonging to this
+OptionParser, raises ValueError.
+\end{description}
-\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.
+\subsubsection{Conflicts between options\label{optparse-conflicts-between-options}}
- 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:
-
+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 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.
+(This is particularly true if you've defined your own OptionParser
+subclass with some standard options.)
-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:
-
+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="resolve")
+parser = OptionParser(..., conflict_handler="...")
\end{verbatim}
-or via the \method{set_conflict_handler()} method.
+or with a separate call:
+\begin{verbatim}
+parser.set_conflict_handler("...")
+\end{verbatim}
-The default conflict-handling mechanism is \code{error}.
+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}
-Here's an example: first, define an \class{OptionParser} set to
-resolve conflicts intelligently:
-
+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}
-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.:
-
+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 original dry-run option
- ...
+ --dry-run do no harm
+ [...]
-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}:
-
+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 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:
-
+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$
-\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).
+\subsection{Option Callbacks\label{optparse-option-callbacks}}
-\subsubsection{Defining a callback option\label{optparse-defining-callback-option}}
+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.
-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:
+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-a-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", callback=my_callback)
+parser.add_option("-c", action="callback", 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.
+\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 an option attribute:
+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}
-\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}}
+\subsubsection{How callbacks are called\label{optparse-how-callbacks-are-called}}
All callbacks are called as follows:
-
\begin{verbatim}
-func(option, opt, value, parser, *args, **kwargs)
+func(option, opt_str, value, parser, *args, **kwargs)
\end{verbatim}
where
-
-\begin{definitions}
-\term{option}
-is the \class{Option} instance that's calling the callback.
-
-\term{opt}
+\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, \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}
+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[\var{args}]
is a tuple of arbitrary positional arguments supplied via the
-\var{callback}_args option attribute.
-
-\term{kwargs}
+\code{callback{\_}args} option attribute.
+\item[\code{kwargs}]
is a dictionary of arbitrary keyword arguments supplied via
-\var{callback_kwargs}.
-\end{definitions}
+\code{callback{\_}kwargs}.
+\end{description}
-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-error-handling}}
-\subsubsection{Error handling\label{optparse-callback-error-handling}}
+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.
-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}}
+\subsubsection{Callback example 1: trivial callback\label{optparse-callback-example-1:-trivial-callback}}
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
+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 ``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.
+Of course, you could do that with the \code{store{\_}true} action.
+
+\subsubsection{Callback example 2: check option order\label{optparse-callback-example-2:-check-option-order}}
+
+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, value, parser):
+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}
-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.
+\subsubsection{Callback example 3: check option order (generalized)\label{optparse-callback-example-3:-check-option-order-(generalized)}}
+
+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, value, parser):
+def check_order(option, opt_str, value, parser):
if parser.values.b:
- raise OptionValueError("can't use %s after -b" % opt)
+ 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}
-Of course, you could put any condition in there---you're not limited
+
+\subsubsection{Callback example 4: check arbitrary condition\label{optparse-callback-example-4:-check-arbitrary-condition}}
+
+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)
+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_full_moon()} is left as an exercise for the
+(The definition of \code{is{\_}moon{\_}full()} is left as an exercise for the
reader.)
-\strong{Fixed arguments}
+
+\subsubsection{Callback example 5: fixed arguments\label{optparse-callback-example-5:-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.
+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 ``store'' action:
-
+Here's an example that just emulates the standard \code{store} action:
\begin{verbatim}
-def store_value(option, opt, value, parser):
+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.
-Use your imagination!)
+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.)
-\strong{Variable arguments}
+
+\subsubsection{Callback example 6: variable arguments\label{optparse-callback-example-6:-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:
-
+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 bare \longprogramopt{}, if not the argument to some option,
-causes command-line processing to halt and the \longprogramopt{}
-itself is lost.
+\item {}
+either \code{"-{}-"} or \code{"-"} can be option arguments
-\item bare \programopt{-} similarly causes command-line processing to
-halt, but the \programopt{-} itself is kept.
+\item {}
+bare \code{"-{}-"} (if not the argument to some option): halt command-line
+processing and discard the \code{"-{}-"}
-\item either \longprogramopt{} or \programopt{-} can be option
-arguments.
+\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).
+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):
+def vararg_callback(option, opt_str, value, parser):
assert value is None
done = 0
value = []
@@ -1426,290 +1414,14 @@
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.
+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$
-\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}