| |
| .. 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 |
n | the special meanings of arguments of the form '``-``' and '``-``\ ``-``'). Long |
n | 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 |
n | optional third argument. This module provides a single function and an |
n | optional third argument. |
| |
| A more convenient, flexible, and powerful alternative is the |
| :mod:`optparse` module. |
| |
| This module provides two functions and an |
| exception: |
n | |
| .. % 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 |
| 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 |
n | option list was stripped (this is a trailing slice of *args*). Each option-and- |
n | option list was stripped (this is a trailing slice of *args*). Each |
| value pair returned has the option as its first element, prefixed with a hyphen |
| option-and-value pair returned has the option as its first element, prefixed |
| for short options (e.g., ``'-x'``) or two hyphens for long options (e.g., |
| with a hyphen for short options (e.g., ``'-x'``) or two hyphens for long |
| ``'-``\ ``-long-option'``), and the option argument as its second element, or an |
| options (e.g., ``'-``\ ``-long-option'``), and the option argument as its |
| empty string if the option has no argument. The options occur in the list in |
| second element, or an empty string if the option has no argument. The |
| the same order in which they were found, thus allowing multiple occurrences. |
| options occur in the list in the same order in which they were found, thus |
| Long and short options may be mixed. |
| 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 |
n | variable POSIXLY_CORRECT is set, then option processing stops as soon as a non- |
n | variable :envvar:`POSIXLY_CORRECT` is set, then option processing stops as |
| option argument is encountered. |
| 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 |
| .. versionchanged:: 1.6 |
| Introduced :exc:`GetoptError` as a synonym for :exc:`error`. |
| |
| |
| .. exception:: error |
| |
| Alias for :exc:`GetoptError`; for backward compatibility. |
| |
n | An example using only Unix style options:: |
n | 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'] |
| |
n | Using long option names is equally easy:: |
n | 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 |
n | [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', |
n | [('--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="]) |
n | except getopt.GetoptError: |
n | except getopt.GetoptError, err: |
| # print help information and exit: |
n | 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 |
n | if o in ("-h", "--help"): |
n | elif o in ("-h", "--help"): |
| usage() |
| sys.exit() |
n | if o in ("-o", "--output"): |
n | elif o in ("-o", "--output"): |
| output = a |
t | else: |
| assert False, "unhandled option" |
| # ... |
| |
| if __name__ == "__main__": |
| main() |
| |
| |
| .. seealso:: |
| |