mirror of
https://github.com/python/cpython.git
synced 2024-11-27 03:45:08 +08:00
124 lines
4.5 KiB
TeX
124 lines
4.5 KiB
TeX
\section{\module{getopt} ---
|
|
Parser for command line options}
|
|
|
|
\declaremodule{standard}{getopt}
|
|
\modulesynopsis{Portable parser for command line options; support both
|
|
short and long option names.}
|
|
|
|
|
|
This module helps scripts to parse the command line arguments in
|
|
\code{sys.argv}.
|
|
It supports the same conventions as the \UNIX{} \cfunction{getopt()}
|
|
function (including the special meanings of arguments of the form
|
|
`\code{-}' and `\code{-}\code{-}').
|
|
% That's to fool latex2html into leaving the two hyphens alone!
|
|
Long options similar to those supported by
|
|
GNU software may be used as well via an optional third argument.
|
|
This module provides a single function and an exception:
|
|
|
|
\begin{funcdesc}{getopt}{args, options\optional{, long_options}}
|
|
Parses command line options and parameter list. \var{args} is the
|
|
argument list to be parsed, without the leading reference to the
|
|
running program. Typically, this means \samp{sys.argv[1:]}.
|
|
\var{options} is the string of option letters that the script wants to
|
|
recognize, with options that require an argument followed by a colon
|
|
(\character{:}; i.e., the same format that \UNIX{}
|
|
\cfunction{getopt()} uses).
|
|
|
|
\var{long_options}, if specified, must be a list of strings with the
|
|
names of the long options which should be supported. The leading
|
|
\code{'-}\code{-'} characters should not be included in the option
|
|
name. Long options which require an argument should be followed by an
|
|
equal sign (\character{=}). To accept only long options,
|
|
\var{options} should be an empty string. Long options on the command
|
|
line can be recognized so long as they provide a prefix of the option
|
|
name that matches exactly one of the accepted options. For example,
|
|
it \var{long_options} is \code{['foo', 'frob']}, the option
|
|
\longprogramopt{fo} will match as \longprogramopt{foo}, but
|
|
\longprogramopt{f} will not match uniquely, so \exception{GetoptError}
|
|
will be raised.
|
|
|
|
The return value consists of two elements: the first is a list of
|
|
\code{(\var{option}, \var{value})} pairs; the second is the list of
|
|
program arguments left after the option list was stripped (this is a
|
|
trailing slice of \var{args}). Each option-and-value pair returned
|
|
has the option as its first element, prefixed with a hyphen for short
|
|
options (e.g., \code{'-x'}) or two hyphens for long options (e.g.,
|
|
\code{'-}\code{-long-option'}), and the option argument as its second
|
|
element, or an empty string if the option has no argument. The
|
|
options occur in the list in the same order in which they were found,
|
|
thus allowing multiple occurrences. Long and short options may be
|
|
mixed.
|
|
\end{funcdesc}
|
|
|
|
\begin{excdesc}{GetoptError}
|
|
This is raised when an unrecognized option is found in the argument
|
|
list or when an option requiring an argument is given none.
|
|
The argument to the exception is a string indicating the cause of the
|
|
error. For long options, an argument given to an option which does
|
|
not require one will also cause this exception to be raised. The
|
|
attributes \member{msg} and \member{opt} give the error message and
|
|
related option; if there is no specific option to which the exception
|
|
relates, \member{opt} is an empty string.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{error}
|
|
Alias for \exception{GetoptError}; for backward compatibility.
|
|
\end{excdesc}
|
|
|
|
|
|
An example using only \UNIX{} style options:
|
|
|
|
\begin{verbatim}
|
|
>>> import getopt
|
|
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
|
|
>>> args
|
|
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
|
|
>>> optlist, args = getopt.getopt(args, 'abc:d:')
|
|
>>> optlist
|
|
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
|
|
>>> args
|
|
['a1', 'a2']
|
|
\end{verbatim}
|
|
|
|
Using long option names is equally easy:
|
|
|
|
\begin{verbatim}
|
|
>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
|
|
>>> args = s.split()
|
|
>>> args
|
|
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
|
|
>>> optlist, args = getopt.getopt(args, 'x', [
|
|
... 'condition=', 'output-file=', 'testing'])
|
|
>>> optlist
|
|
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
|
|
'')]
|
|
>>> args
|
|
['a1', 'a2']
|
|
\end{verbatim}
|
|
|
|
In a script, typical usage is something like this:
|
|
|
|
\begin{verbatim}
|
|
import getopt, sys
|
|
|
|
def main():
|
|
try:
|
|
opts, args = getopt.getopt(sys.argv[1:], "ho:", ["help", "output="])
|
|
except getopt.GetoptError:
|
|
# print help information and exit:
|
|
usage()
|
|
sys.exit(2)
|
|
output = None
|
|
for o, a in opts:
|
|
if o in ("-h", "--help"):
|
|
usage()
|
|
sys.exit()
|
|
if o in ("-o", "--output"):
|
|
output = a
|
|
# ...
|
|
|
|
if __name__ == "__main__":
|
|
main()
|
|
\end{verbatim}
|