Steven Bethard | 6d26569 | 2010-03-02 09:22:57 +0000 | [diff] [blame] | 1 | :mod:`getopt` --- C-style parser for command line options |
| 2 | ========================================================= |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: getopt |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 5 | :synopsis: Portable parser for command line options; support both short and |
| 6 | long option names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 8 | **Source code:** :source:`Lib/getopt.py` |
| 9 | |
| 10 | -------------- |
| 11 | |
Steven Bethard | 5971096 | 2010-05-24 03:21:08 +0000 | [diff] [blame] | 12 | .. note:: |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 13 | |
Steven Bethard | 5971096 | 2010-05-24 03:21:08 +0000 | [diff] [blame] | 14 | The :mod:`getopt` module is a parser for command line options whose API is |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 15 | designed to be familiar to users of the C :c:func:`getopt` function. Users who |
| 16 | are unfamiliar with the C :c:func:`getopt` function or who would like to write |
Steven Bethard | 5971096 | 2010-05-24 03:21:08 +0000 | [diff] [blame] | 17 | less code and get better help and error messages should consider using the |
| 18 | :mod:`argparse` module instead. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 19 | |
| 20 | This module helps scripts to parse the command line arguments in ``sys.argv``. |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 21 | It supports the same conventions as the Unix :c:func:`getopt` function (including |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 22 | the special meanings of arguments of the form '``-``' and '``--``'). Long |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 23 | options similar to those supported by GNU software may be used as well via an |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 24 | optional third argument. |
| 25 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 26 | This module provides two functions and an |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | exception: |
| 28 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 30 | .. function:: getopt(args, shortopts, longopts=[]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | |
| 32 | Parses command line options and parameter list. *args* is the argument list to |
| 33 | be parsed, without the leading reference to the running program. Typically, this |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 34 | means ``sys.argv[1:]``. *shortopts* is the string of option letters that the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 35 | script wants to recognize, with options that require an argument followed by a |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 36 | colon (``':'``; i.e., the same format that Unix :c:func:`getopt` uses). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | |
| 38 | .. note:: |
| 39 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 40 | Unlike GNU :c:func:`getopt`, after a non-option argument, all further |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 41 | arguments are considered also non-options. This is similar to the way |
| 42 | non-GNU Unix systems work. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 44 | *longopts*, if specified, must be a list of strings with the names of the |
Georg Brandl | 81ac1ce | 2007-08-31 17:17:17 +0000 | [diff] [blame] | 45 | long options which should be supported. The leading ``'--'`` characters |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | should not be included in the option name. Long options which require an |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 47 | argument should be followed by an equal sign (``'='``). Optional arguments |
| 48 | are not supported. To accept only long options, *shortopts* should be an |
| 49 | empty string. Long options on the command line can be recognized so long as |
| 50 | they provide a prefix of the option name that matches exactly one of the |
| 51 | accepted options. For example, if *longopts* is ``['foo', 'frob']``, the |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 52 | option ``--fo`` will match as ``--foo``, but ``--f`` will |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 53 | not match uniquely, so :exc:`GetoptError` will be raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | |
| 55 | The return value consists of two elements: the first is a list of ``(option, |
| 56 | value)`` pairs; the second is the list of program arguments left after the |
| 57 | option list was stripped (this is a trailing slice of *args*). Each |
| 58 | option-and-value pair returned has the option as its first element, prefixed |
| 59 | with a hyphen for short options (e.g., ``'-x'``) or two hyphens for long |
Georg Brandl | 81ac1ce | 2007-08-31 17:17:17 +0000 | [diff] [blame] | 60 | options (e.g., ``'--long-option'``), and the option argument as its |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | second element, or an empty string if the option has no argument. The |
| 62 | options occur in the list in the same order in which they were found, thus |
| 63 | allowing multiple occurrences. Long and short options may be mixed. |
| 64 | |
| 65 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 66 | .. function:: gnu_getopt(args, shortopts, longopts=[]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | |
| 68 | This function works like :func:`getopt`, except that GNU style scanning mode is |
| 69 | used by default. This means that option and non-option arguments may be |
| 70 | intermixed. The :func:`getopt` function stops processing options as soon as a |
| 71 | non-option argument is encountered. |
| 72 | |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 73 | If the first character of the option string is ``'+'``, or if the environment |
Georg Brandl | af265f4 | 2008-12-07 15:06:20 +0000 | [diff] [blame] | 74 | variable :envvar:`POSIXLY_CORRECT` is set, then option processing stops as |
| 75 | soon as a non-option argument is encountered. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | |
| 78 | .. exception:: GetoptError |
| 79 | |
| 80 | This is raised when an unrecognized option is found in the argument list or when |
| 81 | an option requiring an argument is given none. The argument to the exception is |
| 82 | a string indicating the cause of the error. For long options, an argument given |
| 83 | to an option which does not require one will also cause this exception to be |
| 84 | raised. The attributes :attr:`msg` and :attr:`opt` give the error message and |
| 85 | related option; if there is no specific option to which the exception relates, |
| 86 | :attr:`opt` is an empty string. |
| 87 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 88 | .. XXX deprecated? |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | .. exception:: error |
| 90 | |
| 91 | Alias for :exc:`GetoptError`; for backward compatibility. |
| 92 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 93 | An example using only Unix style options: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 94 | |
| 95 | >>> import getopt |
| 96 | >>> args = '-a -b -cfoo -d bar a1 a2'.split() |
| 97 | >>> args |
| 98 | ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2'] |
| 99 | >>> optlist, args = getopt.getopt(args, 'abc:d:') |
| 100 | >>> optlist |
| 101 | [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')] |
| 102 | >>> args |
| 103 | ['a1', 'a2'] |
| 104 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 105 | Using long option names is equally easy: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
| 107 | >>> s = '--condition=foo --testing --output-file abc.def -x a1 a2' |
| 108 | >>> args = s.split() |
| 109 | >>> args |
| 110 | ['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2'] |
| 111 | >>> optlist, args = getopt.getopt(args, 'x', [ |
| 112 | ... 'condition=', 'output-file=', 'testing']) |
| 113 | >>> optlist |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 114 | [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | >>> args |
| 116 | ['a1', 'a2'] |
| 117 | |
| 118 | In a script, typical usage is something like this:: |
| 119 | |
| 120 | import getopt, sys |
| 121 | |
| 122 | def main(): |
| 123 | try: |
| 124 | opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="]) |
| 125 | except getopt.GetoptError as err: |
| 126 | # print help information and exit: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 127 | print(err) # will print something like "option -a not recognized" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 128 | usage() |
| 129 | sys.exit(2) |
| 130 | output = None |
| 131 | verbose = False |
| 132 | for o, a in opts: |
| 133 | if o == "-v": |
| 134 | verbose = True |
| 135 | elif o in ("-h", "--help"): |
| 136 | usage() |
| 137 | sys.exit() |
| 138 | elif o in ("-o", "--output"): |
| 139 | output = a |
| 140 | else: |
| 141 | assert False, "unhandled option" |
| 142 | # ... |
| 143 | |
| 144 | if __name__ == "__main__": |
| 145 | main() |
| 146 | |
Steven Bethard | 5971096 | 2010-05-24 03:21:08 +0000 | [diff] [blame] | 147 | Note that an equivalent command line interface could be produced with less code |
| 148 | and more informative help and error messages by using the :mod:`argparse` module:: |
| 149 | |
| 150 | import argparse |
| 151 | |
| 152 | if __name__ == '__main__': |
| 153 | parser = argparse.ArgumentParser() |
| 154 | parser.add_argument('-o', '--output') |
| 155 | parser.add_argument('-v', dest='verbose', action='store_true') |
| 156 | args = parser.parse_args() |
| 157 | # ... do something with args.output ... |
| 158 | # ... do something with args.verbose .. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 159 | |
| 160 | .. seealso:: |
| 161 | |
Steven Bethard | 5971096 | 2010-05-24 03:21:08 +0000 | [diff] [blame] | 162 | Module :mod:`argparse` |
| 163 | Alternative command line option and argument parsing library. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | |