| \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 |
| \var{options} object returned by \method{parse{\_}args()} based on user-supplied |
| command-line values. When \method{parse{\_}args()} returns from parsing this |
| command line, \var{options.filename} will be \code{"outfile"} and |
| \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 {} |
| \var{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then |
| \var{options.file} will be the filename supplied by the user, or |
| \code{None} if the user did not supply that option |
| |
| \item {} |
| \var{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}, Extending \module{optparse}. |
| Most actions tell \module{optparse} to store a value in some variable{---}for |
| example, take a string from the command line and store it in an |
| attribute of \var{options}. |
| |
| 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 \var{options.filename}. So, |
| after this call to \method{parse{\_}args()}, \var{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}, 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 |
| \var{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 |
| \var{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 \var{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} |
| |
| Note that \code{"{\%}prog"} is expanded just like it is in \var{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-optik-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{parse.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 415 2004-09-30 02:26:17Z greg $ |
| |
| |
| \subsection{Reference Guide\label{optparse-reference-guide}} |
| |
| |
| \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 by calling |
| \function{make{\_}option()}, so that is what will be shown here. However, the |
| most common and convenient way is to use \code{parser.add{\_}option()}. Note |
| that \function{make{\_}option()} and \code{parser.add{\_}option()} have identical call |
| signatures: |
| \begin{verbatim} |
| make_option(opt_str, ..., attr=value, ...) |
| parser.add_option(opt_str, ..., attr=value, ...) |
| \end{verbatim} |
| |
| To define an option with only a short option string: |
| \begin{verbatim} |
| make_option("-f", attr=value, ...) |
| \end{verbatim} |
| |
| And to define an option with only a long option string: |
| \begin{verbatim} |
| make_option("--foo", attr=value, ...) |
| \end{verbatim} |
| |
| The \code{attr=value} keyword arguments define option attributes, |
| i.e. attributes of the Option object. The most important option |
| attribute is \member{action}, and it largely determines what other attributes |
| are relevant or required. If you pass irrelevant option attributes, or |
| fail to pass required ones, \module{optparse} raises an OptionError exception |
| explaining your mistake. |
| |
| An options's \emph{action} determines what \module{optparse} does when it encounters |
| this option on the command-line. The actions hard-coded into \module{optparse} are: |
| \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{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 an instance of \code{optparse.Values} |
| specifically for this purpose; we refer to this instance as \var{options}. |
| Option arguments (and various other values) are stored as attributes of |
| this object, according to the \member{dest} (destination) option attribute. |
| |
| For example, when you call |
| \begin{verbatim} |
| parser.parse_args() |
| \end{verbatim} |
| |
| one of the first things \module{optparse} does is create the \var{options} object: |
| \begin{verbatim} |
| options = Values() |
| \end{verbatim} |
| |
| If one of the options in this parser is defined with |
| \begin{verbatim} |
| make_option("-f", "--file", action="store", type="string", dest="filename") |
| \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 the \programopt{-f} or \longprogramopt{file} 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{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}. The signature of |
| this function should be |
| \begin{verbatim} |
| func(option : Option, |
| opt : string, |
| value : any, |
| parser : OptionParser, |
| *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 \var{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{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}, 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 are passed to \code{int()} to convert them to Python |
| integers. If \code{int()} fails, so will \module{optparse}, although with a more |
| useful error message. (Internally, \module{optparse} raises OptionValueError; |
| OptionParser catches this exception higher up and terminates your |
| program with a useful error message.) |
| |
| Likewise, \code{float} arguments are passed to \code{float()} for conversion, |
| \code{long} arguments to \code{long()}, and \code{complex} arguments to |
| \code{complex()}. Apart from that, they are handled identically to integer |
| arguments. |
| |
| \code{choice} options are a subtype of \code{string} options. The \code{choices} |
| option attribute (a sequence of strings) defines the set of allowed |
| option arguments. \code{optparse.option.check{\_}choice()} compares |
| user-supplied option arguments against this master list and raises |
| OptionValueError if an invalid string is given. |
| |
| |
| \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="...") |
| \end{verbatim} |
| |
| or with a separate call: |
| \begin{verbatim} |
| parser.set_conflict_handler("...") |
| \end{verbatim} |
| |
| The available conflict-handling mechanisms 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} |
| % $Id: reference.txt 415 2004-09-30 02:26:17Z greg $ |
| |
| |
| \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 \var{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[\var{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 $ |
| |