blob: 37764d317ac089cb5b867ba80f8686a64414cc67 [file] [log] [blame]
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001"""A powerful, extensible, and easy-to-use option parser.
Guido van Rossumb9ba4582002-11-14 22:00:19 +00002
3By Greg Ward <gward@python.net>
4
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00005Originally distributed as Optik.
Greg Ward2492fcf2003-04-21 02:40:34 +00006
7For support, use the optik-users@lists.sourceforge.net mailing list
8(http://lists.sourceforge.net/lists/listinfo/optik-users).
Georg Brandlf3532df2009-04-27 16:41:41 +00009
10Simple usage example:
11
12 from optparse import OptionParser
13
14 parser = OptionParser()
15 parser.add_option("-f", "--file", dest="filename",
16 help="write report to FILE", metavar="FILE")
17 parser.add_option("-q", "--quiet",
18 action="store_false", dest="verbose", default=True,
19 help="don't print status messages to stdout")
20
21 (options, args) = parser.parse_args()
Guido van Rossumb9ba4582002-11-14 22:00:19 +000022"""
23
Thomas Wouters0e3f5912006-08-11 14:57:12 +000024__version__ = "1.5.3"
Greg Ward2492fcf2003-04-21 02:40:34 +000025
Greg Ward4656ed42003-05-08 01:38:52 +000026__all__ = ['Option',
Benjamin Petersond23f8222009-04-05 19:13:16 +000027 'make_option',
Greg Ward4656ed42003-05-08 01:38:52 +000028 'SUPPRESS_HELP',
29 'SUPPRESS_USAGE',
Greg Ward4656ed42003-05-08 01:38:52 +000030 'Values',
31 'OptionContainer',
32 'OptionGroup',
33 'OptionParser',
34 'HelpFormatter',
35 'IndentedHelpFormatter',
36 'TitledHelpFormatter',
37 'OptParseError',
38 'OptionError',
39 'OptionConflictError',
40 'OptionValueError',
41 'BadOptionError']
Greg Ward2492fcf2003-04-21 02:40:34 +000042
Guido van Rossumb9ba4582002-11-14 22:00:19 +000043__copyright__ = """
Thomas Wouters477c8d52006-05-27 19:21:47 +000044Copyright (c) 2001-2006 Gregory P. Ward. All rights reserved.
45Copyright (c) 2002-2006 Python Software Foundation. All rights reserved.
Guido van Rossumb9ba4582002-11-14 22:00:19 +000046
47Redistribution and use in source and binary forms, with or without
48modification, are permitted provided that the following conditions are
49met:
50
51 * Redistributions of source code must retain the above copyright
52 notice, this list of conditions and the following disclaimer.
53
54 * Redistributions in binary form must reproduce the above copyright
55 notice, this list of conditions and the following disclaimer in the
56 documentation and/or other materials provided with the distribution.
57
58 * Neither the name of the author nor the names of its
59 contributors may be used to endorse or promote products derived from
60 this software without specific prior written permission.
61
62THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
63IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
64TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
65PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
66CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
67EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
68PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
69PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
70LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
71NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
72SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
73"""
74
75import sys, os
Guido van Rossumb9ba4582002-11-14 22:00:19 +000076import textwrap
Greg Wardeba20e62004-07-31 16:15:44 +000077
78def _repr(self):
79 return "<%s at 0x%x: %s>" % (self.__class__.__name__, id(self), self)
80
81
82# This file was generated from:
Thomas Wouters0e3f5912006-08-11 14:57:12 +000083# Id: option_parser.py 527 2006-07-23 15:21:30Z greg
84# Id: option.py 522 2006-06-11 16:22:03Z gward
85# Id: help.py 527 2006-07-23 15:21:30Z greg
Thomas Wouters477c8d52006-05-27 19:21:47 +000086# Id: errors.py 509 2006-04-20 00:58:24Z gward
87
88try:
Éric Araujo6a1454f2011-03-20 19:59:25 +010089 from gettext import gettext, ngettext
Thomas Wouters477c8d52006-05-27 19:21:47 +000090except ImportError:
91 def gettext(message):
92 return message
Éric Araujo6a1454f2011-03-20 19:59:25 +010093
94 def ngettext(singular, plural, n):
95 if n == 1:
96 return singular
97 return plural
98
Thomas Wouters477c8d52006-05-27 19:21:47 +000099_ = gettext
100
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000101
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000102class OptParseError (Exception):
Greg Wardeba20e62004-07-31 16:15:44 +0000103 def __init__(self, msg):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000104 self.msg = msg
105
Greg Wardeba20e62004-07-31 16:15:44 +0000106 def __str__(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000107 return self.msg
108
Greg Ward2492fcf2003-04-21 02:40:34 +0000109
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000110class OptionError (OptParseError):
111 """
112 Raised if an Option instance is created with invalid or
113 inconsistent arguments.
114 """
115
Greg Wardeba20e62004-07-31 16:15:44 +0000116 def __init__(self, msg, option):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000117 self.msg = msg
118 self.option_id = str(option)
119
Greg Wardeba20e62004-07-31 16:15:44 +0000120 def __str__(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000121 if self.option_id:
122 return "option %s: %s" % (self.option_id, self.msg)
123 else:
124 return self.msg
125
126class OptionConflictError (OptionError):
127 """
128 Raised if conflicting options are added to an OptionParser.
129 """
130
131class OptionValueError (OptParseError):
132 """
133 Raised if an invalid option value is encountered on the command
134 line.
135 """
136
137class BadOptionError (OptParseError):
138 """
Thomas Wouters477c8d52006-05-27 19:21:47 +0000139 Raised if an invalid option is seen on the command line.
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000140 """
Thomas Wouters477c8d52006-05-27 19:21:47 +0000141 def __init__(self, opt_str):
142 self.opt_str = opt_str
143
144 def __str__(self):
145 return _("no such option: %s") % self.opt_str
146
147class AmbiguousOptionError (BadOptionError):
148 """
149 Raised if an ambiguous option is seen on the command line.
150 """
151 def __init__(self, opt_str, possibilities):
152 BadOptionError.__init__(self, opt_str)
153 self.possibilities = possibilities
154
155 def __str__(self):
156 return (_("ambiguous option: %s (%s?)")
157 % (self.opt_str, ", ".join(self.possibilities)))
Greg Ward2492fcf2003-04-21 02:40:34 +0000158
159
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000160class HelpFormatter:
161
162 """
163 Abstract base class for formatting option help. OptionParser
164 instances should use one of the HelpFormatter subclasses for
165 formatting help; by default IndentedHelpFormatter is used.
166
167 Instance attributes:
Greg Wardeba20e62004-07-31 16:15:44 +0000168 parser : OptionParser
169 the controlling OptionParser instance
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000170 indent_increment : int
171 the number of columns to indent per nesting level
172 max_help_position : int
173 the maximum starting column for option help text
174 help_position : int
175 the calculated starting column for option help text;
176 initially the same as the maximum
177 width : int
Greg Wardeba20e62004-07-31 16:15:44 +0000178 total number of columns for output (pass None to constructor for
179 this value to be taken from the $COLUMNS environment variable)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000180 level : int
181 current indentation level
182 current_indent : int
183 current indentation level (in columns)
184 help_width : int
185 number of columns available for option help text (calculated)
Greg Wardeba20e62004-07-31 16:15:44 +0000186 default_tag : str
187 text to replace with each option's default value, "%default"
188 by default. Set to false value to disable default value expansion.
189 option_strings : { Option : str }
190 maps Option instances to the snippet of help text explaining
191 the syntax of that option, e.g. "-h, --help" or
192 "-fFILE, --file=FILE"
193 _short_opt_fmt : str
194 format string controlling how short options with values are
195 printed in help text. Must be either "%s%s" ("-fFILE") or
196 "%s %s" ("-f FILE"), because those are the two syntaxes that
197 Optik supports.
198 _long_opt_fmt : str
199 similar but for long options; must be either "%s %s" ("--file FILE")
200 or "%s=%s" ("--file=FILE").
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000201 """
202
Greg Wardeba20e62004-07-31 16:15:44 +0000203 NO_DEFAULT_VALUE = "none"
204
205 def __init__(self,
206 indent_increment,
207 max_help_position,
208 width,
209 short_first):
210 self.parser = None
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000211 self.indent_increment = indent_increment
212 self.help_position = self.max_help_position = max_help_position
Greg Wardeba20e62004-07-31 16:15:44 +0000213 if width is None:
214 try:
215 width = int(os.environ['COLUMNS'])
216 except (KeyError, ValueError):
217 width = 80
218 width -= 2
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000219 self.width = width
220 self.current_indent = 0
221 self.level = 0
Greg Wardeba20e62004-07-31 16:15:44 +0000222 self.help_width = None # computed later
Greg Ward2492fcf2003-04-21 02:40:34 +0000223 self.short_first = short_first
Greg Wardeba20e62004-07-31 16:15:44 +0000224 self.default_tag = "%default"
225 self.option_strings = {}
226 self._short_opt_fmt = "%s %s"
227 self._long_opt_fmt = "%s=%s"
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000228
Greg Wardeba20e62004-07-31 16:15:44 +0000229 def set_parser(self, parser):
230 self.parser = parser
231
232 def set_short_opt_delimiter(self, delim):
233 if delim not in ("", " "):
234 raise ValueError(
235 "invalid metavar delimiter for short options: %r" % delim)
236 self._short_opt_fmt = "%s" + delim + "%s"
237
238 def set_long_opt_delimiter(self, delim):
239 if delim not in ("=", " "):
240 raise ValueError(
241 "invalid metavar delimiter for long options: %r" % delim)
242 self._long_opt_fmt = "%s" + delim + "%s"
243
244 def indent(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000245 self.current_indent += self.indent_increment
246 self.level += 1
247
Greg Wardeba20e62004-07-31 16:15:44 +0000248 def dedent(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000249 self.current_indent -= self.indent_increment
250 assert self.current_indent >= 0, "Indent decreased below 0."
251 self.level -= 1
252
Greg Wardeba20e62004-07-31 16:15:44 +0000253 def format_usage(self, usage):
Collin Winterce36ad82007-08-30 01:19:48 +0000254 raise NotImplementedError("subclasses must implement")
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000255
Greg Wardeba20e62004-07-31 16:15:44 +0000256 def format_heading(self, heading):
Collin Winterce36ad82007-08-30 01:19:48 +0000257 raise NotImplementedError("subclasses must implement")
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000258
Thomas Wouters477c8d52006-05-27 19:21:47 +0000259 def _format_text(self, text):
260 """
261 Format a paragraph of free-form text for inclusion in the
262 help output at the current indentation level.
263 """
264 text_width = self.width - self.current_indent
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000265 indent = " "*self.current_indent
Thomas Wouters477c8d52006-05-27 19:21:47 +0000266 return textwrap.fill(text,
267 text_width,
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000268 initial_indent=indent,
Thomas Wouters477c8d52006-05-27 19:21:47 +0000269 subsequent_indent=indent)
270
271 def format_description(self, description):
272 if description:
273 return self._format_text(description) + "\n"
274 else:
275 return ""
276
277 def format_epilog(self, epilog):
278 if epilog:
279 return "\n" + self._format_text(epilog) + "\n"
280 else:
281 return ""
282
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000283
Greg Wardeba20e62004-07-31 16:15:44 +0000284 def expand_default(self, option):
285 if self.parser is None or not self.default_tag:
286 return option.help
287
288 default_value = self.parser.defaults.get(option.dest)
289 if default_value is NO_DEFAULT or default_value is None:
290 default_value = self.NO_DEFAULT_VALUE
291
292 return option.help.replace(self.default_tag, str(default_value))
293
294 def format_option(self, option):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000295 # The help for each option consists of two parts:
296 # * the opt strings and metavars
297 # eg. ("-x", or "-fFILENAME, --file=FILENAME")
298 # * the user-supplied help string
299 # eg. ("turn on expert mode", "read data from FILENAME")
300 #
301 # If possible, we write both of these on the same line:
302 # -x turn on expert mode
303 #
304 # But if the opt string list is too long, we put the help
305 # string on a second line, indented to the same column it would
306 # start in if it fit on the first line.
307 # -fFILENAME, --file=FILENAME
308 # read data from FILENAME
309 result = []
Greg Wardeba20e62004-07-31 16:15:44 +0000310 opts = self.option_strings[option]
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000311 opt_width = self.help_position - self.current_indent - 2
312 if len(opts) > opt_width:
313 opts = "%*s%s\n" % (self.current_indent, "", opts)
314 indent_first = self.help_position
315 else: # start help on same line as opts
316 opts = "%*s%-*s " % (self.current_indent, "", opt_width, opts)
317 indent_first = 0
318 result.append(opts)
319 if option.help:
Greg Wardeba20e62004-07-31 16:15:44 +0000320 help_text = self.expand_default(option)
321 help_lines = textwrap.wrap(help_text, self.help_width)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000322 result.append("%*s%s\n" % (indent_first, "", help_lines[0]))
323 result.extend(["%*s%s\n" % (self.help_position, "", line)
324 for line in help_lines[1:]])
325 elif opts[-1] != "\n":
326 result.append("\n")
327 return "".join(result)
328
Greg Wardeba20e62004-07-31 16:15:44 +0000329 def store_option_strings(self, parser):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000330 self.indent()
331 max_len = 0
332 for opt in parser.option_list:
333 strings = self.format_option_strings(opt)
Greg Wardeba20e62004-07-31 16:15:44 +0000334 self.option_strings[opt] = strings
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000335 max_len = max(max_len, len(strings) + self.current_indent)
336 self.indent()
337 for group in parser.option_groups:
338 for opt in group.option_list:
339 strings = self.format_option_strings(opt)
Greg Wardeba20e62004-07-31 16:15:44 +0000340 self.option_strings[opt] = strings
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000341 max_len = max(max_len, len(strings) + self.current_indent)
342 self.dedent()
343 self.dedent()
344 self.help_position = min(max_len + 2, self.max_help_position)
Greg Wardeba20e62004-07-31 16:15:44 +0000345 self.help_width = self.width - self.help_position
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000346
Greg Wardeba20e62004-07-31 16:15:44 +0000347 def format_option_strings(self, option):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000348 """Return a comma-separated list of option strings & metavariables."""
Greg Ward2492fcf2003-04-21 02:40:34 +0000349 if option.takes_value():
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000350 metavar = option.metavar or option.dest.upper()
Greg Wardeba20e62004-07-31 16:15:44 +0000351 short_opts = [self._short_opt_fmt % (sopt, metavar)
352 for sopt in option._short_opts]
353 long_opts = [self._long_opt_fmt % (lopt, metavar)
354 for lopt in option._long_opts]
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000355 else:
Greg Ward2492fcf2003-04-21 02:40:34 +0000356 short_opts = option._short_opts
357 long_opts = option._long_opts
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000358
Greg Ward2492fcf2003-04-21 02:40:34 +0000359 if self.short_first:
360 opts = short_opts + long_opts
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000361 else:
Greg Ward2492fcf2003-04-21 02:40:34 +0000362 opts = long_opts + short_opts
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000363
Greg Ward2492fcf2003-04-21 02:40:34 +0000364 return ", ".join(opts)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000365
366class IndentedHelpFormatter (HelpFormatter):
367 """Format help with indented section bodies.
368 """
369
Greg Wardeba20e62004-07-31 16:15:44 +0000370 def __init__(self,
371 indent_increment=2,
372 max_help_position=24,
373 width=None,
374 short_first=1):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000375 HelpFormatter.__init__(
376 self, indent_increment, max_help_position, width, short_first)
377
Greg Wardeba20e62004-07-31 16:15:44 +0000378 def format_usage(self, usage):
Thomas Wouters477c8d52006-05-27 19:21:47 +0000379 return _("Usage: %s\n") % usage
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000380
Greg Wardeba20e62004-07-31 16:15:44 +0000381 def format_heading(self, heading):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000382 return "%*s%s:\n" % (self.current_indent, "", heading)
383
384
385class TitledHelpFormatter (HelpFormatter):
386 """Format help with underlined section headers.
387 """
388
Greg Wardeba20e62004-07-31 16:15:44 +0000389 def __init__(self,
390 indent_increment=0,
391 max_help_position=24,
392 width=None,
393 short_first=0):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000394 HelpFormatter.__init__ (
395 self, indent_increment, max_help_position, width, short_first)
396
Greg Wardeba20e62004-07-31 16:15:44 +0000397 def format_usage(self, usage):
398 return "%s %s\n" % (self.format_heading(_("Usage")), usage)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000399
Greg Wardeba20e62004-07-31 16:15:44 +0000400 def format_heading(self, heading):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000401 return "%s\n%s\n" % (heading, "=-"[self.level] * len(heading))
Greg Ward2492fcf2003-04-21 02:40:34 +0000402
403
Thomas Wouters477c8d52006-05-27 19:21:47 +0000404def _parse_num(val, type):
405 if val[:2].lower() == "0x": # hexadecimal
406 radix = 16
407 elif val[:2].lower() == "0b": # binary
408 radix = 2
409 val = val[2:] or "0" # have to remove "0b" prefix
410 elif val[:1] == "0": # octal
411 radix = 8
412 else: # decimal
413 radix = 10
414
415 return type(val, radix)
416
417def _parse_int(val):
418 return _parse_num(val, int)
419
Thomas Wouters477c8d52006-05-27 19:21:47 +0000420_builtin_cvt = { "int" : (_parse_int, _("integer")),
Florent Xicluna2bb96f52011-10-23 22:11:00 +0200421 "long" : (_parse_int, _("integer")),
Greg Wardeba20e62004-07-31 16:15:44 +0000422 "float" : (float, _("floating-point")),
423 "complex" : (complex, _("complex")) }
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000424
Greg Wardeba20e62004-07-31 16:15:44 +0000425def check_builtin(option, opt, value):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000426 (cvt, what) = _builtin_cvt[option.type]
427 try:
428 return cvt(value)
429 except ValueError:
430 raise OptionValueError(
Greg Wardeba20e62004-07-31 16:15:44 +0000431 _("option %s: invalid %s value: %r") % (opt, what, value))
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000432
433def check_choice(option, opt, value):
434 if value in option.choices:
435 return value
436 else:
437 choices = ", ".join(map(repr, option.choices))
438 raise OptionValueError(
Greg Wardeba20e62004-07-31 16:15:44 +0000439 _("option %s: invalid choice: %r (choose from %s)")
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000440 % (opt, value, choices))
441
442# Not supplying a default is different from a default of None,
443# so we need an explicit "not supplied" value.
Greg Wardeba20e62004-07-31 16:15:44 +0000444NO_DEFAULT = ("NO", "DEFAULT")
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000445
446
447class Option:
448 """
449 Instance attributes:
450 _short_opts : [string]
451 _long_opts : [string]
452
453 action : string
454 type : string
455 dest : string
456 default : any
457 nargs : int
458 const : any
459 choices : [string]
460 callback : function
461 callback_args : (any*)
462 callback_kwargs : { string : any }
463 help : string
464 metavar : string
465 """
466
467 # The list of instance attributes that may be set through
468 # keyword args to the constructor.
469 ATTRS = ['action',
470 'type',
471 'dest',
472 'default',
473 'nargs',
474 'const',
475 'choices',
476 'callback',
477 'callback_args',
478 'callback_kwargs',
479 'help',
480 'metavar']
481
482 # The set of actions allowed by option parsers. Explicitly listed
483 # here so the constructor can validate its arguments.
484 ACTIONS = ("store",
485 "store_const",
486 "store_true",
487 "store_false",
488 "append",
Thomas Wouters477c8d52006-05-27 19:21:47 +0000489 "append_const",
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000490 "count",
491 "callback",
492 "help",
493 "version")
494
495 # The set of actions that involve storing a value somewhere;
496 # also listed just for constructor argument validation. (If
497 # the action is one of these, there must be a destination.)
498 STORE_ACTIONS = ("store",
499 "store_const",
500 "store_true",
501 "store_false",
502 "append",
Thomas Wouters477c8d52006-05-27 19:21:47 +0000503 "append_const",
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000504 "count")
505
506 # The set of actions for which it makes sense to supply a value
Greg Ward48aa84b2004-10-27 02:20:04 +0000507 # type, ie. which may consume an argument from the command line.
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000508 TYPED_ACTIONS = ("store",
509 "append",
510 "callback")
511
Greg Ward48aa84b2004-10-27 02:20:04 +0000512 # The set of actions which *require* a value type, ie. that
513 # always consume an argument from the command line.
514 ALWAYS_TYPED_ACTIONS = ("store",
515 "append")
516
Thomas Wouters477c8d52006-05-27 19:21:47 +0000517 # The set of actions which take a 'const' attribute.
518 CONST_ACTIONS = ("store_const",
519 "append_const")
520
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000521 # The set of known types for option parsers. Again, listed here for
522 # constructor argument validation.
523 TYPES = ("string", "int", "long", "float", "complex", "choice")
524
525 # Dictionary of argument checking functions, which convert and
526 # validate option arguments according to the option type.
527 #
528 # Signature of checking functions is:
529 # check(option : Option, opt : string, value : string) -> any
530 # where
531 # option is the Option instance calling the checker
532 # opt is the actual option seen on the command-line
533 # (eg. "-a", "--file")
534 # value is the option argument seen on the command-line
535 #
536 # The return value should be in the appropriate Python type
537 # for option.type -- eg. an integer if option.type == "int".
538 #
539 # If no checker is defined for a type, arguments will be
540 # unchecked and remain strings.
541 TYPE_CHECKER = { "int" : check_builtin,
542 "long" : check_builtin,
543 "float" : check_builtin,
Greg Wardeba20e62004-07-31 16:15:44 +0000544 "complex": check_builtin,
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000545 "choice" : check_choice,
546 }
547
548
549 # CHECK_METHODS is a list of unbound method objects; they are called
550 # by the constructor, in order, after all attributes are
551 # initialized. The list is created and filled in later, after all
552 # the methods are actually defined. (I just put it here because I
553 # like to define and document all class attributes in the same
554 # place.) Subclasses that add another _check_*() method should
555 # define their own CHECK_METHODS list that adds their check method
556 # to those from this class.
557 CHECK_METHODS = None
558
559
560 # -- Constructor/initialization methods ----------------------------
561
Greg Wardeba20e62004-07-31 16:15:44 +0000562 def __init__(self, *opts, **attrs):
Greg Ward2492fcf2003-04-21 02:40:34 +0000563 # Set _short_opts, _long_opts attrs from 'opts' tuple.
564 # Have to be set now, in case no option strings are supplied.
565 self._short_opts = []
566 self._long_opts = []
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000567 opts = self._check_opt_strings(opts)
568 self._set_opt_strings(opts)
569
570 # Set all other attrs (action, type, etc.) from 'attrs' dict
571 self._set_attrs(attrs)
572
573 # Check all the attributes we just set. There are lots of
574 # complicated interdependencies, but luckily they can be farmed
575 # out to the _check_*() methods listed in CHECK_METHODS -- which
576 # could be handy for subclasses! The one thing these all share
577 # is that they raise OptionError if they discover a problem.
578 for checker in self.CHECK_METHODS:
579 checker(self)
580
Greg Wardeba20e62004-07-31 16:15:44 +0000581 def _check_opt_strings(self, opts):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000582 # Filter out None because early versions of Optik had exactly
583 # one short option and one long option, either of which
584 # could be None.
Guido van Rossumc1f779c2007-07-03 08:25:58 +0000585 opts = [opt for opt in opts if opt]
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000586 if not opts:
Greg Ward2492fcf2003-04-21 02:40:34 +0000587 raise TypeError("at least one option string must be supplied")
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000588 return opts
589
Greg Wardeba20e62004-07-31 16:15:44 +0000590 def _set_opt_strings(self, opts):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000591 for opt in opts:
592 if len(opt) < 2:
593 raise OptionError(
594 "invalid option string %r: "
595 "must be at least two characters long" % opt, self)
596 elif len(opt) == 2:
597 if not (opt[0] == "-" and opt[1] != "-"):
598 raise OptionError(
599 "invalid short option string %r: "
600 "must be of the form -x, (x any non-dash char)" % opt,
601 self)
602 self._short_opts.append(opt)
603 else:
604 if not (opt[0:2] == "--" and opt[2] != "-"):
605 raise OptionError(
606 "invalid long option string %r: "
607 "must start with --, followed by non-dash" % opt,
608 self)
609 self._long_opts.append(opt)
610
Greg Wardeba20e62004-07-31 16:15:44 +0000611 def _set_attrs(self, attrs):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000612 for attr in self.ATTRS:
Guido van Rossume2b70bc2006-08-18 22:13:04 +0000613 if attr in attrs:
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000614 setattr(self, attr, attrs[attr])
615 del attrs[attr]
616 else:
617 if attr == 'default':
618 setattr(self, attr, NO_DEFAULT)
619 else:
620 setattr(self, attr, None)
621 if attrs:
Georg Brandlc2d9d7f2007-02-11 23:06:17 +0000622 attrs = sorted(attrs.keys())
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000623 raise OptionError(
Thomas Wouters4d70c3d2006-06-08 14:42:34 +0000624 "invalid keyword arguments: %s" % ", ".join(attrs),
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000625 self)
626
627
628 # -- Constructor validation methods --------------------------------
629
Greg Wardeba20e62004-07-31 16:15:44 +0000630 def _check_action(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000631 if self.action is None:
632 self.action = "store"
633 elif self.action not in self.ACTIONS:
634 raise OptionError("invalid action: %r" % self.action, self)
635
Greg Wardeba20e62004-07-31 16:15:44 +0000636 def _check_type(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000637 if self.type is None:
Greg Ward48aa84b2004-10-27 02:20:04 +0000638 if self.action in self.ALWAYS_TYPED_ACTIONS:
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000639 if self.choices is not None:
640 # The "choices" attribute implies "choice" type.
641 self.type = "choice"
642 else:
643 # No type given? "string" is the most sensible default.
644 self.type = "string"
645 else:
Thomas Wouters477c8d52006-05-27 19:21:47 +0000646 # Allow type objects or builtin type conversion functions
647 # (int, str, etc.) as an alternative to their names. (The
Georg Brandl1a3284e2007-12-02 09:40:06 +0000648 # complicated check of builtins is only necessary for
Thomas Wouters477c8d52006-05-27 19:21:47 +0000649 # Python 2.1 and earlier, and is short-circuited by the
650 # first check on modern Pythons.)
Georg Brandl1a3284e2007-12-02 09:40:06 +0000651 import builtins
Guido van Rossum13257902007-06-07 23:15:56 +0000652 if ( isinstance(self.type, type) or
Thomas Wouters477c8d52006-05-27 19:21:47 +0000653 (hasattr(self.type, "__name__") and
Georg Brandl1a3284e2007-12-02 09:40:06 +0000654 getattr(builtins, self.type.__name__, None) is self.type) ):
Greg Wardeba20e62004-07-31 16:15:44 +0000655 self.type = self.type.__name__
Thomas Wouters477c8d52006-05-27 19:21:47 +0000656
Greg Wardeba20e62004-07-31 16:15:44 +0000657 if self.type == "str":
658 self.type = "string"
659
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000660 if self.type not in self.TYPES:
661 raise OptionError("invalid option type: %r" % self.type, self)
662 if self.action not in self.TYPED_ACTIONS:
663 raise OptionError(
664 "must not supply a type for action %r" % self.action, self)
665
666 def _check_choice(self):
667 if self.type == "choice":
668 if self.choices is None:
669 raise OptionError(
670 "must supply a list of choices for type 'choice'", self)
Guido van Rossum13257902007-06-07 23:15:56 +0000671 elif not isinstance(self.choices, (tuple, list)):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000672 raise OptionError(
673 "choices must be a list of strings ('%s' supplied)"
674 % str(type(self.choices)).split("'")[1], self)
675 elif self.choices is not None:
676 raise OptionError(
677 "must not supply choices for type %r" % self.type, self)
678
Greg Wardeba20e62004-07-31 16:15:44 +0000679 def _check_dest(self):
680 # No destination given, and we need one for this action. The
681 # self.type check is for callbacks that take a value.
682 takes_value = (self.action in self.STORE_ACTIONS or
683 self.type is not None)
684 if self.dest is None and takes_value:
685
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000686 # Glean a destination from the first long option string,
687 # or from the first short option string if no long options.
688 if self._long_opts:
689 # eg. "--foo-bar" -> "foo_bar"
690 self.dest = self._long_opts[0][2:].replace('-', '_')
691 else:
692 self.dest = self._short_opts[0][1]
693
Greg Wardeba20e62004-07-31 16:15:44 +0000694 def _check_const(self):
Thomas Wouters477c8d52006-05-27 19:21:47 +0000695 if self.action not in self.CONST_ACTIONS and self.const is not None:
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000696 raise OptionError(
697 "'const' must not be supplied for action %r" % self.action,
698 self)
699
Greg Wardeba20e62004-07-31 16:15:44 +0000700 def _check_nargs(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000701 if self.action in self.TYPED_ACTIONS:
702 if self.nargs is None:
703 self.nargs = 1
704 elif self.nargs is not None:
705 raise OptionError(
706 "'nargs' must not be supplied for action %r" % self.action,
707 self)
708
Greg Wardeba20e62004-07-31 16:15:44 +0000709 def _check_callback(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000710 if self.action == "callback":
Florent Xicluna5d1155c2011-10-28 14:45:05 +0200711 if not callable(self.callback):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000712 raise OptionError(
713 "callback not callable: %r" % self.callback, self)
714 if (self.callback_args is not None and
Guido van Rossum13257902007-06-07 23:15:56 +0000715 not isinstance(self.callback_args, tuple)):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000716 raise OptionError(
717 "callback_args, if supplied, must be a tuple: not %r"
718 % self.callback_args, self)
719 if (self.callback_kwargs is not None and
Guido van Rossum13257902007-06-07 23:15:56 +0000720 not isinstance(self.callback_kwargs, dict)):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000721 raise OptionError(
722 "callback_kwargs, if supplied, must be a dict: not %r"
723 % self.callback_kwargs, self)
724 else:
725 if self.callback is not None:
726 raise OptionError(
727 "callback supplied (%r) for non-callback option"
728 % self.callback, self)
729 if self.callback_args is not None:
730 raise OptionError(
731 "callback_args supplied for non-callback option", self)
732 if self.callback_kwargs is not None:
733 raise OptionError(
734 "callback_kwargs supplied for non-callback option", self)
735
736
737 CHECK_METHODS = [_check_action,
738 _check_type,
739 _check_choice,
740 _check_dest,
741 _check_const,
742 _check_nargs,
743 _check_callback]
744
745
746 # -- Miscellaneous methods -----------------------------------------
747
Greg Wardeba20e62004-07-31 16:15:44 +0000748 def __str__(self):
Greg Ward2492fcf2003-04-21 02:40:34 +0000749 return "/".join(self._short_opts + self._long_opts)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000750
Greg Wardeba20e62004-07-31 16:15:44 +0000751 __repr__ = _repr
752
753 def takes_value(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000754 return self.type is not None
755
Greg Wardeba20e62004-07-31 16:15:44 +0000756 def get_opt_string(self):
757 if self._long_opts:
758 return self._long_opts[0]
759 else:
760 return self._short_opts[0]
761
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000762
763 # -- Processing methods --------------------------------------------
764
Greg Wardeba20e62004-07-31 16:15:44 +0000765 def check_value(self, opt, value):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000766 checker = self.TYPE_CHECKER.get(self.type)
767 if checker is None:
768 return value
769 else:
770 return checker(self, opt, value)
771
Greg Wardeba20e62004-07-31 16:15:44 +0000772 def convert_value(self, opt, value):
773 if value is not None:
774 if self.nargs == 1:
775 return self.check_value(opt, value)
776 else:
777 return tuple([self.check_value(opt, v) for v in value])
778
779 def process(self, opt, value, values, parser):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000780
781 # First, convert the value(s) to the right type. Howl if any
782 # value(s) are bogus.
Greg Wardeba20e62004-07-31 16:15:44 +0000783 value = self.convert_value(opt, value)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000784
785 # And then take whatever action is expected of us.
786 # This is a separate method to make life easier for
787 # subclasses to add new actions.
788 return self.take_action(
789 self.action, self.dest, opt, value, values, parser)
790
Greg Wardeba20e62004-07-31 16:15:44 +0000791 def take_action(self, action, dest, opt, value, values, parser):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000792 if action == "store":
793 setattr(values, dest, value)
794 elif action == "store_const":
795 setattr(values, dest, self.const)
796 elif action == "store_true":
Greg Ward2492fcf2003-04-21 02:40:34 +0000797 setattr(values, dest, True)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000798 elif action == "store_false":
Greg Ward2492fcf2003-04-21 02:40:34 +0000799 setattr(values, dest, False)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000800 elif action == "append":
801 values.ensure_value(dest, []).append(value)
Thomas Wouters477c8d52006-05-27 19:21:47 +0000802 elif action == "append_const":
803 values.ensure_value(dest, []).append(self.const)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000804 elif action == "count":
805 setattr(values, dest, values.ensure_value(dest, 0) + 1)
806 elif action == "callback":
807 args = self.callback_args or ()
808 kwargs = self.callback_kwargs or {}
809 self.callback(self, opt, value, parser, *args, **kwargs)
810 elif action == "help":
811 parser.print_help()
Greg Ward48aa84b2004-10-27 02:20:04 +0000812 parser.exit()
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000813 elif action == "version":
814 parser.print_version()
Greg Ward48aa84b2004-10-27 02:20:04 +0000815 parser.exit()
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000816 else:
Benjamin Peterson4469d0c2008-11-30 22:46:23 +0000817 raise ValueError("unknown action %r" % self.action)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000818
819 return 1
820
821# class Option
Greg Ward2492fcf2003-04-21 02:40:34 +0000822
823
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000824SUPPRESS_HELP = "SUPPRESS"+"HELP"
825SUPPRESS_USAGE = "SUPPRESS"+"USAGE"
826
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000827class Values:
828
Greg Wardeba20e62004-07-31 16:15:44 +0000829 def __init__(self, defaults=None):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000830 if defaults:
831 for (attr, val) in defaults.items():
832 setattr(self, attr, val)
833
Greg Wardeba20e62004-07-31 16:15:44 +0000834 def __str__(self):
835 return str(self.__dict__)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000836
Greg Wardeba20e62004-07-31 16:15:44 +0000837 __repr__ = _repr
838
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000839 def __eq__(self, other):
Greg Wardeba20e62004-07-31 16:15:44 +0000840 if isinstance(other, Values):
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000841 return self.__dict__ == other.__dict__
Guido van Rossum13257902007-06-07 23:15:56 +0000842 elif isinstance(other, dict):
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000843 return self.__dict__ == other
Greg Wardeba20e62004-07-31 16:15:44 +0000844 else:
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000845 return NotImplemented
Greg Wardeba20e62004-07-31 16:15:44 +0000846
847 def _update_careful(self, dict):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000848 """
849 Update the option values from an arbitrary dictionary, but only
850 use keys from dict that already have a corresponding attribute
851 in self. Any keys in dict without a corresponding attribute
852 are silently ignored.
853 """
854 for attr in dir(self):
Guido van Rossume2b70bc2006-08-18 22:13:04 +0000855 if attr in dict:
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000856 dval = dict[attr]
857 if dval is not None:
858 setattr(self, attr, dval)
859
Greg Wardeba20e62004-07-31 16:15:44 +0000860 def _update_loose(self, dict):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000861 """
862 Update the option values from an arbitrary dictionary,
863 using all keys from the dictionary regardless of whether
864 they have a corresponding attribute in self or not.
865 """
866 self.__dict__.update(dict)
867
Greg Wardeba20e62004-07-31 16:15:44 +0000868 def _update(self, dict, mode):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000869 if mode == "careful":
870 self._update_careful(dict)
871 elif mode == "loose":
872 self._update_loose(dict)
873 else:
Collin Winterce36ad82007-08-30 01:19:48 +0000874 raise ValueError("invalid update mode: %r" % mode)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000875
Greg Wardeba20e62004-07-31 16:15:44 +0000876 def read_module(self, modname, mode="careful"):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000877 __import__(modname)
878 mod = sys.modules[modname]
879 self._update(vars(mod), mode)
880
Greg Wardeba20e62004-07-31 16:15:44 +0000881 def read_file(self, filename, mode="careful"):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000882 vars = {}
Neal Norwitz01688022007-08-12 00:43:29 +0000883 exec(open(filename).read(), vars)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000884 self._update(vars, mode)
885
Greg Wardeba20e62004-07-31 16:15:44 +0000886 def ensure_value(self, attr, value):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000887 if not hasattr(self, attr) or getattr(self, attr) is None:
888 setattr(self, attr, value)
889 return getattr(self, attr)
890
891
892class OptionContainer:
893
894 """
895 Abstract base class.
896
897 Class attributes:
898 standard_option_list : [Option]
899 list of standard options that will be accepted by all instances
900 of this parser class (intended to be overridden by subclasses).
901
902 Instance attributes:
903 option_list : [Option]
904 the list of Option objects contained by this OptionContainer
905 _short_opt : { string : Option }
906 dictionary mapping short option strings, eg. "-f" or "-X",
907 to the Option instances that implement them. If an Option
908 has multiple short option strings, it will appears in this
909 dictionary multiple times. [1]
910 _long_opt : { string : Option }
911 dictionary mapping long option strings, eg. "--file" or
912 "--exclude", to the Option instances that implement them.
913 Again, a given Option can occur multiple times in this
914 dictionary. [1]
915 defaults : { string : any }
916 dictionary mapping option destination names to default
917 values for each destination [1]
918
919 [1] These mappings are common to (shared by) all components of the
920 controlling OptionParser, where they are initially created.
921
922 """
923
Greg Wardeba20e62004-07-31 16:15:44 +0000924 def __init__(self, option_class, conflict_handler, description):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000925 # Initialize the option list and related data structures.
926 # This method must be provided by subclasses, and it must
927 # initialize at least the following instance attributes:
928 # option_list, _short_opt, _long_opt, defaults.
929 self._create_option_list()
930
931 self.option_class = option_class
932 self.set_conflict_handler(conflict_handler)
933 self.set_description(description)
934
Greg Wardeba20e62004-07-31 16:15:44 +0000935 def _create_option_mappings(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000936 # For use by OptionParser constructor -- create the master
937 # option mappings used by this OptionParser and all
938 # OptionGroups that it owns.
939 self._short_opt = {} # single letter -> Option instance
940 self._long_opt = {} # long option -> Option instance
941 self.defaults = {} # maps option dest -> default value
942
943
Greg Wardeba20e62004-07-31 16:15:44 +0000944 def _share_option_mappings(self, parser):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000945 # For use by OptionGroup constructor -- use shared option
946 # mappings from the OptionParser that owns this OptionGroup.
947 self._short_opt = parser._short_opt
948 self._long_opt = parser._long_opt
949 self.defaults = parser.defaults
950
Greg Wardeba20e62004-07-31 16:15:44 +0000951 def set_conflict_handler(self, handler):
Greg Ward48aa84b2004-10-27 02:20:04 +0000952 if handler not in ("error", "resolve"):
Collin Winterce36ad82007-08-30 01:19:48 +0000953 raise ValueError("invalid conflict_resolution value %r" % handler)
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000954 self.conflict_handler = handler
955
Greg Wardeba20e62004-07-31 16:15:44 +0000956 def set_description(self, description):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000957 self.description = description
958
Greg Wardeba20e62004-07-31 16:15:44 +0000959 def get_description(self):
960 return self.description
961
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000962
Thomas Wouters477c8d52006-05-27 19:21:47 +0000963 def destroy(self):
964 """see OptionParser.destroy()."""
965 del self._short_opt
966 del self._long_opt
967 del self.defaults
968
969
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000970 # -- Option-adding methods -----------------------------------------
971
Greg Wardeba20e62004-07-31 16:15:44 +0000972 def _check_conflict(self, option):
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000973 conflict_opts = []
974 for opt in option._short_opts:
Guido van Rossume2b70bc2006-08-18 22:13:04 +0000975 if opt in self._short_opt:
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000976 conflict_opts.append((opt, self._short_opt[opt]))
977 for opt in option._long_opts:
Guido van Rossume2b70bc2006-08-18 22:13:04 +0000978 if opt in self._long_opt:
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000979 conflict_opts.append((opt, self._long_opt[opt]))
980
981 if conflict_opts:
982 handler = self.conflict_handler
Greg Ward48aa84b2004-10-27 02:20:04 +0000983 if handler == "error":
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000984 raise OptionConflictError(
985 "conflicting option string(s): %s"
986 % ", ".join([co[0] for co in conflict_opts]),
987 option)
Greg Ward48aa84b2004-10-27 02:20:04 +0000988 elif handler == "resolve":
Guido van Rossumb9ba4582002-11-14 22:00:19 +0000989 for (opt, c_option) in conflict_opts:
990 if opt.startswith("--"):
991 c_option._long_opts.remove(opt)
992 del self._long_opt[opt]
993 else:
994 c_option._short_opts.remove(opt)
995 del self._short_opt[opt]
996 if not (c_option._short_opts or c_option._long_opts):
997 c_option.container.option_list.remove(c_option)
998
Greg Wardeba20e62004-07-31 16:15:44 +0000999 def add_option(self, *args, **kwargs):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001000 """add_option(Option)
1001 add_option(opt_str, ..., kwarg=val, ...)
1002 """
Guido van Rossum3172c5d2007-10-16 18:12:55 +00001003 if isinstance(args[0], str):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001004 option = self.option_class(*args, **kwargs)
1005 elif len(args) == 1 and not kwargs:
1006 option = args[0]
1007 if not isinstance(option, Option):
Collin Winterce36ad82007-08-30 01:19:48 +00001008 raise TypeError("not an Option instance: %r" % option)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001009 else:
Collin Winterce36ad82007-08-30 01:19:48 +00001010 raise TypeError("invalid arguments")
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001011
1012 self._check_conflict(option)
1013
1014 self.option_list.append(option)
1015 option.container = self
1016 for opt in option._short_opts:
1017 self._short_opt[opt] = option
1018 for opt in option._long_opts:
1019 self._long_opt[opt] = option
1020
1021 if option.dest is not None: # option has a dest, we need a default
1022 if option.default is not NO_DEFAULT:
1023 self.defaults[option.dest] = option.default
Guido van Rossume2b70bc2006-08-18 22:13:04 +00001024 elif option.dest not in self.defaults:
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001025 self.defaults[option.dest] = None
1026
1027 return option
1028
Greg Wardeba20e62004-07-31 16:15:44 +00001029 def add_options(self, option_list):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001030 for option in option_list:
1031 self.add_option(option)
1032
1033 # -- Option query/removal methods ----------------------------------
1034
Greg Wardeba20e62004-07-31 16:15:44 +00001035 def get_option(self, opt_str):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001036 return (self._short_opt.get(opt_str) or
1037 self._long_opt.get(opt_str))
1038
Greg Wardeba20e62004-07-31 16:15:44 +00001039 def has_option(self, opt_str):
Guido van Rossume2b70bc2006-08-18 22:13:04 +00001040 return (opt_str in self._short_opt or
Guido van Rossum93662412006-08-19 16:09:41 +00001041 opt_str in self._long_opt)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001042
Greg Wardeba20e62004-07-31 16:15:44 +00001043 def remove_option(self, opt_str):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001044 option = self._short_opt.get(opt_str)
1045 if option is None:
1046 option = self._long_opt.get(opt_str)
1047 if option is None:
1048 raise ValueError("no such option %r" % opt_str)
1049
1050 for opt in option._short_opts:
1051 del self._short_opt[opt]
1052 for opt in option._long_opts:
1053 del self._long_opt[opt]
1054 option.container.option_list.remove(option)
1055
1056
1057 # -- Help-formatting methods ---------------------------------------
1058
Greg Wardeba20e62004-07-31 16:15:44 +00001059 def format_option_help(self, formatter):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001060 if not self.option_list:
1061 return ""
1062 result = []
1063 for option in self.option_list:
1064 if not option.help is SUPPRESS_HELP:
1065 result.append(formatter.format_option(option))
1066 return "".join(result)
1067
Greg Wardeba20e62004-07-31 16:15:44 +00001068 def format_description(self, formatter):
1069 return formatter.format_description(self.get_description())
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001070
Greg Wardeba20e62004-07-31 16:15:44 +00001071 def format_help(self, formatter):
1072 result = []
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001073 if self.description:
Greg Wardeba20e62004-07-31 16:15:44 +00001074 result.append(self.format_description(formatter))
1075 if self.option_list:
1076 result.append(self.format_option_help(formatter))
1077 return "\n".join(result)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001078
1079
1080class OptionGroup (OptionContainer):
1081
Greg Wardeba20e62004-07-31 16:15:44 +00001082 def __init__(self, parser, title, description=None):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001083 self.parser = parser
1084 OptionContainer.__init__(
1085 self, parser.option_class, parser.conflict_handler, description)
1086 self.title = title
1087
Greg Wardeba20e62004-07-31 16:15:44 +00001088 def _create_option_list(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001089 self.option_list = []
1090 self._share_option_mappings(self.parser)
1091
Greg Wardeba20e62004-07-31 16:15:44 +00001092 def set_title(self, title):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001093 self.title = title
1094
Thomas Wouters477c8d52006-05-27 19:21:47 +00001095 def destroy(self):
1096 """see OptionParser.destroy()."""
1097 OptionContainer.destroy(self)
1098 del self.option_list
1099
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001100 # -- Help-formatting methods ---------------------------------------
1101
Greg Wardeba20e62004-07-31 16:15:44 +00001102 def format_help(self, formatter):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001103 result = formatter.format_heading(self.title)
1104 formatter.indent()
1105 result += OptionContainer.format_help(self, formatter)
1106 formatter.dedent()
1107 return result
1108
1109
1110class OptionParser (OptionContainer):
1111
1112 """
1113 Class attributes:
1114 standard_option_list : [Option]
1115 list of standard options that will be accepted by all instances
1116 of this parser class (intended to be overridden by subclasses).
1117
1118 Instance attributes:
1119 usage : string
1120 a usage string for your program. Before it is displayed
1121 to the user, "%prog" will be expanded to the name of
Greg Ward2492fcf2003-04-21 02:40:34 +00001122 your program (self.prog or os.path.basename(sys.argv[0])).
1123 prog : string
1124 the name of the current program (to override
1125 os.path.basename(sys.argv[0])).
R David Murrayfc5ed802011-05-04 21:06:57 -04001126 description : string
1127 A paragraph of text giving a brief overview of your program.
1128 optparse reformats this paragraph to fit the current terminal
1129 width and prints it when the user requests help (after usage,
1130 but before the list of options).
Thomas Wouters477c8d52006-05-27 19:21:47 +00001131 epilog : string
1132 paragraph of help text to print after option help
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001133
Greg Wardeba20e62004-07-31 16:15:44 +00001134 option_groups : [OptionGroup]
1135 list of option groups in this parser (option groups are
1136 irrelevant for parsing the command-line, but very useful
1137 for generating help)
1138
1139 allow_interspersed_args : bool = true
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001140 if true, positional arguments may be interspersed with options.
1141 Assuming -a and -b each take a single argument, the command-line
1142 -ablah foo bar -bboo baz
1143 will be interpreted the same as
1144 -ablah -bboo -- foo bar baz
1145 If this flag were false, that command line would be interpreted as
1146 -ablah -- foo bar -bboo baz
1147 -- ie. we stop processing options as soon as we see the first
1148 non-option argument. (This is the tradition followed by
1149 Python's getopt module, Perl's Getopt::Std, and other argument-
1150 parsing libraries, but it is generally annoying to users.)
1151
Greg Wardeba20e62004-07-31 16:15:44 +00001152 process_default_values : bool = true
1153 if true, option default values are processed similarly to option
1154 values from the command line: that is, they are passed to the
1155 type-checking function for the option's type (as long as the
1156 default value is a string). (This really only matters if you
1157 have defined custom types; see SF bug #955889.) Set it to false
1158 to restore the behaviour of Optik 1.4.1 and earlier.
1159
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001160 rargs : [string]
1161 the argument list currently being parsed. Only set when
1162 parse_args() is active, and continually trimmed down as
1163 we consume arguments. Mainly there for the benefit of
1164 callback options.
1165 largs : [string]
1166 the list of leftover arguments that we have skipped while
1167 parsing options. If allow_interspersed_args is false, this
1168 list is always empty.
1169 values : Values
1170 the set of option values currently being accumulated. Only
1171 set when parse_args() is active. Also mainly for callbacks.
1172
1173 Because of the 'rargs', 'largs', and 'values' attributes,
1174 OptionParser is not thread-safe. If, for some perverse reason, you
1175 need to parse command-line arguments simultaneously in different
1176 threads, use different OptionParser instances.
1177
1178 """
1179
1180 standard_option_list = []
1181
Greg Wardeba20e62004-07-31 16:15:44 +00001182 def __init__(self,
1183 usage=None,
1184 option_list=None,
1185 option_class=Option,
1186 version=None,
1187 conflict_handler="error",
1188 description=None,
1189 formatter=None,
1190 add_help_option=True,
Thomas Wouters477c8d52006-05-27 19:21:47 +00001191 prog=None,
1192 epilog=None):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001193 OptionContainer.__init__(
1194 self, option_class, conflict_handler, description)
1195 self.set_usage(usage)
Greg Ward2492fcf2003-04-21 02:40:34 +00001196 self.prog = prog
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001197 self.version = version
Greg Wardeba20e62004-07-31 16:15:44 +00001198 self.allow_interspersed_args = True
1199 self.process_default_values = True
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001200 if formatter is None:
1201 formatter = IndentedHelpFormatter()
1202 self.formatter = formatter
Greg Wardeba20e62004-07-31 16:15:44 +00001203 self.formatter.set_parser(self)
Thomas Wouters477c8d52006-05-27 19:21:47 +00001204 self.epilog = epilog
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001205
1206 # Populate the option list; initial sources are the
1207 # standard_option_list class attribute, the 'option_list'
Greg Wardeba20e62004-07-31 16:15:44 +00001208 # argument, and (if applicable) the _add_version_option() and
1209 # _add_help_option() methods.
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001210 self._populate_option_list(option_list,
1211 add_help=add_help_option)
1212
1213 self._init_parsing_state()
1214
Thomas Wouters477c8d52006-05-27 19:21:47 +00001215
1216 def destroy(self):
1217 """
1218 Declare that you are done with this OptionParser. This cleans up
1219 reference cycles so the OptionParser (and all objects referenced by
1220 it) can be garbage-collected promptly. After calling destroy(), the
1221 OptionParser is unusable.
1222 """
1223 OptionContainer.destroy(self)
1224 for group in self.option_groups:
1225 group.destroy()
1226 del self.option_list
1227 del self.option_groups
1228 del self.formatter
1229
1230
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001231 # -- Private methods -----------------------------------------------
1232 # (used by our or OptionContainer's constructor)
1233
Greg Wardeba20e62004-07-31 16:15:44 +00001234 def _create_option_list(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001235 self.option_list = []
1236 self.option_groups = []
1237 self._create_option_mappings()
1238
Greg Wardeba20e62004-07-31 16:15:44 +00001239 def _add_help_option(self):
1240 self.add_option("-h", "--help",
1241 action="help",
1242 help=_("show this help message and exit"))
1243
1244 def _add_version_option(self):
1245 self.add_option("--version",
1246 action="version",
1247 help=_("show program's version number and exit"))
1248
1249 def _populate_option_list(self, option_list, add_help=True):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001250 if self.standard_option_list:
1251 self.add_options(self.standard_option_list)
1252 if option_list:
1253 self.add_options(option_list)
1254 if self.version:
Greg Wardeba20e62004-07-31 16:15:44 +00001255 self._add_version_option()
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001256 if add_help:
Greg Wardeba20e62004-07-31 16:15:44 +00001257 self._add_help_option()
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001258
Greg Wardeba20e62004-07-31 16:15:44 +00001259 def _init_parsing_state(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001260 # These are set in parse_args() for the convenience of callbacks.
1261 self.rargs = None
1262 self.largs = None
1263 self.values = None
1264
1265
1266 # -- Simple modifier methods ---------------------------------------
1267
Greg Wardeba20e62004-07-31 16:15:44 +00001268 def set_usage(self, usage):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001269 if usage is None:
Greg Wardeba20e62004-07-31 16:15:44 +00001270 self.usage = _("%prog [options]")
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001271 elif usage is SUPPRESS_USAGE:
1272 self.usage = None
Greg Wardeba20e62004-07-31 16:15:44 +00001273 # For backwards compatibility with Optik 1.3 and earlier.
Thomas Wouters477c8d52006-05-27 19:21:47 +00001274 elif usage.lower().startswith("usage: "):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001275 self.usage = usage[7:]
1276 else:
1277 self.usage = usage
1278
Greg Wardeba20e62004-07-31 16:15:44 +00001279 def enable_interspersed_args(self):
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001280 """Set parsing to not stop on the first non-option, allowing
1281 interspersing switches with command arguments. This is the
1282 default behavior. See also disable_interspersed_args() and the
1283 class documentation description of the attribute
1284 allow_interspersed_args."""
Greg Wardeba20e62004-07-31 16:15:44 +00001285 self.allow_interspersed_args = True
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001286
Greg Wardeba20e62004-07-31 16:15:44 +00001287 def disable_interspersed_args(self):
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001288 """Set parsing to stop on the first non-option. Use this if
1289 you have a command processor which runs another command that
1290 has options of its own and you want to make sure these options
1291 don't get confused.
1292 """
Greg Wardeba20e62004-07-31 16:15:44 +00001293 self.allow_interspersed_args = False
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001294
Greg Wardeba20e62004-07-31 16:15:44 +00001295 def set_process_default_values(self, process):
1296 self.process_default_values = process
1297
1298 def set_default(self, dest, value):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001299 self.defaults[dest] = value
1300
Greg Wardeba20e62004-07-31 16:15:44 +00001301 def set_defaults(self, **kwargs):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001302 self.defaults.update(kwargs)
1303
Greg Wardeba20e62004-07-31 16:15:44 +00001304 def _get_all_options(self):
1305 options = self.option_list[:]
1306 for group in self.option_groups:
1307 options.extend(group.option_list)
1308 return options
1309
1310 def get_default_values(self):
1311 if not self.process_default_values:
1312 # Old, pre-Optik 1.5 behaviour.
1313 return Values(self.defaults)
1314
1315 defaults = self.defaults.copy()
1316 for option in self._get_all_options():
1317 default = defaults.get(option.dest)
Guido van Rossum3172c5d2007-10-16 18:12:55 +00001318 if isinstance(default, str):
Greg Wardeba20e62004-07-31 16:15:44 +00001319 opt_str = option.get_opt_string()
1320 defaults[option.dest] = option.check_value(opt_str, default)
1321
1322 return Values(defaults)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001323
1324
1325 # -- OptionGroup methods -------------------------------------------
1326
Greg Wardeba20e62004-07-31 16:15:44 +00001327 def add_option_group(self, *args, **kwargs):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001328 # XXX lots of overlap with OptionContainer.add_option()
Guido van Rossum3172c5d2007-10-16 18:12:55 +00001329 if isinstance(args[0], str):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001330 group = OptionGroup(self, *args, **kwargs)
1331 elif len(args) == 1 and not kwargs:
1332 group = args[0]
1333 if not isinstance(group, OptionGroup):
Collin Winterce36ad82007-08-30 01:19:48 +00001334 raise TypeError("not an OptionGroup instance: %r" % group)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001335 if group.parser is not self:
Collin Winterce36ad82007-08-30 01:19:48 +00001336 raise ValueError("invalid OptionGroup (wrong parser)")
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001337 else:
Collin Winterce36ad82007-08-30 01:19:48 +00001338 raise TypeError("invalid arguments")
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001339
1340 self.option_groups.append(group)
1341 return group
1342
Greg Wardeba20e62004-07-31 16:15:44 +00001343 def get_option_group(self, opt_str):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001344 option = (self._short_opt.get(opt_str) or
1345 self._long_opt.get(opt_str))
1346 if option and option.container is not self:
1347 return option.container
1348 return None
1349
1350
1351 # -- Option-parsing methods ----------------------------------------
1352
Greg Wardeba20e62004-07-31 16:15:44 +00001353 def _get_args(self, args):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001354 if args is None:
1355 return sys.argv[1:]
1356 else:
1357 return args[:] # don't modify caller's list
1358
Greg Wardeba20e62004-07-31 16:15:44 +00001359 def parse_args(self, args=None, values=None):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001360 """
1361 parse_args(args : [string] = sys.argv[1:],
1362 values : Values = None)
1363 -> (values : Values, args : [string])
1364
1365 Parse the command-line options found in 'args' (default:
1366 sys.argv[1:]). Any errors result in a call to 'error()', which
1367 by default prints the usage message to stderr and calls
1368 sys.exit() with an error message. On success returns a pair
1369 (values, args) where 'values' is an Values instance (with all
1370 your option values) and 'args' is the list of arguments left
1371 over after parsing options.
1372 """
1373 rargs = self._get_args(args)
1374 if values is None:
1375 values = self.get_default_values()
1376
1377 # Store the halves of the argument list as attributes for the
1378 # convenience of callbacks:
1379 # rargs
1380 # the rest of the command-line (the "r" stands for
1381 # "remaining" or "right-hand")
1382 # largs
1383 # the leftover arguments -- ie. what's left after removing
1384 # options and their arguments (the "l" stands for "leftover"
1385 # or "left-hand")
1386 self.rargs = rargs
1387 self.largs = largs = []
1388 self.values = values
1389
1390 try:
1391 stop = self._process_args(largs, rargs, values)
Guido van Rossumb940e112007-01-10 16:19:56 +00001392 except (BadOptionError, OptionValueError) as err:
Thomas Wouters477c8d52006-05-27 19:21:47 +00001393 self.error(str(err))
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001394
1395 args = largs + rargs
1396 return self.check_values(values, args)
1397
Greg Wardeba20e62004-07-31 16:15:44 +00001398 def check_values(self, values, args):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001399 """
1400 check_values(values : Values, args : [string])
1401 -> (values : Values, args : [string])
1402
1403 Check that the supplied option values and leftover arguments are
1404 valid. Returns the option values and leftover arguments
1405 (possibly adjusted, possibly completely new -- whatever you
1406 like). Default implementation just returns the passed-in
1407 values; subclasses may override as desired.
1408 """
1409 return (values, args)
1410
Greg Wardeba20e62004-07-31 16:15:44 +00001411 def _process_args(self, largs, rargs, values):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001412 """_process_args(largs : [string],
1413 rargs : [string],
1414 values : Values)
1415
1416 Process command-line arguments and populate 'values', consuming
1417 options and arguments from 'rargs'. If 'allow_interspersed_args' is
1418 false, stop at the first non-option argument. If true, accumulate any
1419 interspersed non-option arguments in 'largs'.
1420 """
1421 while rargs:
1422 arg = rargs[0]
1423 # We handle bare "--" explicitly, and bare "-" is handled by the
1424 # standard arg handler since the short arg case ensures that the
1425 # len of the opt string is greater than 1.
1426 if arg == "--":
1427 del rargs[0]
1428 return
1429 elif arg[0:2] == "--":
1430 # process a single long option (possibly with value(s))
1431 self._process_long_opt(rargs, values)
1432 elif arg[:1] == "-" and len(arg) > 1:
1433 # process a cluster of short options (possibly with
1434 # value(s) for the last one only)
1435 self._process_short_opts(rargs, values)
1436 elif self.allow_interspersed_args:
1437 largs.append(arg)
1438 del rargs[0]
1439 else:
1440 return # stop now, leave this arg in rargs
1441
1442 # Say this is the original argument list:
1443 # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)]
1444 # ^
1445 # (we are about to process arg(i)).
1446 #
1447 # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of
1448 # [arg0, ..., arg(i-1)] (any options and their arguments will have
1449 # been removed from largs).
1450 #
1451 # The while loop will usually consume 1 or more arguments per pass.
1452 # If it consumes 1 (eg. arg is an option that takes no arguments),
1453 # then after _process_arg() is done the situation is:
1454 #
1455 # largs = subset of [arg0, ..., arg(i)]
1456 # rargs = [arg(i+1), ..., arg(N-1)]
1457 #
1458 # If allow_interspersed_args is false, largs will always be
1459 # *empty* -- still a subset of [arg0, ..., arg(i-1)], but
1460 # not a very interesting subset!
1461
Greg Wardeba20e62004-07-31 16:15:44 +00001462 def _match_long_opt(self, opt):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001463 """_match_long_opt(opt : string) -> string
1464
1465 Determine which long option string 'opt' matches, ie. which one
1466 it is an unambiguous abbrevation for. Raises BadOptionError if
1467 'opt' doesn't unambiguously match any long option string.
1468 """
1469 return _match_abbrev(opt, self._long_opt)
1470
Greg Wardeba20e62004-07-31 16:15:44 +00001471 def _process_long_opt(self, rargs, values):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001472 arg = rargs.pop(0)
1473
1474 # Value explicitly attached to arg? Pretend it's the next
1475 # argument.
1476 if "=" in arg:
1477 (opt, next_arg) = arg.split("=", 1)
1478 rargs.insert(0, next_arg)
Greg Wardeba20e62004-07-31 16:15:44 +00001479 had_explicit_value = True
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001480 else:
1481 opt = arg
Greg Wardeba20e62004-07-31 16:15:44 +00001482 had_explicit_value = False
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001483
1484 opt = self._match_long_opt(opt)
1485 option = self._long_opt[opt]
1486 if option.takes_value():
1487 nargs = option.nargs
1488 if len(rargs) < nargs:
Éric Araujo6a1454f2011-03-20 19:59:25 +01001489 self.error(ngettext(
1490 "%(option)s option requires %(number)d argument",
1491 "%(option)s option requires %(number)d arguments",
1492 nargs) % {"option": opt, "number": nargs})
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001493 elif nargs == 1:
1494 value = rargs.pop(0)
1495 else:
1496 value = tuple(rargs[0:nargs])
1497 del rargs[0:nargs]
1498
1499 elif had_explicit_value:
Greg Wardeba20e62004-07-31 16:15:44 +00001500 self.error(_("%s option does not take a value") % opt)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001501
1502 else:
1503 value = None
1504
1505 option.process(opt, value, values, self)
1506
Greg Wardeba20e62004-07-31 16:15:44 +00001507 def _process_short_opts(self, rargs, values):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001508 arg = rargs.pop(0)
Greg Wardeba20e62004-07-31 16:15:44 +00001509 stop = False
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001510 i = 1
1511 for ch in arg[1:]:
1512 opt = "-" + ch
1513 option = self._short_opt.get(opt)
1514 i += 1 # we have consumed a character
1515
1516 if not option:
Thomas Wouters477c8d52006-05-27 19:21:47 +00001517 raise BadOptionError(opt)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001518 if option.takes_value():
1519 # Any characters left in arg? Pretend they're the
1520 # next arg, and stop consuming characters of arg.
1521 if i < len(arg):
1522 rargs.insert(0, arg[i:])
Greg Wardeba20e62004-07-31 16:15:44 +00001523 stop = True
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001524
1525 nargs = option.nargs
1526 if len(rargs) < nargs:
Éric Araujo6a1454f2011-03-20 19:59:25 +01001527 self.error(ngettext(
1528 "%(option)s option requires %(number)d argument",
1529 "%(option)s option requires %(number)d arguments",
1530 nargs) % {"option": opt, "number": nargs})
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001531 elif nargs == 1:
1532 value = rargs.pop(0)
1533 else:
1534 value = tuple(rargs[0:nargs])
1535 del rargs[0:nargs]
1536
1537 else: # option doesn't take a value
1538 value = None
1539
1540 option.process(opt, value, values, self)
1541
1542 if stop:
1543 break
1544
1545
1546 # -- Feedback methods ----------------------------------------------
1547
Greg Wardeba20e62004-07-31 16:15:44 +00001548 def get_prog_name(self):
1549 if self.prog is None:
1550 return os.path.basename(sys.argv[0])
1551 else:
1552 return self.prog
1553
1554 def expand_prog_name(self, s):
1555 return s.replace("%prog", self.get_prog_name())
1556
1557 def get_description(self):
1558 return self.expand_prog_name(self.description)
1559
Greg Ward48aa84b2004-10-27 02:20:04 +00001560 def exit(self, status=0, msg=None):
1561 if msg:
1562 sys.stderr.write(msg)
1563 sys.exit(status)
1564
Greg Wardeba20e62004-07-31 16:15:44 +00001565 def error(self, msg):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001566 """error(msg : string)
1567
1568 Print a usage message incorporating 'msg' to stderr and exit.
1569 If you override this in a subclass, it should not return -- it
1570 should either exit or raise an exception.
1571 """
1572 self.print_usage(sys.stderr)
Greg Ward48aa84b2004-10-27 02:20:04 +00001573 self.exit(2, "%s: error: %s\n" % (self.get_prog_name(), msg))
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001574
Greg Wardeba20e62004-07-31 16:15:44 +00001575 def get_usage(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001576 if self.usage:
1577 return self.formatter.format_usage(
Greg Wardeba20e62004-07-31 16:15:44 +00001578 self.expand_prog_name(self.usage))
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001579 else:
1580 return ""
1581
Greg Wardeba20e62004-07-31 16:15:44 +00001582 def print_usage(self, file=None):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001583 """print_usage(file : file = stdout)
1584
1585 Print the usage message for the current program (self.usage) to
Mark Dickinson934896d2009-02-21 20:59:32 +00001586 'file' (default stdout). Any occurrence of the string "%prog" in
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001587 self.usage is replaced with the name of the current program
1588 (basename of sys.argv[0]). Does nothing if self.usage is empty
1589 or not defined.
1590 """
1591 if self.usage:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001592 print(self.get_usage(), file=file)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001593
Greg Wardeba20e62004-07-31 16:15:44 +00001594 def get_version(self):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001595 if self.version:
Greg Wardeba20e62004-07-31 16:15:44 +00001596 return self.expand_prog_name(self.version)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001597 else:
1598 return ""
1599
Greg Wardeba20e62004-07-31 16:15:44 +00001600 def print_version(self, file=None):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001601 """print_version(file : file = stdout)
1602
1603 Print the version message for this program (self.version) to
Mark Dickinson934896d2009-02-21 20:59:32 +00001604 'file' (default stdout). As with print_usage(), any occurrence
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001605 of "%prog" in self.version is replaced by the current program's
1606 name. Does nothing if self.version is empty or undefined.
1607 """
1608 if self.version:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001609 print(self.get_version(), file=file)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001610
Greg Wardeba20e62004-07-31 16:15:44 +00001611 def format_option_help(self, formatter=None):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001612 if formatter is None:
1613 formatter = self.formatter
1614 formatter.store_option_strings(self)
1615 result = []
Thomas Wouters477c8d52006-05-27 19:21:47 +00001616 result.append(formatter.format_heading(_("Options")))
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001617 formatter.indent()
1618 if self.option_list:
1619 result.append(OptionContainer.format_option_help(self, formatter))
1620 result.append("\n")
1621 for group in self.option_groups:
1622 result.append(group.format_help(formatter))
1623 result.append("\n")
1624 formatter.dedent()
1625 # Drop the last "\n", or the header if no options or option groups:
1626 return "".join(result[:-1])
1627
Thomas Wouters477c8d52006-05-27 19:21:47 +00001628 def format_epilog(self, formatter):
1629 return formatter.format_epilog(self.epilog)
1630
Greg Wardeba20e62004-07-31 16:15:44 +00001631 def format_help(self, formatter=None):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001632 if formatter is None:
1633 formatter = self.formatter
1634 result = []
1635 if self.usage:
1636 result.append(self.get_usage() + "\n")
1637 if self.description:
1638 result.append(self.format_description(formatter) + "\n")
1639 result.append(self.format_option_help(formatter))
Thomas Wouters477c8d52006-05-27 19:21:47 +00001640 result.append(self.format_epilog(formatter))
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001641 return "".join(result)
1642
Greg Wardeba20e62004-07-31 16:15:44 +00001643 def print_help(self, file=None):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001644 """print_help(file : file = stdout)
1645
1646 Print an extended help message, listing all options and any
1647 help text provided with them, to 'file' (default stdout).
1648 """
1649 if file is None:
1650 file = sys.stdout
Guido van Rossum34d19282007-08-09 01:03:29 +00001651 file.write(self.format_help())
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001652
1653# class OptionParser
1654
1655
Greg Wardeba20e62004-07-31 16:15:44 +00001656def _match_abbrev(s, wordmap):
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001657 """_match_abbrev(s : string, wordmap : {string : Option}) -> string
1658
1659 Return the string key in 'wordmap' for which 's' is an unambiguous
1660 abbreviation. If 's' is found to be ambiguous or doesn't match any of
1661 'words', raise BadOptionError.
1662 """
1663 # Is there an exact match?
Guido van Rossume2b70bc2006-08-18 22:13:04 +00001664 if s in wordmap:
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001665 return s
1666 else:
1667 # Isolate all words with s as a prefix.
1668 possibilities = [word for word in wordmap.keys()
1669 if word.startswith(s)]
1670 # No exact match, so there had better be just one possibility.
1671 if len(possibilities) == 1:
1672 return possibilities[0]
1673 elif not possibilities:
Thomas Wouters477c8d52006-05-27 19:21:47 +00001674 raise BadOptionError(s)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001675 else:
1676 # More than one possible completion: ambiguous prefix.
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001677 possibilities.sort()
Thomas Wouters477c8d52006-05-27 19:21:47 +00001678 raise AmbiguousOptionError(s, possibilities)
Guido van Rossumb9ba4582002-11-14 22:00:19 +00001679
1680
1681# Some day, there might be many Option classes. As of Optik 1.3, the
1682# preferred way to instantiate Options is indirectly, via make_option(),
1683# which will become a factory function when there are many Option
1684# classes.
1685make_option = Option