diff options
| -rw-r--r-- | Doc/lib/liboptparse.tex | 204 |
1 files changed, 91 insertions, 113 deletions
diff --git a/Doc/lib/liboptparse.tex b/Doc/lib/liboptparse.tex index 8f9de1e..9364e95 100644 --- a/Doc/lib/liboptparse.tex +++ b/Doc/lib/liboptparse.tex @@ -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 |