[Python-checkins] python/dist/src/Doc/lib liboptparse.tex,1.6,1.7
gward@users.sourceforge.net
gward@users.sourceforge.net
Sat, 03 May 2003 14:23:01 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv8404
Modified Files:
liboptparse.tex
Log Message:
Scattered wording and typographical improvements (up to but not
including the "Callback Options" section).
Index: liboptparse.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/liboptparse.tex,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** liboptparse.tex 3 May 2003 20:41:37 -0000 1.6
--- liboptparse.tex 3 May 2003 21:22:58 -0000 1.7
***************
*** 278,283 ****
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
\var{help}.
--- 278,283 ----
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: \var{action}, \var{type}, \var{dest} (destination), and
\var{help}.
***************
*** 308,312 ****
\function{parse_args()}, it automatically uses \var{sys.argv[1:]}.)
! When \module{optparse} sees the \programopt{-f}, it sucks in 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
--- 308,312 ----
\function{parse_args()}, it automatically uses \var{sys.argv[1:]}.)
! 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
***************
*** 326,335 ****
\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''.
! 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). :
\begin{verbatim}
--- 326,336 ----
\end{verbatim}
! This example doesn't provide a long option, which is perfectly
! acceptable. It also doesn't specify the action---it defaults to
! ``store''.
! Let's parse another fake command-line. This time, we'll jam the option
! argument right up against the option, since \programopt{-n42} (one
! argument) is equivalent to \programopt{-n 42} (two arguments).
\begin{verbatim}
***************
*** 338,342 ****
\end{verbatim}
! will print ``42''.
Trying out the ``float'' type is left as an exercise for the reader.
--- 339,343 ----
\end{verbatim}
! This prints \code{42}.
Trying out the ``float'' type is left as an exercise for the reader.
***************
*** 377,384 ****
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.
\subsubsection{Setting default values\label{optparse-setting-default-values}}
--- 378,384 ----
default values---see below.)
! 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}}
***************
*** 387,395 ****
``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.
First, consider the verbose/quiet example. If we want
--- 387,394 ----
``destination'') when certain command-line options are seen. What
happens if those options are never seen? Since we didn't supply any
! defaults, they are all set to \code{None}. Sometimes, this is just fine (which
! is why it's the default), but sometimes, you want more control. To
! address that need, \module{optparse} lets you supply a default value for
! each destination, which is assigned before the command-line is parsed.
First, consider the verbose/quiet example. If we want
***************
*** 421,426 ****
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.
\subsubsection{Generating help\label{optparse-generating-help}}
--- 420,425 ----
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.
\subsubsection{Generating help\label{optparse-generating-help}}
***************
*** 476,480 ****
\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
expanded string is then printed before the detailed option help.
--- 475,479 ----
\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.
***************
*** 524,529 ****
\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)
--- 523,528 ----
\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)
***************
*** 560,569 ****
\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.
For example, if your script is called /usr/bin/foo, a user might do:
--- 559,568 ----
\end{verbatim}
! \var{version} can contain anything you like; \code{\%prog} is expanded
! in \var{version} just as with \var{usage}. When you supply it,
! \module{optparse} automatically adds a \longprogramopt{version} option
! to your parser. If it encounters this option on the command line, it
! expands your \var{version} string (by replacing \code{\%prog}), prints
! it to stdout, and exits.
For example, if your script is called /usr/bin/foo, a user might do:
***************
*** 572,577 ****
$ /usr/bin/foo --version
foo 1.0
! $
! \end{verbatim}
\subsubsection{Error-handling\label{optparse-error-handling}}
--- 571,575 ----
$ /usr/bin/foo --version
foo 1.0
! \end{verbatim} % $ (avoid confusing emacs)
\subsubsection{Error-handling\label{optparse-error-handling}}
***************
*** 579,587 ****
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.
If you don't like this, subclass \class{OptionParser} and override the
--- 577,585 ----
The one thing you need to know for basic usage is how
\module{optparse} behaves when it encounters an error on the
! command-line---e.g. \programopt{-n 4x} where \programopt{-n} is an
! integer-valued option. In this case, \module{optparse} prints your
! usage message to stderr, followed by a useful and human-readable error
! message. Then it terminates (calls \function{sys.exit()}) with a
! non-zero exit status.
If you don't like this, subclass \class{OptionParser} and override the
***************
*** 591,603 ****
\subsubsection{Putting it all together\label{optparse-basic-summary}}
! Here's what my \module{optparse}-based scripts usually look like:
\begin{verbatim}
from optparse import OptionParser
!
! ...
!
! def main ():
! usage = "usage: %prog [options] arg"
parser = OptionParser(usage)
parser.add_option("-f", "--file", type="string", dest="filename",
--- 589,599 ----
\subsubsection{Putting it all together\label{optparse-basic-summary}}
! Here's what \module{optparse}-based scripts typically look like:
\begin{verbatim}
from optparse import OptionParser
! [...]
! def main():
! usage = "usage: \%prog [-f] [-v] [-q] firstarg secondarg"
parser = OptionParser(usage)
parser.add_option("-f", "--file", type="string", dest="filename",
***************
*** 607,611 ****
parser.add_option("-q", "--quiet",
action="store_false", dest="verbose")
- # more options ...
(options, args) = parser.parse_args()
--- 603,606 ----
***************
*** 614,620 ****
if options.verbose:
! print "reading %s..." % options.filename
!
! # go to work ...
if __name__ == "__main__":
--- 609,614 ----
if options.verbose:
! print "reading \%s..." \% options.filename
! [... go to work ...]
if __name__ == "__main__":
***************
*** 624,630 ****
\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}}
--- 618,621 ----
***************
*** 635,638 ****
--- 626,631 ----
\begin{verbatim}
+ from optparse import OptionParser, make_option
+ [...]
parser = OptionParser(option_list=[
make_option("-f", "--filename",
***************
*** 642,653 ****
\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.)
! For long option lists, it's often more convenient/readable to create the
list separately:
--- 635,642 ----
\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:
***************
*** 655,659 ****
option_list = [make_option("-f", "--filename",
action="store", type="string", dest="filename"),
! # 17 other options ...
make_option("-q", "--quiet",
action="store_false", dest="verbose")]
--- 644,648 ----
option_list = [make_option("-f", "--filename",
action="store", type="string", dest="filename"),
! [... more options ...]
make_option("-q", "--quiet",
action="store_false", dest="verbose")]
***************
*** 674,679 ****
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:
--- 663,668 ----
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:
***************
*** 682,686 ****
\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}
constructor), and it will create the \class{Option} instance for you
(shown above).
--- 671,675 ----
\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).
***************
*** 690,694 ****
Each \class{Option} instance represents a set of synonymous
! command-line options, ie. 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
--- 679,683 ----
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
***************
*** 707,741 ****
\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 most important attribute of an option is its action, ie. 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}
(If you don't supply an action, the default is ``store''. For this
--- 696,721 ----
\end{verbatim}
! The ``...'' represents a set of keyword arguments that define attributes
! of the \class{Option} object. The rules governing which keyword args
! you must supply for a given \class{Option} are fairly complicated, but
! you always have to supply \emph{some}. If you get it wrong,
! \module{optparse} raises an \exception{OptionError} exception explaining
! your mistake.
! The most important attribute of an option is its action, i.e. what to do
when we encounter this option on the command-line. The possible actions
are:
! \begin{tableii}{l|l}{code}{Action}{Meaning}
! \lineii{store}{store this option's argument (default)}
! \lineii{store_const}{store a constant value}
! \lineii{store_true}{store a true value}
! \lineii{store_false}{store a false value}
! \lineii{append}{append this option's argument to a list}
! \lineii{count}{increment a counter by one}
! \lineii{callback}{call a specified function}
! \lineii{help}{print a usage message including all options and the
! documentation for them}
! \end{tableii}
(If you don't supply an action, the default is ``store''. For this
***************
*** 785,789 ****
\end{verbatim}
! Clearly, the \var{type} and \var{dest} arguments are (usually) 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
--- 765,769 ----
\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
***************
*** 802,811 ****
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
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
defaults to ``choice''.
--- 782,791 ----
The option must be followed by an argument, which is converted to a
value according to \var{type} and stored in \var{dest}. If
! \code{nargs > 1}, multiple arguments will be consumed from the command
line; all will be converted according to \var{type} and stored to
\var{dest} as a tuple. See section~\ref{optparse-option-types},
``Option types'' below.
! If \var{choices} (a sequence of strings) is supplied, the type
defaults to ``choice''.
***************
*** 853,857 ****
make_option("-v", "--verbose",
action="store_const", const=1, dest="verbose"),
! make_option(None, "--noisy",
action="store_const", const=2, dest="verbose"),
\end{verbatim}
--- 833,837 ----
make_option("-v", "--verbose",
action="store_const", const=1, dest="verbose"),
! make_option("--noisy",
action="store_const", const=2, dest="verbose"),
\end{verbatim}
***************
*** 869,873 ****
\term{store_false} [required: \var{dest}]
! Like ``store_true'', but stores a \code{False}
Example:
--- 849,853 ----
\term{store_false} [required: \var{dest}]
! Like ``store_true'', but stores \code{False}
Example:
***************
*** 882,888 ****
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
\module{optparse} first encounters this option on the command-line.
! If \samp{nargs > 1}, multiple arguments are consumed, and a tuple of
length \var{nargs} is appended to \var{dest}.
--- 862,868 ----
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}.
***************
*** 939,943 ****
\end{verbatim}
! \term{callback} [required: \var{'callback'};
relevant: \var{type}, \var{nargs}, \var{callback_args},
\var{callback_kwargs}]
--- 919,923 ----
\end{verbatim}
! \term{callback} [required: \var{callback};
relevant: \var{type}, \var{nargs}, \var{callback_args},
\var{callback_kwargs}]
***************
*** 955,959 ****
Callback options are covered in detail in
! section~\ref{optparse-callback-options} ``Callback Options.''
\term{help} [required: none]
--- 935,939 ----
Callback options are covered in detail in
! section~\ref{optparse-callback-options}, ``Callback Options.''
\term{help} [required: none]
***************
*** 1013,1017 ****
\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}.''
--- 993,997 ----
\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}.''
***************
*** 1026,1031 ****
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.
Likewise, float arguments are passed to \function{float()} for
--- 1006,1011 ----
Internally, \module{optparse} raises \exception{OptionValueError} in
\function{optparse.check_builtin()}; at a higher level (in
! \class{OptionParser}), \module{optparse} catches this exception and
! terminates your program with a useful error message.
Likewise, float arguments are passed to \function{float()} for
***************
*** 1037,1041 ****
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
compared against this master list in
\function{optparse.check_choice()}, and \exception{OptionValueError}
--- 1017,1021 ----
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}
***************
*** 1055,1059 ****
\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.
\end{methoddesc}
--- 1035,1039 ----
\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}
***************
*** 1108,1114 ****
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.
Here's an example: first, define an \class{OptionParser} set to
--- 1088,1092 ----
or via the \method{set_conflict_handler()} method.
! The default conflict-handling mechanism is \code{error}.
Here's an example: first, define an \class{OptionParser} set to
***************
*** 1247,1252 ****
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
be a tuple of values of the appropriate type.
--- 1225,1230 ----
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.
***************
*** 1258,1262 ****
\begin{definitions}
\term{parser.rargs}
! the current remaining argument list, ie. with \var{opt} (and
\var{value}, if any) removed, and only the arguments following
them still there. Feel free to modify \member{parser.rargs},
--- 1236,1240 ----
\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},
***************
*** 1264,1268 ****
\term{parser.largs}
! the current set of leftover arguments, ie. 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
--- 1242,1246 ----
\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
***************
*** 1464,1468 ****
Also, the examples section includes several demonstrations of
! extending \module{optparse} in different ways: eg. a case-insensitive
option parser, or two kinds of option parsers that implement
``required options''.
--- 1442,1446 ----
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''.
***************
*** 1657,1661 ****
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
then returns \var{value}. This is very handy for actions like
``extend'', ``append'', and ``count'', all of which accumulate data in
--- 1635,1639 ----
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
***************
*** 1664,1668 ****
\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
\method{ensure_value()} will take care of getting it right when it's
needed.
--- 1642,1646 ----
\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.
***************
*** 1675,1679 ****
First, the simple one: \class{OptionParser} tries to be helpful by
! calling \function{sys.exit()} when appropriate, ie. 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
--- 1653,1657 ----
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