diff options
Diffstat (limited to 'Doc/library/getopt.rst')
| -rw-r--r-- | Doc/library/getopt.rst | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst new file mode 100644 index 0000000..0d9641d --- /dev/null +++ b/Doc/library/getopt.rst @@ -0,0 +1,147 @@ + +:mod:`getopt` --- Parser for command line options +================================================= + +.. module:: getopt + :synopsis: Portable parser for command line options; support both short and long option + names. + + +This module helps scripts to parse the command line arguments in ``sys.argv``. +It supports the same conventions as the Unix :cfunc:`getopt` function (including +the special meanings of arguments of the form '``-``' and '``-``\ ``-``'). 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: + +.. % That's to fool latex2html into leaving the two hyphens alone! + + +.. function:: getopt(args, options[, long_options]) + + Parses command line options and parameter list. *args* is the argument list to + be parsed, without the leading reference to the running program. Typically, this + means ``sys.argv[1:]``. *options* is the string of option letters that the + script wants to recognize, with options that require an argument followed by a + colon (``':'``; i.e., the same format that Unix :cfunc:`getopt` uses). + + .. note:: + + Unlike GNU :cfunc:`getopt`, after a non-option argument, all further arguments + are considered also non-options. This is similar to the way non-GNU Unix systems + work. + + *long_options*, if specified, must be a list of strings with the names of the + long options which should be supported. The leading ``'-``\ ``-'`` characters + should not be included in the option name. Long options which require an + argument should be followed by an equal sign (``'='``). To accept only long + options, *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, if *long_options* is + ``['foo', 'frob']``, the option :option:`--fo` will match as :option:`--foo`, + but :option:`--f` will not match uniquely, so :exc:`GetoptError` will be raised. + + The return value consists of two elements: the first is a list of ``(option, + value)`` pairs; the second is the list of program arguments left after the + option list was stripped (this is a trailing slice of *args*). Each + option-and-value pair returned has the option as its first element, prefixed + with a hyphen for short options (e.g., ``'-x'``) or two hyphens for long + options (e.g., ``'-``\ ``-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. + + +.. function:: gnu_getopt(args, options[, long_options]) + + This function works like :func:`getopt`, except that GNU style scanning mode is + used by default. This means that option and non-option arguments may be + intermixed. The :func:`getopt` function stops processing options as soon as a + non-option argument is encountered. + + If the first character of the option string is '+', or if the environment + variable POSIXLY_CORRECT is set, then option processing stops as soon as a + non-option argument is encountered. + + .. versionadded:: 2.3 + + +.. exception:: 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 :attr:`msg` and :attr:`opt` give the error message and + related option; if there is no specific option to which the exception relates, + :attr:`opt` is an empty string. + + .. versionchanged:: 1.6 + Introduced :exc:`GetoptError` as a synonym for :exc:`error`. + + +.. exception:: error + + Alias for :exc:`GetoptError`; for backward compatibility. + +An example using only Unix style options:: + + >>> 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'] + +Using long option names is equally easy:: + + >>> 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'] + +In a script, typical usage is something like this:: + + import getopt, sys + + def main(): + try: + opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="]) + except getopt.GetoptError as err: + # print help information and exit: + print str(err) # will print something like "option -a not recognized" + usage() + sys.exit(2) + output = None + verbose = False + for o, a in opts: + if o == "-v": + verbose = True + elif o in ("-h", "--help"): + usage() + sys.exit() + elif o in ("-o", "--output"): + output = a + else: + assert False, "unhandled option" + # ... + + if __name__ == "__main__": + main() + + +.. seealso:: + + Module :mod:`optparse` + More object-oriented command line option parsing. + |