|
1 |
|
2 :mod:`getopt` --- Parser for command line options |
|
3 ================================================= |
|
4 |
|
5 .. module:: getopt |
|
6 :synopsis: Portable parser for command line options; support both short and long option |
|
7 names. |
|
8 |
|
9 |
|
10 This module helps scripts to parse the command line arguments in ``sys.argv``. |
|
11 It supports the same conventions as the Unix :cfunc:`getopt` function (including |
|
12 the special meanings of arguments of the form '``-``' and '``--``'). Long |
|
13 options similar to those supported by GNU software may be used as well via an |
|
14 optional third argument. |
|
15 |
|
16 A more convenient, flexible, and powerful alternative is the |
|
17 :mod:`optparse` module. |
|
18 |
|
19 This module provides two functions and an |
|
20 exception: |
|
21 |
|
22 |
|
23 .. function:: getopt(args, options[, long_options]) |
|
24 |
|
25 Parses command line options and parameter list. *args* is the argument list to |
|
26 be parsed, without the leading reference to the running program. Typically, this |
|
27 means ``sys.argv[1:]``. *options* is the string of option letters that the |
|
28 script wants to recognize, with options that require an argument followed by a |
|
29 colon (``':'``; i.e., the same format that Unix :cfunc:`getopt` uses). |
|
30 |
|
31 .. note:: |
|
32 |
|
33 Unlike GNU :cfunc:`getopt`, after a non-option argument, all further arguments |
|
34 are considered also non-options. This is similar to the way non-GNU Unix systems |
|
35 work. |
|
36 |
|
37 *long_options*, if specified, must be a list of strings with the names of the |
|
38 long options which should be supported. The leading ``'-``\ ``-'`` characters |
|
39 should not be included in the option name. Long options which require an |
|
40 argument should be followed by an equal sign (``'='``). To accept only long |
|
41 options, *options* should be an empty string. Long options on the command line |
|
42 can be recognized so long as they provide a prefix of the option name that |
|
43 matches exactly one of the accepted options. For example, if *long_options* is |
|
44 ``['foo', 'frob']``, the option :option:`--fo` will match as :option:`--foo`, |
|
45 but :option:`--f` will not match uniquely, so :exc:`GetoptError` will be raised. |
|
46 |
|
47 The return value consists of two elements: the first is a list of ``(option, |
|
48 value)`` pairs; the second is the list of program arguments left after the |
|
49 option list was stripped (this is a trailing slice of *args*). Each |
|
50 option-and-value pair returned has the option as its first element, prefixed |
|
51 with a hyphen for short options (e.g., ``'-x'``) or two hyphens for long |
|
52 options (e.g., ``'-``\ ``-long-option'``), and the option argument as its |
|
53 second element, or an empty string if the option has no argument. The |
|
54 options occur in the list in the same order in which they were found, thus |
|
55 allowing multiple occurrences. Long and short options may be mixed. |
|
56 |
|
57 |
|
58 .. function:: gnu_getopt(args, options[, long_options]) |
|
59 |
|
60 This function works like :func:`getopt`, except that GNU style scanning mode is |
|
61 used by default. This means that option and non-option arguments may be |
|
62 intermixed. The :func:`getopt` function stops processing options as soon as a |
|
63 non-option argument is encountered. |
|
64 |
|
65 If the first character of the option string is '+', or if the environment |
|
66 variable POSIXLY_CORRECT is set, then option processing stops as soon as a |
|
67 non-option argument is encountered. |
|
68 |
|
69 .. versionadded:: 2.3 |
|
70 |
|
71 |
|
72 .. exception:: GetoptError |
|
73 |
|
74 This is raised when an unrecognized option is found in the argument list or when |
|
75 an option requiring an argument is given none. The argument to the exception is |
|
76 a string indicating the cause of the error. For long options, an argument given |
|
77 to an option which does not require one will also cause this exception to be |
|
78 raised. The attributes :attr:`msg` and :attr:`opt` give the error message and |
|
79 related option; if there is no specific option to which the exception relates, |
|
80 :attr:`opt` is an empty string. |
|
81 |
|
82 .. versionchanged:: 1.6 |
|
83 Introduced :exc:`GetoptError` as a synonym for :exc:`error`. |
|
84 |
|
85 |
|
86 .. exception:: error |
|
87 |
|
88 Alias for :exc:`GetoptError`; for backward compatibility. |
|
89 |
|
90 An example using only Unix style options: |
|
91 |
|
92 >>> import getopt |
|
93 >>> args = '-a -b -cfoo -d bar a1 a2'.split() |
|
94 >>> args |
|
95 ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2'] |
|
96 >>> optlist, args = getopt.getopt(args, 'abc:d:') |
|
97 >>> optlist |
|
98 [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')] |
|
99 >>> args |
|
100 ['a1', 'a2'] |
|
101 |
|
102 Using long option names is equally easy: |
|
103 |
|
104 >>> s = '--condition=foo --testing --output-file abc.def -x a1 a2' |
|
105 >>> args = s.split() |
|
106 >>> args |
|
107 ['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2'] |
|
108 >>> optlist, args = getopt.getopt(args, 'x', [ |
|
109 ... 'condition=', 'output-file=', 'testing']) |
|
110 >>> optlist |
|
111 [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')] |
|
112 >>> args |
|
113 ['a1', 'a2'] |
|
114 |
|
115 In a script, typical usage is something like this:: |
|
116 |
|
117 import getopt, sys |
|
118 |
|
119 def main(): |
|
120 try: |
|
121 opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="]) |
|
122 except getopt.GetoptError, err: |
|
123 # print help information and exit: |
|
124 print str(err) # will print something like "option -a not recognized" |
|
125 usage() |
|
126 sys.exit(2) |
|
127 output = None |
|
128 verbose = False |
|
129 for o, a in opts: |
|
130 if o == "-v": |
|
131 verbose = True |
|
132 elif o in ("-h", "--help"): |
|
133 usage() |
|
134 sys.exit() |
|
135 elif o in ("-o", "--output"): |
|
136 output = a |
|
137 else: |
|
138 assert False, "unhandled option" |
|
139 # ... |
|
140 |
|
141 if __name__ == "__main__": |
|
142 main() |
|
143 |
|
144 |
|
145 .. seealso:: |
|
146 |
|
147 Module :mod:`optparse` |
|
148 More object-oriented command line option parsing. |
|
149 |