diff options
Diffstat (limited to 'Doc/lib/liboptparse.tex')
| -rw-r--r-- | Doc/lib/liboptparse.tex | 2096 |
1 files changed, 904 insertions, 1192 deletions
diff --git a/Doc/lib/liboptparse.tex b/Doc/lib/liboptparse.tex index c99d235..bc3186f 100644 --- a/Doc/lib/liboptparse.tex +++ b/Doc/lib/liboptparse.tex @@ -1,27 +1,23 @@ -\section{\module{optparse} --- - Powerful parser for command line options.} - +\section{\module{optparse} --- More powerful command line option parser} \declaremodule{standard}{optparse} \moduleauthor{Greg Ward}{gward@python.net} -\sectionauthor{Johannes Gijsbers}{jlgijsbers@users.sf.net} -\sectionauthor{Greg Ward}{gward@python.net} - -\modulesynopsis{Powerful, flexible, extensible, easy-to-use command-line - parsing library.} - +\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). -The \module{optparse} module is a powerful, flexible, extensible, -easy-to-use command-line parsing library for Python. Using -\module{optparse}, you can add intelligent, sophisticated handling of -command-line options to your scripts with very little overhead. - -Here's an example of using \module{optparse} to add some command-line -options to a simple script: +\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") @@ -29,347 +25,361 @@ 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() +(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: - +``usual thing'' on the command-line, for example: \begin{verbatim} -$ <yourscript> -f outfile --quiet -$ <yourscript> -qfoutfile -$ <yourscript> --file=outfile -q -$ <yourscript> --quiet --file outfile +<yourscript> --file=outfile -q \end{verbatim} -(All of these result in \code{options.filename == "outfile"} and -\code{options.verbose == False}, just as you might expect.) +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} -Even niftier, users can run one of +Additionally, users can run one of \begin{verbatim} -$ <yourscript> -h -$ <yourscript> --help +<yourscript> -h +<yourscript> --help \end{verbatim} -and \module{optparse} will print out a brief summary of your script's -options: +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 - -fFILE, --file=FILE write report to FILE - -q, --quiet don't print status messages to stdout + -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} -That's just a taste of the flexibility \module{optparse} gives you in -parsing your command-line. +where the value of \emph{yourscript} is determined at runtime (normally +from \code{sys.argv{[}0]}). +% $Id$ -\subsection{Philosophy\label{optparse-philosophy}} -The purpose of \module{optparse} is to make it very easy to provide the -most standard, obvious, straightforward, and user-friendly user -interface for \UNIX{} command-line programs. The \module{optparse} -philosophy is heavily influenced by the \UNIX{} and GNU toolkits, and -this section is meant to explain that philosophy. +\subsection{Background\label{optparse-background}} -\subsubsection{Terminology\label{optparse-terminology}} +\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. -First, we need to establish some terminology. - -\begin{definitions} -\term{argument} -a chunk of text that a user enters on the command-line, and that the -shell passes to \cfunction{execl()} or \cfunction{execv()}. In -Python, arguments are elements of -\code{sys.argv[1:]}. (\code{sys.argv[0]} is the name of the program -being executed; in the context of parsing arguments, it's not very -important.) \UNIX{} shells also use the term ``word''. - -It is occasionally desirable to use 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:]}''. - -\term{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 \programopt{-} followed by a - single letter, e.g. \programopt{-x} or \programopt{-F}. Also, - traditional \UNIX{} syntax allows multiple options to be merged into a - single argument, e.g. \programopt{-x -F} is equivalent to - \programopt{-xF}. The GNU project introduced \longprogramopt{} - followed by a series of hyphen-separated words, - e.g. \longprogramopt{file} or \longprogramopt{dry-run}. These are - the only two option syntaxes provided by \module{optparse}. - - Some other option syntaxes that the world has seen include: +\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. \programopt{-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. \programopt{-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. \programopt{+f}, \programopt{+rgb}. -\item a slash followed by a letter, or a few letters, or a word, e.g. - \programopt{/f}, \programopt{/file}. -\end{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"} -\module{optparse} does not support these option syntaxes, and it never -will. (If you really want to use one of those option syntaxes, you'll -have to subclass \class{OptionParser} and override all the difficult -bits. But please don't! \module{optparse} does things the traditional -\UNIX/GNU way deliberately; the first three are non-standard anywhere, -and the last one makes sense only if you're exclusively targeting -MS-DOS/Windows and/or VMS.) +\item {} +a slash followed by a letter, or a few letters, or a word, e.g. +\code{"/f"}, \code{"/file"} + +\end{itemize} -\term{option argument} +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 the option is. -Often, option arguments may also be included in the same argument as -the option, e.g. : +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} - ["-f", "foo"] +-ffoo +--file=foo \end{verbatim} -may be equivalent to: +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} - ["-ffoo"] +prog -v --report /tmp/report.txt foo bar \end{verbatim} -(\module{optparse} supports this syntax.) - -Some options never take an argument. Some options always take an -argument. 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 \programopt{-a} and \programopt{-b} are both -options, and \programopt{-a} takes an optional argument, how do we -interpret \programopt{-ab}? \module{optparse} does not support optional -option arguments. +\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. -\term{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. -\term{required option} -an option that must be supplied on the command-line. The phrase -``required option'' is an oxymoron; the presence of ``required options'' -in a program is usually a sign of careless user interface design. -\module{optparse} doesn't prevent you from implementing required -options, but doesn't give you much help with it either. See ``Extending -Examples'' (section~\ref{optparse-extending-examples}) for two ways to -implement required options with \module{optparse}. +\subsubsection{What are options for?\label{optparse-what-are-options-for?}} -\end{definitions} +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.) -For example, consider this hypothetical command-line: +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} - prog -v --report /tmp/report.txt foo bar +cp SOURCE DEST +cp SOURCE ... DEST-DIR \end{verbatim} -\programopt{-v} and \longprogramopt{report} are both options. Assuming -the \longprogramopt{report} option takes one argument, -\code{/tmp/report.txt} is an option argument. \code{foo} and \code{bar} -are positional arguments. +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 options for?\label{optparse-options}} -Options are used to provide extra information to tune or customize the -execution of a program. In case it wasn't clear, options should be -\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 only exceptions I can think of are \program{find}, \program{tar}, -and \program{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. (However, if you insist on adding ``required options'' to your -programs, look in ``Extending Examples'' -(section~\ref{optparse-extending-examples}) for two ways of -implementing them with \module{optparse}.) - -Consider the humble \program{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, \program{cp} fails if you -run it with no arguments. However, it has a flexible, useful syntax -that does not rely on options at all: - -\begin{verbatim} -$ cp SOURCE DEST -$ cp SOURCE ... DEST-DIR -\end{verbatim} - -You can get pretty far with just that. Most \program{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 \program{cp}, which is -to copy one file to another, or N files to another directory. - -\subsubsection{What are positional arguments for? \label{optparse-positional-arguments}} - -In case it wasn't clear from the above example: positional arguments -are for those pieces of information that your program absolutely, -positively requires to run. +\subsubsection{What are positional arguments for?\label{optparse-what-are-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 +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, a GUI, or whatever: -if you make that many demands on your users, most of them will just give -up. +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 +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, checkboxes 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. It's quite easy to overwhelm users (and -yourself!) with too much flexibility, so be careful there. +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$ -\subsection{Basic Usage\label{optparse-basic-usage}} -While \module{optparse} is quite flexible and powerful, you don't have -to jump through hoops or read reams of documentation to get it working -in basic cases. This document aims to demonstrate some simple usage -patterns that will get you started using \module{optparse} in your -scripts. +\subsection{Tutorial\label{optparse-tutorial}} -To parse a command line with \module{optparse}, you must create an -\class{OptionParser} instance and populate it. Obviously, you'll have -to import the \class{OptionParser} classes in any script that uses -\module{optparse}: +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} -Early on in the main program, create a parser: - +Then you can start defining options. The basic syntax is: \begin{verbatim} -parser = OptionParser() +parser.add_option(opt_str, ..., + attr=value, ...) \end{verbatim} -Then you can start populating the parser with options. Each option is -really a set of synonymous option strings; most commonly, you'll have -one short option string and one long option string --- -e.g. \programopt{-f} and \longprogramopt{file}: +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} -The interesting stuff, of course, is what comes after the option -strings. For now, we'll only cover four of the things you can put -there: \emph{action}, \emph{type}, \emph{dest} (destination), and -\emph{help}. +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. -\subsubsection{The \emph{store} action% - \label{optparse-store-action}} - -The action tells \module{optparse} what to do when it sees one of the -option strings for this option on the command-line. For example, the -action \emph{store} means: 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, let's fill in the ``...'' of that last option: +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} -parser.add_option("-f", "--file", - action="store", type="string", dest="filename") +(options, args) = parser.parse_args() \end{verbatim} -Now let's make up a fake command-line and ask \module{optparse} to -parse it: +(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:]}.) -\begin{verbatim} -args = ["-f", "foo.txt"] -options, args = parser.parse_args(args) -\end{verbatim} +\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{Option actions\label{optparse-option-actions}} -(Note that if you don't pass an argument list to -\function{parse_args()}, it automatically uses \code{sys.argv[1:]}.) +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}. -When \module{optparse} sees the \programopt{-f}, it consumes the next -argument---\code{foo.txt}---and stores it in the \member{filename} -attribute of a special object. That object is the first return value -from \function{parse_args()}, so: +If you don't specify an option action, \module{optparse} defaults to \code{store}. + +\subsubsection{The store action\label{optparse-the-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} -print options.filename +parser.add_option("-f", "--file", + action="store", type="string", dest="filename") \end{verbatim} -will print \code{foo.txt}. +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} -Other option types supported by \module{optparse} are \code{int} and -\code{float}. Here's an option that expects an integer argument: +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} -This example doesn't provide a long option, which is perfectly -acceptable. It also doesn't specify the action---it defaults to -``store''. - -Let's parse another fake command-line. This time, we'll jam the option -argument right up against the option, since \programopt{-n42} (one -argument) is equivalent to \programopt{-n 42} (two arguments). +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"]) +(options, args) = parser.parse_args(["-n42"]) print options.num \end{verbatim} -This prints \code{42}. - -Trying out the ``float'' type is left as an exercise for the reader. - -If you don't specify a type, \module{optparse} assumes ``string''. -Combined with the fact that the default action is ``store'', that -means our first example can be a lot shorter: +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 \longprogramopt{foo-bar}, then the default destination is -\member{foo_bar}. If there are no long option strings, -\module{optparse} looks at the first short option: the default -destination for \programopt{-f} is \member{f}. +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}. -Adding types is fairly easy; please refer to -section~\ref{optparse-adding-types}, ``Adding new types.'' +\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{Other \emph{store_*} actions% - \label{optparse-other-store-actions}} -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, ``store_true'' and ``store_false''. For -example, you might have a \var{verbose} flag that is turned on with -\programopt{-v} and off with \programopt{-q}: +\subsubsection{Handling flag (boolean) options\label{optparse-handling-flag-(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") @@ -377,61 +387,86 @@ parser.add_option("-q", action="store_false", dest="verbose") 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.) +default values{---}see section~\ref{optparse-default-values}, Default values, below.) -When \module{optparse} sees \programopt{-v} on the command line, it sets -\code{options.verbose} to \code{True}; when it sees \programopt{-q}, it -sets \code{options.verbose} to \code{False}. +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{Setting default values\label{optparse-setting-default-values}} -All of the above examples involve setting some variable (the -``destination'') when certain command-line options are seen. What -happens if those options are never seen? Since we didn't supply any -defaults, they are all set to \code{None}. Sometimes, this is just fine (which -is why it's the default), but sometimes, you want more control. To -address that need, \module{optparse} lets you supply a default value for -each destination, which is assigned before the command-line is parsed. +\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 the section~\ref{None}, Reference Guide and section~\ref{None}, Option Callbacks +documents. -First, consider the verbose/quiet example. If we want -\module{optparse} to set \member{verbose} to \code{True} unless -\programopt{-q} is seen, then we can do this: +\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} -Oddly enough, this is exactly equivalent: - +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} -Those are equivalent because you're supplying a default value for the -option's \emph{destination}, and these two options happen to have the same -destination (the \member{verbose} variable). - 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 \member{verbose} will be \code{True}: the last +Again, the default value for \var{verbose} will be \code{True}: the last default value supplied for any particular destination is the one that counts. -\subsubsection{Generating help\label{optparse-generating-help}} +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} -The last feature that you will use in every script is -\module{optparse}'s ability to generate help messages. All you have -to do is supply a \var{help} argument when you add an option. Let's -create a new parser and populate it with user-friendly (documented) -options: +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) @@ -441,317 +476,314 @@ parser.add_option("-v", "--verbose", parser.add_option("-q", "--quiet", action="store_false", dest="verbose", help="be vewwy quiet (I'm hunting wabbits)") -parser.add_option("-f", "--file", dest="filename", +parser.add_option("-f", "--filename", metavar="FILE", help="write output to FILE"), parser.add_option("-m", "--mode", default="intermediate", - help="interaction mode: one of 'novice', " - "'intermediate' [default], 'expert'") + help="interaction mode: novice, intermediate, " + "or expert [default: %default]") \end{verbatim} -If \module{optparse} encounters either \programopt{-h} or -\longprogramopt{help} on the command-line, or if you just call -\method{parser.print_help()}, it prints the following to stdout: - +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) - -fFILE, --file=FILE write output to FILE - -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate' - [default], 'expert' + -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} -There's a lot going on here to help \module{optparse} generate the -best possible help message: +(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: - +\item {} +the script defines its own usage message: \begin{verbatim} usage = "usage: %prog [options] arg1 arg2" \end{verbatim} -\module{optparse} expands \samp{\%prog} in the usage string to the name of the -current script, i.e. \code{os.path.basename(sys.argv[0])}. The -expanded string is then printed before the detailed option help. +\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. +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 {} +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 +\item {} +options that take a value indicate this fact in their automatically-generated help message, e.g. for the ``mode'' option: - \begin{verbatim} --mMODE, --mode=MODE +-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 \var{filename} option explicitly sets -\code{metavar="FILE"}, resulting in this automatically-generated -option description: - +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} --fFILE, --file=FILE +-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 formal syntax -``-fFILE'' 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. +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} -When dealing with many options, it is convenient to group these -options for better help output. An \class{OptionParser} can contain -several option groups, each of which can contain several options. -Continuing with the parser defined above, adding an -\class{OptionGroup} to a parser is easy: +\subsubsection{Printing a version string\label{optparse-printing-a-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} -group = OptionGroup(parser, "Dangerous Options", - "Caution: use these options at your own risk. " - "It is believed that some of them bite.") -group.add_option("-g", action="store_true", help="Group option.") -parser.add_option_group(group) +parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0") \end{verbatim} -This would result in the following help output: +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} -usage: [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) - -fFILE, --file=FILE write output to FILE - -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate' - [default], 'expert' - - Dangerous Options: - Caution: use of these options is at your own risk. It is believed that - some of them bite. - -g Group option. +$ /usr/bin/foo --version +foo 1.0 \end{verbatim} -\subsubsection{Print a version number\label{optparse-print-version}} - -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 \var{version} argument to \class{OptionParser}: +\subsubsection{Error-handling\label{optparse-error-handling}} -\begin{verbatim} -parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0") +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} -\var{version} can contain anything you like; \code{\%prog} is expanded -in \var{version} just as with \var{usage}. When you supply it, -\module{optparse} automatically adds a \longprogramopt{version} option -to your parser. If it encounters this option on the command line, it -expands your \var{version} string (by replacing \code{\%prog}), prints -it to stdout, and exits. +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. -For example, if your script is called /usr/bin/foo, a user might do: +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 --version -foo 1.0 -\end{verbatim} % $ (avoid confusing emacs) +$ /usr/bin/foo -n +usage: foo [options] -\subsubsection{Error-handling\label{optparse-error-handling}} +foo: error: -n option requires an argument +\end{verbatim} -The one thing you need to know for basic usage is how -\module{optparse} behaves when it encounters an error on the -command-line---e.g. \programopt{-n 4x} where \programopt{-n} is an -integer-valued option. In this case, \module{optparse} prints your -usage message to stderr, followed by a useful and human-readable error -message. Then it terminates (calls \function{sys.exit()}) with a -non-zero exit status. +\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 you don't like this, subclass \class{OptionParser} and override the -\method{error()} method. See section~\ref{optparse-extending}, -``Extending \module{optparse}.'' +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-basic-summary}} -Here's what \module{optparse}-based scripts typically look like: +\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 [-f] [-v] [-q] firstarg secondarg" + usage = "usage: %prog [options] arg" parser = OptionParser(usage) - parser.add_option("-f", "--file", type="string", dest="filename", + 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) != 2: + [...] + (options, args) = parser.parse_args() + if len(args) != 1: parser.error("incorrect number of arguments") - if options.verbose: print "reading %s..." % options.filename - [... go to work ...] + [...] if __name__ == "__main__": main() \end{verbatim} +% $Id$ -\subsection{Advanced Usage\label{optparse-advanced-usage}} -\subsubsection{Creating and populating the - parser\label{optparse-creating-the-parser}} +\subsection{Reference Guide\label{optparse-reference-guide}} -There are several ways to populate the parser with options. One way -is to pass a list of \class{Options} to the \class{OptionParser} -constructor: +\subsubsection{Populating the parser\label{optparse-populating-the-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{None}, the tutorial section. \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} -from optparse import OptionParser, make_option -[...] -parser = OptionParser(option_list=[ +option_list = [ make_option("-f", "--filename", action="store", type="string", dest="filename"), make_option("-q", "--quiet", - action="store_false", dest="verbose")]) + action="store_false", dest="verbose"), + ] +parser = OptionParser(option_list=option_list) \end{verbatim} -(\function{make_option()} is a factory function for generating -\class{Option} objects.) +(\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.) -For long option lists, it may be more convenient/readable to create the -list separately: -\begin{verbatim} -option_list = [make_option("-f", "--filename", - action="store", type="string", dest="filename"), - [... more options ...] - make_option("-q", "--quiet", - action="store_false", dest="verbose")] -parser = OptionParser(option_list=option_list) -\end{verbatim} +\subsubsection{Defining options\label{optparse-defining-options}} -Or, you can use the \method{add_option()} method of -\class{OptionParser} to add options one-at-a-time: +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} -parser = OptionParser() -parser.add_option("-f", "--filename", - action="store", type="string", dest="filename") -parser.add_option("-q", "--quiet", - action="store_false", dest="verbose") +make_option(opt_str, ..., attr=value, ...) +parser.add_option(opt_str, ..., attr=value, ...) \end{verbatim} -This method makes it easier to track down exceptions raised by the -\class{Option} constructor, which are common because of the complicated -interdependencies among the various keyword arguments. (If you get it -wrong, \module{optparse} raises \exception{OptionError}.) - -\method{add_option()} can be called in one of two ways: - -\begin{itemize} -\item pass it an \class{Option} instance (as returned by \function{make_option()}) -\item pass it any combination of positional and keyword arguments that -are acceptable to \function{make_option()} (i.e., to the \class{Option} -constructor), and it will create the \class{Option} instance for you -(shown above). -\end{itemize} - -\subsubsection{Defining options\label{optparse-defining-options}} - -Each \class{Option} instance represents a set of synonymous -command-line options, i.e. options that have the same meaning and -effect, but different spellings. You can specify any number of short -or long option strings, but you must specify at least one option -string. - To define an option with only a short option string: - \begin{verbatim} -make_option("-f", ...) +make_option("-f", attr=value, ...) \end{verbatim} And to define an option with only a long option string: - \begin{verbatim} -make_option("--foo", ...) -\end{verbatim} - -The ``...'' represents a set of keyword arguments that define attributes -of the \class{Option} object. The rules governing which keyword args -you must supply for a given \class{Option} are fairly complicated, but -you always have to supply \emph{some}. If you get it wrong, -\module{optparse} raises an \exception{OptionError} exception explaining -your mistake. - -The most important attribute of an option is its action, i.e. what to do -when we encounter this option on the command-line. The possible actions -are: - -\begin{tableii}{l|l}{code}{Action}{Meaning} -\lineii{store}{store this option's argument (default)} -\lineii{store_const}{store a constant value} -\lineii{store_true}{store a true value} -\lineii{store_false}{store a false value} -\lineii{append}{append this option's argument to a list} -\lineii{count}{increment a counter by one} -\lineii{callback}{call a specified function} -\lineii{help}{print a usage message including all options and the - documentation for them} -\end{tableii} - -(If you don't supply an action, the default is ``store''. For this -action, you may also supply \var{type} and \var{dest} keywords; see +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 a particular object (an -instance of the \class{Values} class) specifically for this -purpose. Option arguments (and various other values) are stored as -attributes of this object, according to the \var{dest} (destination) -argument to \function{make_option()}/\method{add_option()}. - -For example, when you call: +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 a -\code{values} object: - +one of the first things \module{optparse} does is create the \var{options} object: \begin{verbatim} -values = Values() +options = Values() \end{verbatim} -If one of the options in this parser is defined with: - +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 @@ -759,174 +791,157 @@ and the command-line being parsed includes any of the following: --file foo \end{verbatim} -then \module{optparse}, on seeing the \programopt{-f} or -\longprogramopt{file} option, will do the equivalent of this: - +then \module{optparse}, on seeing the \programopt{-f} or \longprogramopt{file} option, will do the +equivalent of \begin{verbatim} - values.filename = "foo" +options.filename = "foo" \end{verbatim} -Clearly, the \var{type} and \var{dest} arguments are almost -as important as \var{action}. \var{action} is the only attribute that -is meaningful for \emph{all} options, though, so it is the most -important. +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{Option actions\label{optparse-option-actions}} -The various option actions all have slightly different requirements -and effects. Except for the ``help'' action, you must supply at least -one other keyword argument when creating the \class{Option}; the exact -requirements for each action are listed here. +\subsubsection{Option actions\label{optparse-option-actions}} -\begin{definitions} -\term{store} [relevant: \var{type}, \var{dest}, \var{nargs}, \var{choices}] +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 \var{type} and stored in \var{dest}. If -\code{nargs > 1}, multiple arguments will be consumed from the command -line; all will be converted according to \var{type} and stored to -\var{dest} as a tuple. See section~\ref{optparse-option-types}, -``Option types,'' below. +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 \var{choices} (a sequence of strings) is supplied, the type -defaults to ``choice''. +If \code{choices} is supplied (a list or tuple of strings), the type +defaults to \code{choice}. -If \var{type} is not supplied, it defaults to ``string''. +If \member{type} is not supplied, it defaults to \code{string}. -If \var{dest} is not supplied, \module{optparse} derives a -destination from the first long option strings (e.g., -\longprogramopt{foo-bar} becomes \member{foo_bar}). If there are no long -option strings, \module{optparse} derives a destination from the first -short option string (e.g., \programopt{-f} becomes \member{f}). +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} -make_option("-f") -make_option("-p", type="float", nargs=3, dest="point") +parser.add_option("-f") +parser.add_option("-p", type="float", nargs=3, dest="point") \end{verbatim} -Given the following command line: - +As it parses the command line \begin{verbatim} -f foo.txt -p 1 -3.5 4 -fbar.txt \end{verbatim} -\module{optparse} will set: - +\module{optparse} will set \begin{verbatim} -values.f = "bar.txt" -values.point = (1.0, -3.5, 4.0) +options.f = "foo.txt" +options.point = (1.0, -3.5, 4.0) +options.f = "bar.txt" \end{verbatim} -(Actually, \member{values.f} will be set twice, but only the second -time is visible in the end.) +\item {} +\code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}] -\term{store_const} [required: \var{const}, \var{dest}] - -The \var{const} value supplied to the \class{Option} constructor is -stored in \var{dest}. +The value \code{const} is stored in \member{dest}. Example: - \begin{verbatim} -make_option("-q", "--quiet", - action="store_const", const=0, dest="verbose"), -make_option("-v", "--verbose", - action="store_const", const=1, dest="verbose"), -make_option("--noisy", - action="store_const", const=2, dest="verbose"), +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 \longprogramopt{noisy} is seen, \module{optparse} will set: - +If \code{"-{}-noisy"} is seen, \module{optparse} will set \begin{verbatim} -values.verbose = 2 +options.verbose = 2 \end{verbatim} -\term{store_true} [required: \var{dest}] +\item {} +\code{store{\_}true} {[}relevant: \member{dest}] -A special case of ``store_const'' that stores \code{True} to \var{dest}. +A special case of \code{store{\_}const} that stores a true value +to \member{dest}. -\term{store_false} [required: \var{dest}] +\item {} +\code{store{\_}false} {[}relevant: \member{dest}] -Like ``store_true'', but stores \code{False} +Like \code{store{\_}true}, but stores a false value. Example: - \begin{verbatim} -make_option(None, "--clobber", action="store_true", dest="clobber") -make_option(None, "--no-clobber", action="store_false", dest="clobber") +parser.add_option("--clobber", action="store_true", dest="clobber") +parser.add_option("--no-clobber", action="store_false", dest="clobber") \end{verbatim} -\term{append} [relevant: \var{type}, \var{dest}, \var{nargs}, \var{choices}] +\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 \var{dest}. If no default value for \var{dest} is supplied -(i.e. the default is \code{None}), an empty list is automatically created when -\module{optparse} first encounters this option on the command-line. -If \code{nargs > 1}, multiple arguments are consumed, and a tuple of -length \var{nargs} is appended to \var{dest}. +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 \var{type} and \var{dest} are the same as for the -``store'' action. +The defaults for \member{type} and \member{dest} are the same as for the +\code{store} action. Example: - \begin{verbatim} -make_option("-t", "--tracks", action="append", type="int") +parser.add_option("-t", "--tracks", action="append", type="int") \end{verbatim} -If \programopt{-t3} is seen on the command-line, \module{optparse} does the equivalent of: - +If \code{"-t3"} is seen on the command-line, \module{optparse} does the equivalent of: \begin{verbatim} -values.tracks = [] -values.tracks.append(int("3")) +options.tracks = [] +options.tracks.append(int("3")) \end{verbatim} -If, a little later on, \longprogramopt{tracks=4} is seen, it does: - +If, a little later on, \code{"-{}-tracks=4"} is seen, it does: \begin{verbatim} -values.tracks.append(int("4")) +options.tracks.append(int("4")) \end{verbatim} -See ``Error handling'' (section~\ref{optparse-error-handling}) for -information on how \module{optparse} deals with something like -\longprogramopt{tracks=x}. - -\term{count} [required: \var{dest}] +\item {} +\code{count} {[}relevant: \member{dest}] -Increment the integer stored at \var{dest}. \var{dest} is set to zero -before being incremented the first time (unless you supply a default -value). +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} -make_option("-v", action="count", dest="verbosity") +parser.add_option("-v", action="count", dest="verbosity") \end{verbatim} -The first time \programopt{-v} is seen on the command line, -\module{optparse} does the equivalent of: - +The first time \code{"-v"} is seen on the command line, \module{optparse} does the +equivalent of: \begin{verbatim} -values.verbosity = 0 -values.verbosity += 1 +options.verbosity = 0 +options.verbosity += 1 \end{verbatim} -Every subsequent occurrence of \programopt{-v} results in: - +Every subsequent occurrence of \code{"-v"} results in \begin{verbatim} -values.verbosity += 1 +options.verbosity += 1 \end{verbatim} -\term{callback} [required: \var{callback}; - relevant: \var{type}, \var{nargs}, \var{callback_args}, - \var{callback_kwargs}] - -Call the function specified by \var{callback}. The signature of -this function should be: +\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, @@ -935,42 +950,41 @@ func(option : Option, *args, **kwargs) \end{verbatim} -Callback options are covered in detail in -section~\ref{optparse-callback-options}, ``Callback Options.'' +See section~\ref{None}, Option Callbacks for more detail. -\term{help} [required: none] +\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 \class{OptionParser}'s constructor and the \var{help} -string passed to every option. +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 \var{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 \constant{optparse.SUPPRESS_HELP}. +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}. -Example: +\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 Option, OptionParser, SUPPRESS_HELP +from optparse import OptionParser, SUPPRESS_HELP -usage = "usage: %prog [options]" -parser = OptionParser(usage, option_list=[ - make_option("-h", "--help", action="help"), - make_option("-v", action="store_true", dest="verbose", - help="Be moderately verbose") - make_option("--file", dest="filename", - help="Input file to read data from"), - make_option("--secret", help=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 \programopt{-h} or -\longprogramopt{help} on the command line, it will print something -like the following help message to stdout: - +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: <yourscript> [options] +usage: foo.py [options] options: -h, --help Show this help message and exit @@ -981,431 +995,405 @@ options: After printing the help message, \module{optparse} terminates your process with \code{sys.exit(0)}. -\term{version} [required: none] +\item {} +\code{version} -Prints the version number supplied to the \class{OptionParser} to -stdout and exits. The version number is actually formatted and -printed by the \method{print_version()} method of -\class{OptionParser}. Generally only relevant if the \var{version} -argument is supplied to the \class{OptionParser} constructor. -\end{definitions} +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. -\subsubsection{Option types\label{optparse-option-types}} +\end{itemize} -\module{optparse} supports six option types out of the box: \dfn{string}, -\dfn{int}, \dfn{long}, \dfn{choice}, \dfn{float} and \dfn{complex}. -(Of these, string, int, float, and choice are the most commonly used ----long and complex are there mainly for completeness.) It's easy to -add new option types by subclassing the \class{Option} class; 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 \function{int()} to convert them to -Python integers. If \function{int()} fails, so will -\module{optparse}, although with a more useful error message. -Internally, \module{optparse} raises \exception{OptionValueError} in -\function{optparse.check_builtin()}; at a higher level (in -\class{OptionParser}), \module{optparse} catches this exception and -terminates your program with a useful error message. - -Likewise, float arguments are passed to \function{float()} for -conversion, long arguments to \function{long()}, and complex arguments -to \function{complex()}. Apart from that, they are handled -identically to integer arguments. - -Choice options are a subtype of string options. A master list or -tuple of choices (strings) must be passed to the option constructor -(\function{make_option()} or \method{OptionParser.add_option()}) as -the \var{choices} keyword argument. Choice option arguments are -compared against this master list in -\function{optparse.check_choice()}, and \exception{OptionValueError} -is raised if an unknown string is given. - -\subsubsection{Querying and manipulating your option parser\label{optparse-querying-and-manipulating}} -Sometimes, it's useful to poke around your option parser and see what's -there. \class{OptionParser} provides a couple of methods to help you out: +\subsubsection{Option types\label{optparse-option-types}} -\begin{methoddesc}{has_option}{opt_str} - Given an option string such as \programopt{-q} or - \longprogramopt{verbose}, returns true if the \class{OptionParser} - has an option with that option string. -\end{methoddesc} +\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}. -\begin{methoddesc}{get_option}{opt_str} - Returns the \class{Option} instance that implements the option - string you supplied, or \code{None} if no options implement it. -\end{methoddesc} +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. -\begin{methoddesc}{remove_option}{opt_str} - If the \class{OptionParser} has an option corresponding to - \var{opt_str}, that option is removed. If that option provided - any other option strings, all of those option strings become - invalid. +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.) - If \var{opt_str} does not occur in any option belonging to this - \class{OptionParser}, raises \exception{ValueError}. -\end{methoddesc} +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. -\subsubsection{Conflicts between options\label{optparse-conflicts}} +\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. -If you're not careful, it's easy to define conflicting options: -\begin{verbatim} -parser.add_option("-n", "--dry-run", ...) -... -parser.add_option("-n", "--noisy", ...) -\end{verbatim} +\subsubsection{Querying and manipulating your option parser\label{optparse-querying-and-manipulating-your-option-parser}} -(This is even easier to do if you've defined your own -\class{OptionParser} subclass with some standard options.) +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} -On the assumption that this is usually a mistake, \module{optparse} -raises an exception (\exception{OptionConflictError}) by default when -this happens. Since this is an easily-fixed programming error, you -shouldn't try to catch this exception---fix your mistake and get on -with life. -Sometimes, you want newer options to deliberately replace the option -strings used by older options. You can achieve this by calling: +\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.set_conflict_handler("resolve") +parser.add_option("-n", "--dry-run", ...) +[...] +parser.add_option("-n", "--noisy", ...) \end{verbatim} -which instructs \module{optparse} to resolve option conflicts -intelligently. - -Here's how it works: every time you add an option, \module{optparse} -checks for conflicts with previously-added options. If it finds any, -it invokes the conflict-handling mechanism you specify either to the -\class{OptionParser} constructor: +(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="resolve") +parser = OptionParser(..., conflict_handler="...") \end{verbatim} -or via the \method{set_conflict_handler()} method. - -The default conflict-handling mechanism is \code{error}. - -Here's an example: first, define an \class{OptionParser} set to -resolve conflicts intelligently: - +or with a separate call: \begin{verbatim} -parser = OptionParser(conflict_handler="resolve") +parser.set_conflict_handler("...") \end{verbatim} -Now add all of our options: +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.add_option("-n", "--dry-run", ..., help="original dry-run option") -... +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} +\end{verbatim} At this point, \module{optparse} detects that a previously-added option is already -using the \programopt{-n} option string. Since \code{conflict_handler -== "resolve"}, it resolves the situation by removing \programopt{-n} -from the earlier option's list of option strings. Now, -\longprogramopt{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, e.g.: - +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 original dry-run option - ... + --dry-run do no harm + [...] -n, --noisy be noisy \end{verbatim} -Note that 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. E.g. if we carry on with our -existing \class{OptionParser}: - +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 first \programopt{-n}/\longprogramopt{dry-run} -option is no longer accessible, so \module{optparse} removes it. If -the user asks for help, they'll get something like this: - +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$ + + +\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 -\subsection{Callback Options\label{optparse-callback-options}} +\end{itemize} -If \module{optparse}'s built-in actions and types just don't fit the -bill for you, but it's not worth extending \module{optparse} to define -your own actions or types, you'll probably need to define a callback -option. Defining callback options is quite easy; the tricky part is -writing a good callback (the function that is called when -\module{optparse} encounters the option on the command line). -\subsubsection{Defining a callback option\label{optparse-defining-callback-option}} +\subsubsection{Defining a callback option\label{optparse-defining-a-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} -As always, you can define a callback option either by directly -instantiating the \class{Option} class, or by using the -\method{add_option()} method of your \class{OptionParser} object. The -only option attribute you must specify is \var{callback}, the function -to call: +\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} -parser.add_option("-c", callback=my_callback) +def my_callback(option, opt, value, parser): \end{verbatim} -Note that you supply a function object here---so you must have -already defined a function \function{my_callback()} when you define -the callback option. In this simple case, \module{optparse} knows -nothing about the arguments the \programopt{-c} option expects to -take. Usually, this means that the option doesn't take any 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 document. +The four arguments to a callback are described below. There are several other option attributes that you can supply when you -define an option attribute: - -\begin{definitions} -\term{type} -has its usual meaning: as with the ``store'' or ``append'' actions, it -instructs \module{optparse} to consume one argument that must be -convertible to \var{type}. Rather than storing the value(s) anywhere, -though, \module{optparse} converts it to \var{type} and passes it to -your callback function. - -\term{nargs} -also has its usual meaning: if it is supplied and \samp{nargs > 1}, -\module{optparse} will consume \var{nargs} arguments, each of which -must be convertible to \var{type}. It then passes a tuple of -converted values to your callback. - -\term{callback_args} -a tuple of extra positional arguments to pass to the callback. - -\term{callback_kwargs} -a dictionary of extra keyword arguments to pass to the callback. -\end{definitions} - -\subsubsection{How callbacks are called\label{optparse-callbacks-called}} +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-are-called}} All callbacks are called as follows: - \begin{verbatim} -func(option, opt, value, parser, *args, **kwargs) +func(option, opt_str, value, parser, *args, **kwargs) \end{verbatim} where - -\begin{definitions} -\term{option} -is the \class{Option} instance that's calling the callback. - -\term{opt} +\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, \var{opt} will be -the full, canonical option string---for example, if the user puts -\longprogramopt{foo} on the command-line as an abbreviation for -\longprogramopt{foobar}, then \var{opt} will be -\longprogramopt{foobar}.) - -\term{value} -is the argument to this option seen on the command-line. -\module{optparse} will only expect an argument if \var{type} is -set; the type of \var{value} will be the type implied by the -option's type (see~\ref{optparse-option-types}, ``Option types''). If -\var{type} for this option is \code{None} (no argument expected), then -\var{value} will be \code{None}. If \samp{nargs > 1}, \var{value} will -be a tuple of values of the appropriate type. - -\term{parser} -is the \class{OptionParser} instance driving the whole thing, mainly -useful because you can access some other interesting data through it, -as instance attributes: - -\begin{definitions} -\term{parser.rargs} -the current remaining argument list, i.e. with \var{opt} (and -\var{value}, if any) removed, and only the arguments following -them still there. Feel free to modify \member{parser.rargs}, -e.g. by consuming more arguments. - -\term{parser.largs} -the current set of leftover arguments, i.e. arguments that have been -processed but have not been consumed as options (or arguments to -options). Feel free to modify \member{parser.largs} e.g. by adding -more arguments to it. - -\term{parser.values} -the object where option values are by default stored. This is useful -because it 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 the value(s) of -any options already encountered on the command-line. -\end{definitions} - -\term{args} +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 -\var{callback}_args option attribute. - -\term{kwargs} +\code{callback{\_}args} option attribute. +\item[\code{kwargs}] is a dictionary of arbitrary keyword arguments supplied via -\var{callback_kwargs}. -\end{definitions} +\code{callback{\_}kwargs}. +\end{description} -Since \var{args} and \var{kwargs} are optional (they are only passed -if you supply \var{callback_args} and/or \var{callback_kwargs} when -you define your callback option), the minimal callback function is: -\begin{verbatim} -def my_callback(option, opt, value, parser): - pass -\end{verbatim} +\subsubsection{Error handling\label{optparse-error-handling}} -\subsubsection{Error handling\label{optparse-callback-error-handling}} +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. -The callback function should raise \exception{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{Examples\label{optparse-callback-examples}} +\subsubsection{Callback example 1: trivial callback\label{optparse-callback-example-1:-trivial-callback}} 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, value, parser): - parser.saw_foo = 1 +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 ``store_true'' action. Here's a -slightly more interesting example: record the fact that -\programopt{-a} is seen, but blow up if it comes after \programopt{-b} -in the command-line. +Of course, you could do that with the \code{store{\_}true} action. + +\subsubsection{Callback example 2: check option order\label{optparse-callback-example-2:-check-option-order}} + +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, value, parser): +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} -If you want to reuse this callback for several similar options (set a -flag, but blow up if \programopt{-b} has already been seen), it needs -a bit of work: the error message and the flag that it sets must be -generalized. +\subsubsection{Callback example 3: check option order (generalized)\label{optparse-callback-example-3:-check-option-order-(generalized)}} + +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, value, parser): +def check_order(option, opt_str, value, parser): if parser.values.b: - raise OptionValueError("can't use %s after -b" % opt) + 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} -Of course, you could put any condition in there---you're not limited + +\subsubsection{Callback example 4: check arbitrary condition\label{optparse-callback-example-4:-check-arbitrary-condition}} + +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, value, parser): - if is_full_moon(): - raise OptionValueError("%s option invalid when moon full" % opt) +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_full_moon()} is left as an exercise for the +(The definition of \code{is{\_}moon{\_}full()} is left as an exercise for the reader.) -\strong{Fixed arguments} + +\subsubsection{Callback example 5: fixed arguments\label{optparse-callback-example-5:-fixed-arguments}} 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 ``store'' or -``append'' option: if you define \var{type}, then the option takes one -argument that must be convertible to that type; if you further define -\var{nargs}, then the option takes that many arguments. - -Here's an example that just emulates the standard ``store'' action: +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, value, parser): +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. -Use your imagination!) +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.) -\strong{Variable arguments} -Things get hairy when you want an option to take a variable number of -arguments. For this case, you have to write a callback; -\module{optparse} doesn't provide any built-in capabilities for it. -You have to deal with the full-blown syntax for conventional \UNIX{} -command-line parsing. (Previously, \module{optparse} took care of -this for you, but I got it wrong. It was fixed at the cost of making -this kind of callback more complex.) In particular, callbacks have to -worry about bare \longprogramopt{} and \programopt{-} arguments; the -convention is: +\subsubsection{Callback example 6: variable arguments\label{optparse-callback-example-6:-variable-arguments}} +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 bare \longprogramopt{}, if not the argument to some option, -causes command-line processing to halt and the \longprogramopt{} -itself is lost. +\item {} +either \code{"-{}-"} or \code{"-"} can be option arguments -\item bare \programopt{-} similarly causes command-line processing to -halt, but the \programopt{-} itself is kept. +\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}) -\item either \longprogramopt{} or \programopt{-} can be option -arguments. \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). +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 varargs(option, opt, value, parser): +def vararg_callback(option, opt_str, value, parser): assert value is None done = 0 value = [] @@ -1426,290 +1414,14 @@ def varargs(option, opt, value, parser): 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 \programopt{-c} will be interpreted -as further options, rather than as arguments to \programopt{-c}. -Fixing this is left as an exercise for the reader. - -\subsection{Extending \module{optparse}\label{optparse-extending}} - -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. - -Also, the examples section includes several demonstrations of -extending \module{optparse} in different ways: e.g. a case-insensitive -option parser, or two kinds of option parsers that implement -``required options''. - -\subsubsection{Adding new types\label{optparse-adding-types}} - -To add new types, you need to define your own subclass of -\module{optparse}'s \class{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_foo(option : Option, opt : string, value : string) - -> foo -\end{verbatim} - -You can name it whatever you like, and make it return any type you -like. The value returned by a type-checking function will wind up in -the \class{OptionValues} instance returned by -\method{OptionParser.parse_args()}, or be passed to callbacks as the -\var{value} parameter. - -Your type-checking function should raise \exception{OptionValueError} -if it encounters any problems. \exception{OptionValueError} takes a -single string argument, which is passed as-is to -\class{OptionParser}'s \method{error()} method, which in turn prepends -the program name and the string ``error:'' and prints everything to -stderr before terminating the process. - -Here's a silly example that demonstrates adding a ``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 adds -built-in support for complex numbers [purely for completeness], 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 -\class{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 \class{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 \class{OptionParser} to use \class{MyOption} instead of -\class{Option}: - -\begin{verbatim} -parser = OptionParser(option_class=MyOption) -parser.add_option("-c", action="store", type="complex", dest="c") -\end{verbatim} - -Alternately, you can build your own option list and pass it to -\class{OptionParser}; if you don't use \method{add_option()} in the -above way, you don't need to tell \class{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-actions}} - -Adding new actions is a bit trickier, because you have to understand -that \module{optparse} has a couple of classifications for actions: - -\begin{definitions} -\term{``store'' actions} - actions that result in \module{optparse} storing a value to an attribute - of the OptionValues instance; these options require a \var{dest} - attribute to be supplied to the Option constructor -\term{``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 \var{type} attribute to the - Option constructor. -\end{definitions} - -Some default ``store'' actions are \var{store}, \var{store_const}, -\var{append}, and \var{count}. The default ``typed'' actions are -\var{store}, \var{append}, and \var{callback}. - -When you add an action, you need to decide if it's a ``store'' action, -a ``typed'', neither, or both. Three class attributes of -\class{Option} (or your \class{Option} subclass) control this: - -\begin{memberdesc}{ACTIONS} - All actions must be listed as strings in ACTIONS. -\end{memberdesc} -\begin{memberdesc}{STORE_ACTIONS} - ``store'' actions are additionally listed here. -\end{memberdesc} -\begin{memberdesc}{TYPED_ACTIONS} - ``typed'' actions are additionally listed here. -\end{memberdesc} - -In order to actually implement your new action, you must override -\class{Option}'s \method{take_action()} method and add a case that -recognizes your action. - -For example, let's add an ``extend'' action. This is similar to the -standard ``append'' action, but instead of taking a single value from -the command-line and appending it to an existing list, ``extend'' will -take multiple values in a single comma-delimited string, and extend an -existing list with them. That is, if \longprogramopt{names} is an -``extend'' option of type 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 \class{Option}: - -\begin{verbatim} -class MyOption(Option): - - ACTIONS = Option.ACTIONS + ("extend",) - STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",) - TYPED_ACTIONS = Option.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 ``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 \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 \var{values} is an instance of the \class{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} -\end{itemize} - -If the \member{attr} attribute of \var{values} doesn't exist or is -\code{None}, then \method{ensure_value()} first sets it to \var{value}, and -then returns \var{value}. This is very handy for actions like -``extend'', ``append'', and ``count'', all of which accumulate data in -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 \code{None} and -\method{ensure_value()} will take care of getting it right when it's -needed. - -\subsubsection{Other reasons to extend \module{optparse}\label{optparse-extending-other-reasons}} - -Adding new types and new actions are the big, obvious reasons why you -might want to extend \module{optparse}. I can think of at least two -other areas to play with. - -First, the simple one: \class{OptionParser} tries to be helpful by -calling \function{sys.exit()} when appropriate, i.e. when there's an -error on the command-line or when the user requests help. In the -former case, the traditional course of letting the script crash with a -traceback is unacceptable; it will make users think there's a bug in -your script when they make a command-line error. In the latter case, -there's generally not much point in carrying on after printing a help -message. - -If this behaviour bothers you, it shouldn't be too hard to ``fix'' it. -You'll have to - -\begin{enumerate} -\item subclass OptionParser and override the error() method -\item subclass Option and override the take_action() method---you'll - need to provide your own handling of the ``help'' action that - doesn't call sys.exit() -\end{enumerate} - -The second, much more complex, possibility is to override the -command-line syntax implemented by \module{optparse}. In this case, -you'd leave the whole machinery of option actions and types alone, but -rewrite the code that processes \code{sys.argv}. You'll need to -subclass \class{OptionParser} in any case; depending on how radical a -rewrite you want, you'll probably need to override one or all of -\method{parse_args()}, \method{_process_long_opt()}, and -\method{_process_short_opts()}. - -Both of these are left as an exercise for the reader. I have not -tried to implement either myself, since I'm quite happy with -\module{optparse}'s default behaviour (naturally). - -Happy hacking, and don't forget: Use the Source, Luke. - -\subsubsection{Examples\label{optparse-extending-examples}} - -Here are a few examples of extending the \module{optparse} module. - -First, let's change the option-parsing to be case-insensitive: - -\verbatiminput{caseless.py} - -And two ways of implementing ``required options'' with -\module{optparse}. - -Version 1: Add a method to \class{OptionParser} which applications -must call after parsing arguments: - -\verbatiminput{required_1.py} - -Version 2: Extend \class{Option} and add a \member{required} -attribute; extend \class{OptionParser} to ensure that required options -are present after parsing: - -\verbatiminput{required_2.py} +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$ -\begin{seealso} - \seemodule{getopt}{More traditional \UNIX-style command line option parsing.} -\end{seealso} |