[Python-checkins]
python/dist/src/Doc/lib liboptparse.tex, 1.18.2.1, 1.18.2.2
gward at users.sourceforge.net
gward at users.sourceforge.net
Sat Mar 19 17:28:39 CET 2005
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv14925/lib
Modified Files:
Tag: release24-maint
liboptparse.tex
Log Message:
Beef up optparse reference docs -- now much closer to documenting the
full API of Optik 1.5a2 (which is what's included with Python 2.4.x).
Closes SF #1099324, partially addresses SF #993601.
Index: liboptparse.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/liboptparse.tex,v
retrieving revision 1.18.2.1
retrieving revision 1.18.2.2
diff -u -d -r1.18.2.1 -r1.18.2.2
--- liboptparse.tex 31 Dec 2004 01:08:17 -0000 1.18.2.1
+++ liboptparse.tex 19 Mar 2005 16:28:37 -0000 1.18.2.2
@@ -35,9 +35,9 @@
\end{verbatim}
As it parses the command line, \code{optparse} sets attributes of the
-\var{options} object returned by \method{parse{\_}args()} based on user-supplied
+\code{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
+command line, \code{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
@@ -287,12 +287,12 @@
\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{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then
+\code{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
+\code{args}, the list of positional arguments leftover after parsing
options
\end{itemize}
@@ -309,7 +309,7 @@
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}.
+attribute of \code{options}.
If you don't specify an option action, \module{optparse} defaults to \code{store}.
@@ -333,8 +333,8 @@
\end{verbatim}
When \module{optparse} sees the option string \code{"-f"}, it consumes the next
-argument, \code{"foo.txt"}, and stores it in \var{options.filename}. So,
-after this call to \method{parse{\_}args()}, \var{options.filename} is
+argument, \code{"foo.txt"}, and stores it in \code{options.filename}. So,
+after this call to \method{parse{\_}args()}, \code{options.filename} is
\code{"foo.txt"}.
Some other option types supported by \module{optparse} are \code{int} and \code{float}.
@@ -379,7 +379,7 @@
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"}:
+\code{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")
@@ -421,7 +421,7 @@
destination, which is assigned before the command line is parsed.
First, consider the verbose/quiet example. If we want \module{optparse} to set
-\var{verbose} to \code{True} unless \code{"-q"} is seen, then we can do this:
+\code{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")
@@ -441,7 +441,7 @@
parser.add_option("-q", action="store_false", dest="verbose", default=True)
\end{verbatim}
-Again, the default value for \var{verbose} will be \code{True}: the last
+Again, the default value for \code{verbose} will be \code{True}: the last
default value supplied for any particular destination is the one that
counts.
@@ -566,7 +566,7 @@
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
\end{verbatim}
-Note that \code{"{\%}prog"} is expanded just like it is in \var{usage}. Apart
+Note that \code{"{\%}prog"} is expanded just like it is in \code{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
@@ -580,7 +580,7 @@
\end{verbatim}
-\subsubsection{How \module{optparse} handles errors\label{optparse-how-optik-handles-errors}}
+\subsubsection{How \module{optparse} handles errors\label{optparse-how-optparse-handles-errors}}
There are two broad classes of errors that \module{optparse} has to worry about:
programmer errors and user errors. Programmer errors are usually
@@ -665,6 +665,60 @@
\subsection{Reference Guide\label{optparse-reference-guide}}
+\subsubsection{Creating the parser\label{optparse-creating-parser}}
+
+The first step in using \module{optparse} is to create an OptionParser instance:
+\begin{verbatim}
+parser = OptionParser(...)
+\end{verbatim}
+
+The OptionParser constructor has no required arguments, but a number of
+optional keyword arguments. You should always pass them as keyword
+arguments, i.e. do not rely on the order in which the arguments are
+declared.
+\begin{quote}
+\begin{description}
+\item[\code{usage} (default: \code{"{\%}prog {[}options]"})]
+The usage summary to print when your program is run incorrectly or
+with a help option. When \module{optparse} prints the usage string, it expands
+\code{{\%}prog} to \code{os.path.basename(sys.argv{[}0])} (or to \code{prog} if
+you passed that keyword argument). To suppress a usage message,
+pass the special value \code{optparse.SUPPRESS{\_}USAGE}.
+\item[\code{option{\_}list} (default: \code{{[}]})]
+A list of Option objects to populate the parser with. The options
+in \code{option{\_}list} are added after any options in
+\code{standard{\_}option{\_}list} (a class attribute that may be set by
+OptionParser subclasses), but before any version or help options.
+Deprecated; use \method{add{\_}option()} after creating the parser instead.
+\item[\code{option{\_}class} (default: optparse.Option)]
+Class to use when adding options to the parser in \method{add{\_}option()}.
+\item[\code{version} (default: \code{None})]
+A version string to print when the user supplies a version option.
+If you supply a true value for \code{version}, \module{optparse} automatically adds
+a version option with the single option string \code{"-{}-version"}. The
+substring \code{"{\%}prog"} is expanded the same as for \code{usage}.
+\item[\code{conflict{\_}handler} (default: \code{"error"})]
+Specifies what to do when options with conflicting option strings
+are added to the parser; see section~\ref{optparse-conflicts-between-options}, Conflicts between options.
+\item[\code{description} (default: \code{None})]
+A paragraph of text giving a brief overview of your program. \module{optparse}
+reformats this paragraph to fit the current terminal width and
+prints it when the user requests help (after \code{usage}, but before
+the list of options).
+\item[\code{formatter} (default: a new IndentedHelpFormatter)]
+An instance of optparse.HelpFormatter that will be used for
+printing help text. \module{optparse} provides two concrete classes for this
+purpose: IndentedHelpFormatter and TitledHelpFormatter.
+\item[\code{add{\_}help{\_}option} (default: \code{True})]
+If true, \module{optparse} will add a help option (with option strings \code{"-h"}
+and \code{"-{}-help"}) to the parser.
+\item[\code{prog}]
+The string to use when expanding \code{"{\%}prog"} in \code{usage} and
+\code{version} instead of \code{os.path.basename(sys.argv{[}0])}.
+\end{description}
+\end{quote}
+
+
\subsubsection{Populating the parser\label{optparse-populating-parser}}
There are several ways to populate the parser with options. The
@@ -708,38 +762,34 @@
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:
+The canonical way to create an Option instance is with the
+\method{add{\_}option()} method of \class{OptionParser}:
\begin{verbatim}
-make_option(opt_str, ..., attr=value, ...)
-parser.add_option(opt_str, ..., attr=value, ...)
+parser.add_option(opt_str[, ...], attr=value, ...)
\end{verbatim}
To define an option with only a short option string:
\begin{verbatim}
-make_option("-f", attr=value, ...)
+parser.add_option("-f", attr=value, ...)
\end{verbatim}
And to define an option with only a long option string:
\begin{verbatim}
-make_option("--foo", attr=value, ...)
+parser.add_option("--foo", attr=value, ...)
\end{verbatim}
-The \code{attr=value} keyword arguments define option attributes,
-i.e. attributes of the Option object. The most important option
-attribute is \member{action}, and it largely determines what other attributes
-are relevant or required. If you pass irrelevant option attributes, or
-fail to pass required ones, \module{optparse} raises an OptionError exception
-explaining your mistake.
+The keyword arguments define attributes of the new Option object. The
+most important option attribute is \member{action}, and it largely determines
+which other attributes are relevant or required. If you pass irrelevant
+option attributes, or fail to pass required ones, \module{optparse} raises an
+OptionError exception explaining your mistake.
-An options's \emph{action} determines what \module{optparse} does when it encounters
-this option on the command-line. The actions hard-coded into \module{optparse} are:
+An options's \emph{action} determines what \module{optparse} does when it encounters this
+option on the command-line. The standard option actions hard-coded into
+\module{optparse} are:
\begin{description}
\item[\code{store}]
-store this option's argument {[}default]
+store this option's argument (default)
\item[\code{store{\_}const}]
store a constant value
\item[\code{store{\_}true}]
@@ -762,24 +812,25 @@
below.)
As you can see, most actions involve storing or updating a value
-somewhere. \module{optparse} always creates an instance of \code{optparse.Values}
-specifically for this purpose; we refer to this instance as \var{options}.
-Option arguments (and various other values) are stored as attributes of
-this object, according to the \member{dest} (destination) option attribute.
+somewhere. \module{optparse} always creates a special object for this,
+conventionally called \code{options} (it happens to be an instance of
+\code{optparse.Values}). Option arguments (and various other values) are
+stored as attributes of this object, according to the \member{dest}
+(destination) option attribute.
For example, when you call
\begin{verbatim}
parser.parse_args()
\end{verbatim}
-one of the first things \module{optparse} does is create the \var{options} object:
+one of the first things \module{optparse} does is create the \code{options} object:
\begin{verbatim}
options = Values()
\end{verbatim}
If one of the options in this parser is defined with
\begin{verbatim}
-make_option("-f", "--file", action="store", type="string", dest="filename")
+parser.add_option("-f", "--file", action="store", type="string", dest="filename")
\end{verbatim}
and the command-line being parsed includes any of the following:
@@ -790,8 +841,7 @@
--file foo
\end{verbatim}
-then \module{optparse}, on seeing the \programopt{-f} or \longprogramopt{file} option, will do the
-equivalent of
+then \module{optparse}, on seeing this option, will do the equivalent of
\begin{verbatim}
options.filename = "foo"
\end{verbatim}
@@ -939,14 +989,9 @@
\code{callback} {[}required: \code{callback};
relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}]
-Call the function specified by \code{callback}. The signature of
-this function should be
+Call the function specified by \code{callback}, which is called as
\begin{verbatim}
-func(option : Option,
- opt : string,
- value : any,
- parser : OptionParser,
- *args, **kwargs)
+func(option, opt_str, value, parser, *args, **kwargs)
\end{verbatim}
See section~\ref{optparse-option-callbacks}, Option Callbacks for more detail.
@@ -956,7 +1001,7 @@
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 \code{usage} string passed to OptionParser's constructor and
the \member{help} string passed to every option.
If no \member{help} string is supplied for an option, it will still be
@@ -1030,11 +1075,49 @@
\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
+option arguments. \code{optparse.check{\_}choice()} compares
user-supplied option arguments against this master list and raises
OptionValueError if an invalid string is given.
+\subsubsection{Parsing arguments\label{optparse-parsing-arguments}}
+
+The whole point of creating and populating an OptionParser is to call
+its \method{parse{\_}args()} method:
+\begin{verbatim}
+(options, args) = parser.parse_args(args=None, options=None)
+\end{verbatim}
+
+where the input parameters are
+\begin{description}
+\item[\code{args}]
+the list of arguments to process (\code{sys.argv{[}1:]} by default)
+\item[\code{options}]
+object to store option arguments in (a new instance of
+optparse.Values by default)
+\end{description}
+
+and the return values are
+\begin{description}
+\item[\code{options}]
+the same object as was passed in as \code{options}, or the new
+optparse.Values instance created by \module{optparse}
+\item[\code{args}]
+the leftover positional arguments after all options have been
+processed
+\end{description}
+
+The most common usage is to supply neither keyword argument. If you
+supply a \code{values} object, it will be repeatedly modified with a
+\code{setattr()} call for every option argument written to an option
+destination, and finally returned by \method{parse{\_}args()}.
+
+If \method{parse{\_}args()} encounters any errors in the argument list, it calls
+the OptionParser's \method{error()} method with an appropriate end-user error
+message. This ultimately terminates your process with an exit status of
+2 (the traditional \UNIX{} exit status for command-line errors).
+
+
\subsubsection{Querying and manipulating your option parser\label{optparse-querying-manipulating-option-parser}}
Sometimes, it's useful to poke around your option parser and see what's
@@ -1050,7 +1133,6 @@
If the OptionParser has an option corresponding to \code{opt{\_}str},
that option is removed. If that option provided any other
option strings, all of those option strings become invalid.
-
If \code{opt{\_}str} does not occur in any option belonging to this
OptionParser, raises ValueError.
\end{description}
@@ -1074,15 +1156,15 @@
mechanism. You can set the conflict-handling mechanism either in the
constructor:
\begin{verbatim}
-parser = OptionParser(..., conflict_handler="...")
+parser = OptionParser(..., conflict_handler=handler)
\end{verbatim}
or with a separate call:
\begin{verbatim}
-parser.set_conflict_handler("...")
+parser.set_conflict_handler(handler)
\end{verbatim}
-The available conflict-handling mechanisms are:
+The available conflict handlers are:
\begin{quote}
\begin{description}
\item[\code{error} (default)]
@@ -1131,6 +1213,67 @@
-n, --noisy be noisy
--dry-run new dry-run option
\end{verbatim}
+
+
+\subsubsection{Other methods\label{optparse-other-methods}}
+
+OptionParser supports several other public methods:
+\begin{itemize}
+\item {}
+\code{set{\_}usage(usage)}
+
+Set the usage string according to the rules described above for the
+\code{usage} constructor keyword argument. Passing \code{None} sets the
+default usage string; use \code{SUPPRESS{\_}USAGE} to suppress a usage
+message.
+
+\item {}
+\code{enable{\_}interspersed{\_}args()}, \code{disable{\_}interspersed{\_}args()}
+
+Enable/disable positional arguments interspersed with options, similar
+to GNU getopt (enabled by default). For example, if \code{"-a"} and
+\code{"-b"} are both simple options that take no arguments, \module{optparse}
+normally accepts this syntax:
+\begin{verbatim}
+prog -a arg1 -b arg2
+\end{verbatim}
+
+and treats it as equivalent to
+\begin{verbatim}
+prog -a -b arg1 arg2
+\end{verbatim}
+
+To disable this feature, call \code{disable{\_}interspersed{\_}args()}. This
+restores traditional \UNIX{} syntax, where option parsing stops with the
+first non-option argument.
+
+\item {}
+\code{set{\_}defaults(dest=value, ...)}
+
+Set default values for several option destinations at once. Using
+\method{set{\_}defaults()} is the preferred way to set default values for
+options, since multiple options can share the same destination. For
+example, if several ``mode'' options all set the same destination, any
+one of them can set the default, and the last one wins:
+\begin{verbatim}
+parser.add_option("--advanced", action="store_const",
+ dest="mode", const="advanced",
+ default="novice") # overridden below
+parser.add_option("--novice", action="store_const",
+ dest="mode", const="novice",
+ default="advanced") # overrides above setting
+\end{verbatim}
+
+To avoid this confusion, use \method{set{\_}defaults()}:
+\begin{verbatim}
+parse.set_defaults(mode="advanced")
+parser.add_option("--advanced", action="store_const",
+ dest="mode", const="advanced")
+parser.add_option("--novice", action="store_const",
+ dest="mode", const="novice")
+\end{verbatim}
+
+\end{itemize}
% $Id$
@@ -1234,7 +1377,7 @@
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
+arguments to it. (This list will become \code{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
More information about the Python-checkins
mailing list