languages/cpython
languages/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython synced 2024-10-09 02:17:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Scattered wording and typographical improvements (up to but not

Browse source 
including the "Callback Options" section).
This commit is contained in:
Greg Ward 2003-05-03 21:22:58 +00:00
parent 649625bc05
commit d72312857e
1 changed files with 91 additions and 113 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

204
Doc/lib/liboptparse.tex
View file

@ -277,8 +277,8 @@ parser.add_option("-f", "--file", ...)
\end{verbatim}
The interesting stuff, of course, is what comes after the option
strings. In this document, we'll only cover four of the things you
can put there: \var{action}, \var{type}, \var{dest} (destination), and
strings. For now, we'll only cover four of the things you can put
there: \var{action}, \var{type}, \var{dest} (destination), and
\var{help}.
\subsubsection{The \var{store} action\label{optparse-store-action}}
@ -307,7 +307,7 @@ args = ["-f", "foo.txt"]
(Note that if you don't pass an argument list to
\function{parse_args()}, it automatically uses \var{sys.argv[1:]}.)
When \module{optparse} sees the \programopt{-f}, it sucks in the next
When \module{optparse} sees the \programopt{-f}, it consumes the next
argument---\code{foo.txt}---and stores it in the \var{filename}
attribute of a special object. That object is the first return value
from \function{parse_args()}, so:
@ -325,19 +325,20 @@ Other option types supported by \module{optparse} are \code{int} and
parser.add_option("-n", type="int", dest="num")
\end{verbatim}
Note that I didn't supply a long option, which is perfectly acceptable.
I also didn't specify the action---it defaults to ``store''.
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---\programopt{-n42} (one
argument) is equivalent to \programopt{-n 42} (two arguments). :
Let's parse another fake command-line. This time, we'll jam the option
argument right up against the option, since \programopt{-n42} (one
argument) is equivalent to \programopt{-n 42} (two arguments).
\begin{verbatim}
(options, args) = parser.parse_args(["-n42"])
print options.num
\end{verbatim}
will print ``42''.
This prints \code{42}.
Trying out the ``float'' type is left as an exercise for the reader.
@ -376,21 +377,19 @@ Here we have two different options with the same destination, which is
perfectly OK. (It just means you have to be a bit careful when setting
default values---see below.)
When \module{optparse} sees \programopt{-v} on the command line, it
sets the \var{verbose} attribute of the special {option values}
object to 1; when it sees \programopt{-q}, it sets \var{verbose} to
0.
When \module{optparse} sees \programopt{-v} on the command line, it sets
\var{options.verbose} to \code{True}; when it sees \programopt{-q}, it
sets \var{options.verbose} to \code{False}.
\subsubsection{Setting default values\label{optparse-setting-default-values}}
All of the above examples involve setting some variable (the
``destination'') when certain command-line options are seen. What
happens if those options are never seen? Since we didn't supply any
defaults, they are all set to 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.
defaults, they are all set to \code{None}. Sometimes, this is just fine (which
is why it's the default), but sometimes, you want more control. To
address that need, \module{optparse} lets you supply a default value for
each destination, which is assigned before the command-line is parsed.
First, consider the verbose/quiet example. If we want
\module{optparse} to set \var{verbose} to \code{True} unless
@ -420,8 +419,8 @@ parser.add_option("-q", action="store_false", dest="verbose", default=True)
\end{verbatim}
Again, the default value for \var{verbose} will be \code{True}: the last
default value supplied for any particular destination attribute is the
one that counts.
default value supplied for any particular destination is the one that
counts.
\subsubsection{Generating help\label{optparse-generating-help}}
@ -475,7 +474,7 @@ usage = "usage: %prog [options] arg1 arg2"
\end{verbatim}
\module{optparse} expands \samp{\%prog} in the usage string to the name of the
current script, ie. \code{os.path.basename(sys.argv[0])}. The
current script, i.e. \code{os.path.basename(sys.argv[0])}. The
expanded string is then printed before the detailed option help.
If you don't supply a usage string, \module{optparse} uses a bland but
@ -523,8 +522,8 @@ Continuing with the parser defined above, adding an
\begin{verbatim}
group = OptionGroup(parser, "Dangerous Options",
"Caution: use these options at your own risk."
" It is believed that some of them bite.")
"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}
@ -559,30 +558,29 @@ the \var{version} argument to \class{OptionParser}:
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
\end{verbatim}
Note that ``\%prog'' is expanded just like it is in \var{usage}. Apart from
that, \var{version} can contain anything you like. When you supply it,
\module{optparse} automatically adds a \longprogramopt{version} option to your
parser. If it encounters this option on the command line, it expands
your \var{version} string (by replacing ``\%prog''), prints it to
stdout, and exits.
\var{version} can contain anything you like; \code{\%prog} is expanded
in \var{version} just as with \var{usage}. When you supply it,
\module{optparse} automatically adds a \longprogramopt{version} option
to your parser. If it encounters this option on the command line, it
expands your \var{version} string (by replacing \code{\%prog}), prints
it to stdout, and exits.
For example, if your script is called /usr/bin/foo, a user might do:
\begin{verbatim}
$ /usr/bin/foo --version
foo 1.0
$
\end{verbatim}
\end{verbatim} % $ (avoid confusing emacs)
\subsubsection{Error-handling\label{optparse-error-handling}}
The one thing you need to know for basic usage is how
\module{optparse} behaves when it encounters an error on the
command-line---e.g. \programopt{-n4x} where \programopt{-n} is an
integer-valued option. \module{optparse} prints your usage message to
stderr, followed by a useful and human-readable error message. Then
it terminates (calls \function{sys.exit()}) with a non-zero exit
status.
command-line---e.g. \programopt{-n 4x} where \programopt{-n} is an
integer-valued option. In this case, \module{optparse} prints your
usage message to stderr, followed by a useful and human-readable error
message. Then it terminates (calls \function{sys.exit()}) with a
non-zero exit status.
If you don't like this, subclass \class{OptionParser} and override the
\method{error()} method. See section~\ref{optparse-extending},
@ -590,15 +588,13 @@ If you don't like this, subclass \class{OptionParser} and override the
\subsubsection{Putting it all together\label{optparse-basic-summary}}
Here's what my \module{optparse}-based scripts usually look like:
Here's what \module{optparse}-based scripts typically look like:
\begin{verbatim}
from optparse import OptionParser
...
def main ():
usage = "usage: %prog [options] arg"
[...]
def main():
usage = "usage: \%prog [-f] [-v] [-q] firstarg secondarg"
parser = OptionParser(usage)
parser.add_option("-f", "--file", type="string", dest="filename",
help="read data from FILENAME")
@ -606,16 +602,14 @@ def main ():
action="store_true", dest="verbose")
parser.add_option("-q", "--quiet",
action="store_false", dest="verbose")
# more options ...
(options, args) = parser.parse_args()
if len(args) != 1:
parser.error("incorrect number of arguments")
if options.verbose:
print "reading %s..." % options.filename
# go to work ...
print "reading \%s..." \% options.filename
[... go to work ...]
if __name__ == "__main__":
main()
@ -623,9 +617,6 @@ if __name__ == "__main__":
\subsection{Advanced Usage\label{optparse-advanced-usage}}
This is reference documentation. If you haven't read the basic
documentation in section~\ref{optparse-basic-usage}, do so now.
\subsubsection{Creating and populating the
parser\label{optparse-creating-the-parser}}
@ -634,6 +625,8 @@ is to pass a list of \class{Options} to the \class{OptionParser}
constructor:
\begin{verbatim}
from optparse import OptionParser, make_option
[...]
parser = OptionParser(option_list=[
make_option("-f", "--filename",
action="store", type="string", dest="filename"),
@ -641,20 +634,16 @@ parser = OptionParser(option_list=[
action="store_false", dest="verbose")])
\end{verbatim}
(\function{make_option()} is an alias for
the \class{Option} class, ie. this just calls the \class{Option}
constructor. A future version of \module{optparse} will probably
split \class{Option} into several classes, and
\function{make_option()} will become a factory function that picks the
right class to instantiate.)
(\function{make_option()} is a factory function for generating
\class{Option} objects.)
For long option lists, it's often more convenient/readable to create the
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"),
# 17 other options ...
[... more options ...]
make_option("-q", "--quiet",
action="store_false", dest="verbose")]
parser = OptionParser(option_list=option_list)
@ -673,15 +662,15 @@ parser.add_option("-q", "--quiet",
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}.
interdependencies among the various keyword arguments. (If you get it
wrong, \module{optparse} raises \exception{OptionError}.)
\method{add_option()} can be called in one of two ways:
\begin{itemize}
\item pass it an \class{Option} instance (as returned by \function{make_option()})
\item pass it any combination of positional and keyword arguments that
are acceptable to \function{make_option()} (ie., to the \class{Option}
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}
@ -689,7 +678,7 @@ constructor), and it will create the \class{Option} instance for you
\subsubsection{Defining options\label{optparse-defining-options}}
Each \class{Option} instance represents a set of synonymous
command-line options, ie. options that have the same meaning and
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.
@ -706,37 +695,28 @@ And to define an option with only a long option string:
make_option("--foo", ...)
\end{verbatim}
The ``...'' represents a set of keyword arguments that define
attributes of the \class{Option} object. Just which keyword args you
must supply for a given \class{Option} is fairly complicated (see the
various \method{_check_*()} methods in the \class{Option} class if you
don't believe me), but you always have to supply \emph{some}. If you
get it wrong, \module{optparse} raises an \exception{OptionError}
exception explaining your mistake.
The ``...'' represents a set of keyword arguments that define attributes
of the \class{Option} object. The rules governing which keyword args
you must supply for a given \class{Option} are fairly complicated, but
you always have to supply \emph{some}. If you get it wrong,
\module{optparse} raises an \exception{OptionError} exception explaining
your mistake.
The most important attribute of an option is its action, ie. what to do
The most important attribute of an option is its action, i.e. what to do
when we encounter this option on the command-line. The possible actions
are:
\begin{definitions}
\term{store} [default]
store this option's argument.
\term{store_const}
store a constant value.
\term{store_true}
store a true value.
\term{store_false}
store a false value.
\term{append}
append this option's argument to a list.
\term{count}
increment a counter by one.
\term{callback}
call a specified function.
\term{help}
print a usage message including all options and the documentation for
them.
\end{definitions}
\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
@ -784,7 +764,7 @@ then \module{optparse}, on seeing the \programopt{-f} or
values.filename = "foo"
\end{verbatim}
Clearly, the \var{type} and \var{dest} arguments are (usually) almost
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.
@ -801,12 +781,12 @@ requirements for each action are listed here.
The option must be followed by an argument, which is converted to a
value according to \var{type} and stored in \var{dest}. If
\var{nargs} > 1, multiple arguments will be consumed from the command
\code{nargs > 1}, multiple arguments will be consumed from the command
line; all will be converted according to \var{type} and stored to
\var{dest} as a tuple. See section~\ref{optparse-option-types},
``Option types'' below.
If \var{choices} is supplied (a list or tuple of strings), the type
If \var{choices} (a sequence of strings) is supplied, the type
defaults to ``choice''.
If \var{type} is not supplied, it defaults to ``string''.
@ -852,7 +832,7 @@ make_option("-q", "--quiet",
action="store_const", const=0, dest="verbose"),
make_option("-v", "--verbose",
action="store_const", const=1, dest="verbose"),
make_option(None, "--noisy",
make_option("--noisy",
action="store_const", const=2, dest="verbose"),
\end{verbatim}
@ -868,7 +848,7 @@ A special case of ``store_const'' that stores \code{True} to \var{dest}.
\term{store_false} [required: \var{dest}]
Like ``store_true'', but stores a \code{False}
Like ``store_true'', but stores \code{False}
Example:
@ -881,9 +861,9 @@ make_option(None, "--no-clobber", action="store_false", dest="clobber")
The option must be followed by an argument, which is appended to the
list in \var{dest}. If no default value for \var{dest} is supplied
(ie. the default is None), an empty list is automatically created when
(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 \samp{nargs > 1}, multiple arguments are consumed, and a tuple of
If \code{nargs > 1}, multiple arguments are consumed, and a tuple of
length \var{nargs} is appended to \var{dest}.
The defaults for \var{type} and \var{dest} are the same as for the
@ -938,7 +918,7 @@ Every subsequent occurrence of \programopt{-v} results in:
values.verbosity += 1
\end{verbatim}
\term{callback} [required: \var{'callback'};
\term{callback} [required: \var{callback};
relevant: \var{type}, \var{nargs}, \var{callback_args},
\var{callback_kwargs}]
@ -954,7 +934,7 @@ func(option : Option,
\end{verbatim}
Callback options are covered in detail in
section~\ref{optparse-callback-options} ``Callback Options.''
section~\ref{optparse-callback-options}, ``Callback Options.''
\term{help} [required: none]
@ -1012,7 +992,7 @@ argument is supplied to the \class{OptionParser} constructor.
\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
---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}.''
@ -1025,8 +1005,8 @@ Python integers. If \function{int()} fails, so will
\module{optparse}, although with a more useful error message.
Internally, \module{optparse} raises \exception{OptionValueError} in
\function{optparse.check_builtin()}; at a higher level (in
\class{OptionParser}) this is caught and \module{optparse} terminates
your program with a useful error message.
\class{OptionParser}), \module{optparse} catches this exception and
terminates your program with a useful error message.
Likewise, float arguments are passed to \function{float()} for
conversion, long arguments to \function{long()}, and complex arguments
@ -1036,7 +1016,7 @@ identically to integer arguments.
Choice options are a subtype of string options. A master list or
tuple of choices (strings) must be passed to the option constructor
(\function{make_option()} or \method{OptionParser.add_option()}) as
the ``choices'' keyword argument. Choice option arguments are
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.
@ -1054,7 +1034,7 @@ there. \class{OptionParser} provides a couple of methods to help you out:
\begin{methoddesc}{get_option}{opt_str}
Returns the \class{Option} instance that implements the option
string you supplied, or None if no options implement it.
string you supplied, or \code{None} if no options implement it.
\end{methoddesc}
\begin{methoddesc}{remove_option}{opt_str}
@ -1107,9 +1087,7 @@ parser = OptionParser(..., conflict_handler="resolve")
or via the \method{set_conflict_handler()} method.
The default conflict-handling mechanism is ``error''. The only other
one is ``ignore'', which restores the (arguably broken) behaviour of
\module{optparse} 1.1 and earlier.
The default conflict-handling mechanism is \code{error}.
Here's an example: first, define an \class{OptionParser} set to
resolve conflicts intelligently:
@ -1246,8 +1224,8 @@ is the argument to this option seen on the command-line.
\module{optparse} will only expect an argument if \var{type} is
set; the type of \var{value} will be the type implied by the
option's type (see~\ref{optparse-option-types}, ``Option types''). If
\var{type} for this option is None (no argument expected), then
\var{value} will be None. If \samp{nargs > 1}, \var{value} will
\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}
@ -1257,13 +1235,13 @@ as instance attributes:
\begin{definitions}
\term{parser.rargs}
the current remaining argument list, ie. with \var{opt} (and
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, ie. arguments that have been
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.
@ -1463,7 +1441,7 @@ option, the most likely direction of extension is to add new actions
and new types.
Also, the examples section includes several demonstrations of
extending \module{optparse} in different ways: eg. a case-insensitive
extending \module{optparse} in different ways: e.g. a case-insensitive
option parser, or two kinds of option parsers that implement
``required options''.
@ -1656,14 +1634,14 @@ values.ensure_value(attr, value)
\end{itemize}
If the \member{attr} attribute of \var{values} doesn't exist or is
None, then \method{ensure_value()} first sets it to \var{value}, and
\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 None and
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.
@ -1674,7 +1652,7 @@ might want to extend \module{optparse}. I can think of at least two
other areas to play with.
First, the simple one: \class{OptionParser} tries to be helpful by
calling \function{sys.exit()} when appropriate, ie. when there's an
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