diff options
Diffstat (limited to 'Doc/lib/liboptparse.tex')
| -rw-r--r-- | Doc/lib/liboptparse.tex | 1888 |
1 files changed, 0 insertions, 1888 deletions
diff --git a/Doc/lib/liboptparse.tex b/Doc/lib/liboptparse.tex deleted file mode 100644 index eb4919b..0000000 --- a/Doc/lib/liboptparse.tex +++ /dev/null @@ -1,1888 +0,0 @@ -% THIS FILE IS AUTO-GENERATED! DO NOT EDIT! -% (Your changes will be lost the next time it is generated.) -\section{\module{optparse} --- More powerful command line option parser} -\declaremodule{standard}{optparse} -\moduleauthor{Greg Ward}{gward@python.net} -\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). - -\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 \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") -parser.add_option("-q", "--quiet", - action="store_false", dest="verbose", default=True, - help="don't print status messages to stdout") - -(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, for example: -\begin{verbatim} -<yourscript> --file=outfile -q -\end{verbatim} - -As it parses the command line, \code{optparse} sets attributes of the -\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, \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 -ways. Thus, the following command lines are all equivalent to the above -example: -\begin{verbatim} -<yourscript> -f outfile --quiet -<yourscript> --quiet --file outfile -<yourscript> -q -foutfile -<yourscript> -qfoutfile -\end{verbatim} - -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 - -f FILE, --file=FILE write report to FILE - -q, --quiet don't print status messages to stdout -\end{verbatim} - -where the value of \emph{yourscript} is determined at runtime (normally -from \code{sys.argv{[}0]}). -% $Id: intro.txt 413 2004-09-28 00:59:13Z greg $ - - -\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''. - -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}. - -Some other option syntaxes that the world has seen include: -\begin{itemize} -\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} - -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 that option is. -With \module{optparse}, option arguments may either be in a separate argument -from their option: -\begin{verbatim} --f foo ---file foo -\end{verbatim} - -or included in the same argument: -\begin{verbatim} --ffoo ---file=foo -\end{verbatim} - -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 -removed from the argument list. -\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 -\end{verbatim} - -\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-what-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 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. - -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 -\end{verbatim} - -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-what-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 -before they successfully run the program. This applies whether the user -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 -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, 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: tao.txt 413 2004-09-28 00:59:13Z greg $ - - -\subsection{Tutorial\label{optparse-tutorial}} - -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 -[...] -parser = OptionParser() -\end{verbatim} - -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} - -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. - -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. - -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} - -(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 {} -\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 {} -\code{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{Understanding option actions\label{optparse-understanding-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-optparse}, 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 \code{options}. - -If you don't specify an option action, \module{optparse} defaults to \code{store}. - - -\subsubsection{The store action\label{optparse-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: -\begin{verbatim} -args = ["-f", "foo.txt"] -(options, args) = parser.parse_args(args) -\end{verbatim} - -When \module{optparse} sees the option string \code{"-f"}, it consumes the next -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}. -Here's an option that expects an integer argument: -\begin{verbatim} -parser.add_option("-n", type="int", dest="num") -\end{verbatim} - -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"]) -print options.num -\end{verbatim} - -will print \code{"42"}. - -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 -\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}. - -\module{optparse} also includes built-in \code{long} and \code{complex} types. Adding -types is covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}. - - -\subsubsection{Handling boolean (flag) options\label{optparse-handling-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 -\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") -\end{verbatim} - -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} 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{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 section~\ref{optparse-reference-guide}, Reference Guide and section~\ref{optparse-option-callbacks}, Option Callbacks. - - -\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}. 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 -\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") -\end{verbatim} - -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} - -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 \code{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}} - -\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) -parser.add_option("-v", "--verbose", - action="store_true", dest="verbose", default=True, - help="make lots of noise [default]") -parser.add_option("-q", "--quiet", - action="store_false", dest="verbose", - help="be vewwy quiet (I'm hunting wabbits)") -parser.add_option("-f", "--filename", - metavar="FILE", help="write output to FILE"), -parser.add_option("-m", "--mode", - default="intermediate", - help="interaction mode: novice, intermediate, " - "or expert [default: %default]") -\end{verbatim} - -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) - -f FILE, --filename=FILE - write output to FILE - -m MODE, --mode=MODE interaction mode: novice, intermediate, or - expert [default: intermediate] -\end{verbatim} - -(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: -\begin{verbatim} -usage = "usage: %prog [options] arg1 arg2" -\end{verbatim} - -\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. - -\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 -automatically-generated help message, e.g. for the ``mode'' option: -\begin{verbatim} --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 \longprogramopt{filename} option explicitly sets -\code{metavar="FILE"}, resulting in this automatically-generated option -description: -\begin{verbatim} --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 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} - - -\subsubsection{Printing a version string\label{optparse-printing-version-string}} - -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} - -\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 -\code{version} string (by replacing \code{"{\%}prog"}), prints it to stdout, and -exits. - -For example, if your script is called \code{/usr/bin/foo}: -\begin{verbatim} -$ /usr/bin/foo --version -foo 1.0 -\end{verbatim} - - -\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 -erroneous calls to \code{parser.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. - -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} - -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. - -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 [options] arg" - parser = OptionParser(usage) - 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) != 1: - parser.error("incorrect number of arguments") - if options.verbose: - print "reading %s..." % options.filename - [...] - -if __name__ == "__main__": - main() -\end{verbatim} -% $Id: tutorial.txt 515 2006-06-10 15:37:45Z gward $ - - -\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 -preferred way is by using \code{OptionParser.add{\_}option()}, as shown in -section~\ref{optparse-tutorial}, the tutorial. \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} -option_list = [ - make_option("-f", "--filename", - action="store", type="string", dest="filename"), - make_option("-q", "--quiet", - action="store_false", dest="verbose"), - ] -parser = OptionParser(option_list=option_list) -\end{verbatim} - -(\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.) - - -\subsubsection{Defining options\label{optparse-defining-options}} - -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 with the -\method{add{\_}option()} method of \class{OptionParser}: -\begin{verbatim} -parser.add_option(opt_str[, ...], attr=value, ...) -\end{verbatim} - -To define an option with only a short option string: -\begin{verbatim} -parser.add_option("-f", attr=value, ...) -\end{verbatim} - -And to define an option with only a long option string: -\begin{verbatim} -parser.add_option("--foo", attr=value, ...) -\end{verbatim} - -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 standard option 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{append{\_}const}] -append a constant value 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} - -(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 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 \code{options} object: -\begin{verbatim} -options = Values() -\end{verbatim} - -If one of the options in this parser is defined with -\begin{verbatim} -parser.add_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 ---file=foo ---file foo -\end{verbatim} - -then \module{optparse}, on seeing this option, will do the equivalent of -\begin{verbatim} -options.filename = "foo" -\end{verbatim} - -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{Standard option actions\label{optparse-standard-option-actions}} - -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}] - -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. - -If \code{choices} is supplied (a list or tuple of strings), the type -defaults to \code{choice}. - -If \member{type} is not supplied, it defaults to \code{string}. - -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} -parser.add_option("-f") -parser.add_option("-p", type="float", nargs=3, dest="point") -\end{verbatim} - -As it parses the command line -\begin{verbatim} --f foo.txt -p 1 -3.5 4 -fbar.txt -\end{verbatim} - -\module{optparse} will set -\begin{verbatim} -options.f = "foo.txt" -options.point = (1.0, -3.5, 4.0) -options.f = "bar.txt" -\end{verbatim} - -\item {} -\code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}] - -The value \code{const} is stored in \member{dest}. - -Example: -\begin{verbatim} -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 \code{"-{}-noisy"} is seen, \module{optparse} will set -\begin{verbatim} -options.verbose = 2 -\end{verbatim} - -\item {} -\code{store{\_}true} {[}relevant: \member{dest}] - -A special case of \code{store{\_}const} that stores a true value -to \member{dest}. - -\item {} -\code{store{\_}false} {[}relevant: \member{dest}] - -Like \code{store{\_}true}, but stores a false value. - -Example: -\begin{verbatim} -parser.add_option("--clobber", action="store_true", dest="clobber") -parser.add_option("--no-clobber", action="store_false", dest="clobber") -\end{verbatim} - -\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 \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 \member{type} and \member{dest} are the same as for the -\code{store} action. - -Example: -\begin{verbatim} -parser.add_option("-t", "--tracks", action="append", type="int") -\end{verbatim} - -If \code{"-t3"} is seen on the command-line, \module{optparse} does the equivalent of: -\begin{verbatim} -options.tracks = [] -options.tracks.append(int("3")) -\end{verbatim} - -If, a little later on, \code{"-{}-tracks=4"} is seen, it does: -\begin{verbatim} -options.tracks.append(int("4")) -\end{verbatim} - -\item {} -\code{append{\_}const} {[}required: \code{const}; relevant: \member{dest}] - -Like \code{store{\_}const}, but the value \code{const} is appended to \member{dest}; -as with \code{append}, \member{dest} defaults to \code{None}, and an an empty list is -automatically created the first time the option is encountered. - -\item {} -\code{count} {[}relevant: \member{dest}] - -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} -parser.add_option("-v", action="count", dest="verbosity") -\end{verbatim} - -The first time \code{"-v"} is seen on the command line, \module{optparse} does the -equivalent of: -\begin{verbatim} -options.verbosity = 0 -options.verbosity += 1 -\end{verbatim} - -Every subsequent occurrence of \code{"-v"} results in -\begin{verbatim} -options.verbosity += 1 -\end{verbatim} - -\item {} -\code{callback} {[}required: \code{callback}; -relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}] - -Call the function specified by \code{callback}, which is called as -\begin{verbatim} -func(option, opt_str, value, parser, *args, **kwargs) -\end{verbatim} - -See section~\ref{optparse-option-callbacks}, Option Callbacks for more detail. - -\item {} -\member{help} - -Prints a complete help message for all the options in the -current option parser. The help message is constructed from -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 -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 OptionParser, 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 \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: foo.py [options] - -options: - -h, --help Show this help message and exit - -v Be moderately verbose - --file=FILENAME Input file to read data from -\end{verbatim} - -After printing the help message, \module{optparse} terminates your process -with \code{sys.exit(0)}. - -\item {} -\code{version} - -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 attributes\label{optparse-option-attributes}} - -The following option attributes may be passed as keyword arguments -to \code{parser.add{\_}option()}. If you pass an option attribute -that is not relevant to a particular option, or fail to pass a required -option attribute, \module{optparse} raises OptionError. -\begin{itemize} -\item {} -\member{action} (default: \code{"store"}) - -Determines \module{optparse}'s behaviour when this option is seen on the command -line; the available options are documented above. - -\item {} -\member{type} (default: \code{"string"}) - -The argument type expected by this option (e.g., \code{"string"} or -\code{"int"}); the available option types are documented below. - -\item {} -\member{dest} (default: derived from option strings) - -If the option's action implies writing or modifying a value somewhere, -this tells \module{optparse} where to write it: \member{dest} names an attribute of the -\code{options} object that \module{optparse} builds as it parses the command line. - -\item {} -\code{default} (deprecated) - -The value to use for this option's destination if the option is not -seen on the command line. Deprecated; use \code{parser.set{\_}defaults()} -instead. - -\item {} -\code{nargs} (default: 1) - -How many arguments of type \member{type} should be consumed when this -option is seen. If {\textgreater} 1, \module{optparse} will store a tuple of values to -\member{dest}. - -\item {} -\code{const} - -For actions that store a constant value, the constant value to store. - -\item {} -\code{choices} - -For options of type \code{"choice"}, the list of strings the user -may choose from. - -\item {} -\code{callback} - -For options with action \code{"callback"}, the callable to call when this -option is seen. See section~\ref{optparse-option-callbacks}, Option Callbacks for detail on the arguments -passed to \code{callable}. - -\item {} -\code{callback{\_}args}, \code{callback{\_}kwargs} - -Additional positional and keyword arguments to pass to \code{callback} -after the four standard callback arguments. - -\item {} -\member{help} - -Help text to print for this option when listing all available options -after the user supplies a \member{help} option (such as \code{"-{}-help"}). -If no help text is supplied, the option will be listed without help -text. To hide this option, use the special value \code{SUPPRESS{\_}HELP}. - -\item {} -\code{metavar} (default: derived from option strings) - -Stand-in for the option argument(s) to use when printing help text. -See section~\ref{optparse-tutorial}, the tutorial for an example. - -\end{itemize} - - -\subsubsection{Standard option types\label{optparse-standard-option-types}} - -\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-optparse}, 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. - -Integer arguments (type \code{int} or \code{long}) are parsed as follows: -\begin{quote} -\begin{itemize} -\item {} -if the number starts with \code{0x}, it is parsed as a hexadecimal number - -\item {} -if the number starts with \code{0}, it is parsed as an octal number - -\item {} -if the number starts with \code{0b}, is is parsed as a binary number - -\item {} -otherwise, the number is parsed as a decimal number - -\end{itemize} -\end{quote} - -The conversion is done by calling either \code{int()} or \code{long()} with -the appropriate base (2, 8, 10, or 16). If this fails, so will \module{optparse}, -although with a more useful error message. - -\code{float} and \code{complex} option arguments are converted directly with -\code{float()} and \code{complex()}, with similar error-handling. - -\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.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, values=None) -\end{verbatim} - -where the input parameters are -\begin{description} -\item[\code{args}] -the list of arguments to process (default: \code{sys.argv{[}1:]}) -\item[\code{values}] -object to store option arguments in (default: a new instance of -optparse.Values) -\end{description} - -and the return values are -\begin{description} -\item[\code{options}] -the same object that was passed in as \code{options}, or the -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 \code{options}, it will be modified with repeated \code{setattr()} -calls (roughly one for every option argument stored to an option -destination) and 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 -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. -If \code{opt{\_}str} does not occur in any option belonging to this -OptionParser, raises ValueError. -\end{description} - - -\subsubsection{Conflicts between options\label{optparse-conflicts-between-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 particularly true if you've defined your own OptionParser -subclass with some standard options.) - -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=handler) -\end{verbatim} - -or with a separate call: -\begin{verbatim} -parser.set_conflict_handler(handler) -\end{verbatim} - -The available conflict handlers 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} - -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} - -At this point, \module{optparse} detects that a previously-added option is already -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 do no harm - [...] - -n, --noisy be noisy -\end{verbatim} - -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 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} - - -\subsubsection{Cleanup\label{optparse-cleanup}} - -OptionParser instances have several cyclic references. This should not -be a problem for Python's garbage collector, but you may wish to break -the cyclic references explicitly by calling \code{destroy()} on your -OptionParser once you are done with it. This is particularly useful in -long-running applications where large object graphs are reachable from -your OptionParser. - - -\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} -parser.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: reference.txt 519 2006-06-11 14:39:11Z gward $ - - -\subsection{Option Callbacks\label{optparse-option-callbacks}} - -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. - -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-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", action="callback", callback=my_callback) -\end{verbatim} - -\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 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} - - -\subsubsection{How callbacks are called\label{optparse-how-callbacks-called}} - -All callbacks are called as follows: -\begin{verbatim} -func(option, opt_str, value, parser, *args, **kwargs) -\end{verbatim} - -where -\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, \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 \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 -\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[\code{args}] -is a tuple of arbitrary positional arguments supplied via the -\code{callback{\_}args} option attribute. -\item[\code{kwargs}] -is a dictionary of arbitrary keyword arguments supplied via -\code{callback{\_}kwargs}. -\end{description} - - -\subsubsection{Raising errors in a callback\label{optparse-raising-errors-in-callback}} - -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. - - -\subsubsection{Callback example 1: trivial callback\label{optparse-callback-example-1}} - -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_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 \code{store{\_}true} action. - - -\subsubsection{Callback example 2: check option order\label{optparse-callback-example-2}} - -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_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} - - -\subsubsection{Callback example 3: check option order (generalized)\label{optparse-callback-example-3}} - -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_str, value, parser): - if parser.values.b: - 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} - - -\subsubsection{Callback example 4: check arbitrary condition\label{optparse-callback-example-4}} - -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_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{\_}moon{\_}full()} is left as an exercise for the -reader.) - - -\subsubsection{Callback example 5: fixed arguments\label{optparse-callback-example-5}} - -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 \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 \code{store} action: -\begin{verbatim} -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.) - - -\subsubsection{Callback example 6: variable arguments\label{optparse-callback-example-6}} - -Things get hairy when you want an option to take a variable number of -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 {} -either \code{"-{}-"} or \code{"-"} can be option arguments - -\item {} -bare \code{"-{}-"} (if not the argument to some option): halt command-line -processing and discard the \code{"-{}-"} - -\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). - -Nevertheless, here's a stab at a callback for an option with variable -arguments: -\begin{verbatim} -def vararg_callback(option, opt_str, value, parser): - assert value is None - done = 0 - value = [] - rargs = parser.rargs - while rargs: - arg = rargs[0] - - # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f", - # etc. Note that this also stops on "-3" or "-3.0", so if - # your option takes numeric values, you will need to handle - # this. - if ((arg[:2] == "--" and len(arg) > 2) or - (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")): - break - else: - value.append(arg) - del rargs[0] - - 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 \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: callbacks.txt 415 2004-09-30 02:26:17Z greg $ - - -\subsection{Extending \module{optparse}\label{optparse-extending-optparse}} - -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. - - -\subsubsection{Adding new types\label{optparse-adding-new-types}} - -To add new types, you need to define your own subclass of \module{optparse}'s 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_mytype(option, opt, value) -\end{verbatim} - -where \code{option} is an \class{Option} instance, \code{opt} is an option string -(e.g., \code{"-f"}), and \code{value} is the string from the command line that -must be checked and converted to your desired type. \code{check{\_}mytype()} -should return an object of the hypothetical type \code{mytype}. The value -returned by a type-checking function will wind up in the OptionValues -instance returned by \method{OptionParser.parse{\_}args()}, or be passed to a -callback as the \code{value} parameter. - -Your type-checking function should raise OptionValueError if it -encounters any problems. OptionValueError takes a single string -argument, which is passed as-is to OptionParser's \method{error()} method, -which in turn prepends the program name and the string \code{"error:"} and -prints everything to stderr before terminating the process. - -Here's a silly example that demonstrates adding a \code{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 added built-in -support for complex numbers, 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 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 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 -OptionParser to use MyOption instead of Option: -\begin{verbatim} -parser = OptionParser(option_class=MyOption) -parser.add_option("-c", type="complex") -\end{verbatim} - -Alternately, you can build your own option list and pass it to -OptionParser; if you don't use \method{add{\_}option()} in the above way, you -don't need to tell 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-new-actions}} - -Adding new actions is a bit trickier, because you have to understand -that \module{optparse} has a couple of classifications for actions: -\begin{description} -\item[``store'' actions] -actions that result in \module{optparse} storing a value to an attribute of the -current OptionValues instance; these options require a \member{dest} -attribute to be supplied to the Option constructor -\item[``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 \member{type} attribute to the -Option constructor. -\end{description} - -These are overlapping sets: some default ``store'' actions are \code{store}, -\code{store{\_}const}, \code{append}, and \code{count}, while the default ``typed'' -actions are \code{store}, \code{append}, and \code{callback}. - -When you add an action, you need to categorize it by listing it in at -least one of the following class attributes of Option (all are lists of -strings): -\begin{description} -\item[\member{ACTIONS}] -all actions must be listed in ACTIONS -\item[\member{STORE{\_}ACTIONS}] -``store'' actions are additionally listed here -\item[\member{TYPED{\_}ACTIONS}] -``typed'' actions are additionally listed here -\item[\code{ALWAYS{\_}TYPED{\_}ACTIONS}] -actions that always take a type (i.e. whose options always take a -value) are additionally listed here. The only effect of this is -that \module{optparse} assigns the default type, \code{string}, to options with no -explicit type whose action is listed in \code{ALWAYS{\_}TYPED{\_}ACTIONS}. -\end{description} - -In order to actually implement your new action, you must override -Option's \method{take{\_}action()} method and add a case that recognizes your -action. - -For example, let's add an \code{extend} action. This is similar to the -standard \code{append} action, but instead of taking a single value from -the command-line and appending it to an existing list, \code{extend} will -take multiple values in a single comma-delimited string, and extend an -existing list with them. That is, if \code{"-{}-names"} is an \code{extend} -option of type \code{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 Option: -\begin{verbatim} -class MyOption (Option): - - ACTIONS = Option.ACTIONS + ("extend",) - STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",) - TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",) - ALWAYS_TYPED_ACTIONS = Option.ALWAYS_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 {} -\code{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 {} -to ensure that \module{optparse} assigns the default type of \code{string} to -\code{extend} actions, we put the \code{extend} action in -\code{ALWAYS{\_}TYPED{\_}ACTIONS} as well - -\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 {} -\code{values} is an instance of the optparse{\_}parser.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} - -If the \code{attr} attribute of \code{values} doesn't exist or is None, then -ensure{\_}value() first sets it to \code{value}, and then returns 'value. -This is very handy for actions like \code{extend}, \code{append}, and -\code{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 \method{ensure{\_}value()} will take care of getting it right when -it's needed. - -\end{itemize} -% $Id: extending.txt 517 2006-06-10 16:18:11Z gward $ - |