| 1 | """A powerful, extensible, and easy-to-use option parser.
|
|---|
| 2 |
|
|---|
| 3 | By Greg Ward <gward@python.net>
|
|---|
| 4 |
|
|---|
| 5 | Originally distributed as Optik.
|
|---|
| 6 |
|
|---|
| 7 | For support, use the optik-users@lists.sourceforge.net mailing list
|
|---|
| 8 | (http://lists.sourceforge.net/lists/listinfo/optik-users).
|
|---|
| 9 |
|
|---|
| 10 | Simple 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()
|
|---|
| 22 | """
|
|---|
| 23 |
|
|---|
| 24 | __version__ = "1.5.3"
|
|---|
| 25 |
|
|---|
| 26 | __all__ = ['Option',
|
|---|
| 27 | 'make_option',
|
|---|
| 28 | 'SUPPRESS_HELP',
|
|---|
| 29 | 'SUPPRESS_USAGE',
|
|---|
| 30 | 'Values',
|
|---|
| 31 | 'OptionContainer',
|
|---|
| 32 | 'OptionGroup',
|
|---|
| 33 | 'OptionParser',
|
|---|
| 34 | 'HelpFormatter',
|
|---|
| 35 | 'IndentedHelpFormatter',
|
|---|
| 36 | 'TitledHelpFormatter',
|
|---|
| 37 | 'OptParseError',
|
|---|
| 38 | 'OptionError',
|
|---|
| 39 | 'OptionConflictError',
|
|---|
| 40 | 'OptionValueError',
|
|---|
| 41 | 'BadOptionError']
|
|---|
| 42 |
|
|---|
| 43 | __copyright__ = """
|
|---|
| 44 | Copyright (c) 2001-2006 Gregory P. Ward. All rights reserved.
|
|---|
| 45 | Copyright (c) 2002-2006 Python Software Foundation. All rights reserved.
|
|---|
| 46 |
|
|---|
| 47 | Redistribution and use in source and binary forms, with or without
|
|---|
| 48 | modification, are permitted provided that the following conditions are
|
|---|
| 49 | met:
|
|---|
| 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 |
|
|---|
| 62 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
|
|---|
| 63 | IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|---|
| 64 | TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
|---|
| 65 | PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
|
|---|
| 66 | CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|---|
| 67 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|---|
| 68 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|---|
| 69 | PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|---|
| 70 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|---|
| 71 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|---|
| 72 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|---|
| 73 | """
|
|---|
| 74 |
|
|---|
| 75 | import sys, os
|
|---|
| 76 | import types
|
|---|
| 77 | import textwrap
|
|---|
| 78 |
|
|---|
| 79 | def _repr(self):
|
|---|
| 80 | return "<%s at 0x%x: %s>" % (self.__class__.__name__, id(self), self)
|
|---|
| 81 |
|
|---|
| 82 |
|
|---|
| 83 | # This file was generated from:
|
|---|
| 84 | # Id: option_parser.py 527 2006-07-23 15:21:30Z greg
|
|---|
| 85 | # Id: option.py 522 2006-06-11 16:22:03Z gward
|
|---|
| 86 | # Id: help.py 527 2006-07-23 15:21:30Z greg
|
|---|
| 87 | # Id: errors.py 509 2006-04-20 00:58:24Z gward
|
|---|
| 88 |
|
|---|
| 89 | try:
|
|---|
| 90 | from gettext import gettext
|
|---|
| 91 | except ImportError:
|
|---|
| 92 | def gettext(message):
|
|---|
| 93 | return message
|
|---|
| 94 | _ = gettext
|
|---|
| 95 |
|
|---|
| 96 |
|
|---|
| 97 | class OptParseError (Exception):
|
|---|
| 98 | def __init__(self, msg):
|
|---|
| 99 | self.msg = msg
|
|---|
| 100 |
|
|---|
| 101 | def __str__(self):
|
|---|
| 102 | return self.msg
|
|---|
| 103 |
|
|---|
| 104 |
|
|---|
| 105 | class OptionError (OptParseError):
|
|---|
| 106 | """
|
|---|
| 107 | Raised if an Option instance is created with invalid or
|
|---|
| 108 | inconsistent arguments.
|
|---|
| 109 | """
|
|---|
| 110 |
|
|---|
| 111 | def __init__(self, msg, option):
|
|---|
| 112 | self.msg = msg
|
|---|
| 113 | self.option_id = str(option)
|
|---|
| 114 |
|
|---|
| 115 | def __str__(self):
|
|---|
| 116 | if self.option_id:
|
|---|
| 117 | return "option %s: %s" % (self.option_id, self.msg)
|
|---|
| 118 | else:
|
|---|
| 119 | return self.msg
|
|---|
| 120 |
|
|---|
| 121 | class OptionConflictError (OptionError):
|
|---|
| 122 | """
|
|---|
| 123 | Raised if conflicting options are added to an OptionParser.
|
|---|
| 124 | """
|
|---|
| 125 |
|
|---|
| 126 | class OptionValueError (OptParseError):
|
|---|
| 127 | """
|
|---|
| 128 | Raised if an invalid option value is encountered on the command
|
|---|
| 129 | line.
|
|---|
| 130 | """
|
|---|
| 131 |
|
|---|
| 132 | class BadOptionError (OptParseError):
|
|---|
| 133 | """
|
|---|
| 134 | Raised if an invalid option is seen on the command line.
|
|---|
| 135 | """
|
|---|
| 136 | def __init__(self, opt_str):
|
|---|
| 137 | self.opt_str = opt_str
|
|---|
| 138 |
|
|---|
| 139 | def __str__(self):
|
|---|
| 140 | return _("no such option: %s") % self.opt_str
|
|---|
| 141 |
|
|---|
| 142 | class AmbiguousOptionError (BadOptionError):
|
|---|
| 143 | """
|
|---|
| 144 | Raised if an ambiguous option is seen on the command line.
|
|---|
| 145 | """
|
|---|
| 146 | def __init__(self, opt_str, possibilities):
|
|---|
| 147 | BadOptionError.__init__(self, opt_str)
|
|---|
| 148 | self.possibilities = possibilities
|
|---|
| 149 |
|
|---|
| 150 | def __str__(self):
|
|---|
| 151 | return (_("ambiguous option: %s (%s?)")
|
|---|
| 152 | % (self.opt_str, ", ".join(self.possibilities)))
|
|---|
| 153 |
|
|---|
| 154 |
|
|---|
| 155 | class HelpFormatter:
|
|---|
| 156 |
|
|---|
| 157 | """
|
|---|
| 158 | Abstract base class for formatting option help. OptionParser
|
|---|
| 159 | instances should use one of the HelpFormatter subclasses for
|
|---|
| 160 | formatting help; by default IndentedHelpFormatter is used.
|
|---|
| 161 |
|
|---|
| 162 | Instance attributes:
|
|---|
| 163 | parser : OptionParser
|
|---|
| 164 | the controlling OptionParser instance
|
|---|
| 165 | indent_increment : int
|
|---|
| 166 | the number of columns to indent per nesting level
|
|---|
| 167 | max_help_position : int
|
|---|
| 168 | the maximum starting column for option help text
|
|---|
| 169 | help_position : int
|
|---|
| 170 | the calculated starting column for option help text;
|
|---|
| 171 | initially the same as the maximum
|
|---|
| 172 | width : int
|
|---|
| 173 | total number of columns for output (pass None to constructor for
|
|---|
| 174 | this value to be taken from the $COLUMNS environment variable)
|
|---|
| 175 | level : int
|
|---|
| 176 | current indentation level
|
|---|
| 177 | current_indent : int
|
|---|
| 178 | current indentation level (in columns)
|
|---|
| 179 | help_width : int
|
|---|
| 180 | number of columns available for option help text (calculated)
|
|---|
| 181 | default_tag : str
|
|---|
| 182 | text to replace with each option's default value, "%default"
|
|---|
| 183 | by default. Set to false value to disable default value expansion.
|
|---|
| 184 | option_strings : { Option : str }
|
|---|
| 185 | maps Option instances to the snippet of help text explaining
|
|---|
| 186 | the syntax of that option, e.g. "-h, --help" or
|
|---|
| 187 | "-fFILE, --file=FILE"
|
|---|
| 188 | _short_opt_fmt : str
|
|---|
| 189 | format string controlling how short options with values are
|
|---|
| 190 | printed in help text. Must be either "%s%s" ("-fFILE") or
|
|---|
| 191 | "%s %s" ("-f FILE"), because those are the two syntaxes that
|
|---|
| 192 | Optik supports.
|
|---|
| 193 | _long_opt_fmt : str
|
|---|
| 194 | similar but for long options; must be either "%s %s" ("--file FILE")
|
|---|
| 195 | or "%s=%s" ("--file=FILE").
|
|---|
| 196 | """
|
|---|
| 197 |
|
|---|
| 198 | NO_DEFAULT_VALUE = "none"
|
|---|
| 199 |
|
|---|
| 200 | def __init__(self,
|
|---|
| 201 | indent_increment,
|
|---|
| 202 | max_help_position,
|
|---|
| 203 | width,
|
|---|
| 204 | short_first):
|
|---|
| 205 | self.parser = None
|
|---|
| 206 | self.indent_increment = indent_increment
|
|---|
| 207 | self.help_position = self.max_help_position = max_help_position
|
|---|
| 208 | if width is None:
|
|---|
| 209 | try:
|
|---|
| 210 | width = int(os.environ['COLUMNS'])
|
|---|
| 211 | except (KeyError, ValueError):
|
|---|
| 212 | width = 80
|
|---|
| 213 | width -= 2
|
|---|
| 214 | self.width = width
|
|---|
| 215 | self.current_indent = 0
|
|---|
| 216 | self.level = 0
|
|---|
| 217 | self.help_width = None # computed later
|
|---|
| 218 | self.short_first = short_first
|
|---|
| 219 | self.default_tag = "%default"
|
|---|
| 220 | self.option_strings = {}
|
|---|
| 221 | self._short_opt_fmt = "%s %s"
|
|---|
| 222 | self._long_opt_fmt = "%s=%s"
|
|---|
| 223 |
|
|---|
| 224 | def set_parser(self, parser):
|
|---|
| 225 | self.parser = parser
|
|---|
| 226 |
|
|---|
| 227 | def set_short_opt_delimiter(self, delim):
|
|---|
| 228 | if delim not in ("", " "):
|
|---|
| 229 | raise ValueError(
|
|---|
| 230 | "invalid metavar delimiter for short options: %r" % delim)
|
|---|
| 231 | self._short_opt_fmt = "%s" + delim + "%s"
|
|---|
| 232 |
|
|---|
| 233 | def set_long_opt_delimiter(self, delim):
|
|---|
| 234 | if delim not in ("=", " "):
|
|---|
| 235 | raise ValueError(
|
|---|
| 236 | "invalid metavar delimiter for long options: %r" % delim)
|
|---|
| 237 | self._long_opt_fmt = "%s" + delim + "%s"
|
|---|
| 238 |
|
|---|
| 239 | def indent(self):
|
|---|
| 240 | self.current_indent += self.indent_increment
|
|---|
| 241 | self.level += 1
|
|---|
| 242 |
|
|---|
| 243 | def dedent(self):
|
|---|
| 244 | self.current_indent -= self.indent_increment
|
|---|
| 245 | assert self.current_indent >= 0, "Indent decreased below 0."
|
|---|
| 246 | self.level -= 1
|
|---|
| 247 |
|
|---|
| 248 | def format_usage(self, usage):
|
|---|
| 249 | raise NotImplementedError, "subclasses must implement"
|
|---|
| 250 |
|
|---|
| 251 | def format_heading(self, heading):
|
|---|
| 252 | raise NotImplementedError, "subclasses must implement"
|
|---|
| 253 |
|
|---|
| 254 | def _format_text(self, text):
|
|---|
| 255 | """
|
|---|
| 256 | Format a paragraph of free-form text for inclusion in the
|
|---|
| 257 | help output at the current indentation level.
|
|---|
| 258 | """
|
|---|
| 259 | text_width = self.width - self.current_indent
|
|---|
| 260 | indent = " "*self.current_indent
|
|---|
| 261 | return textwrap.fill(text,
|
|---|
| 262 | text_width,
|
|---|
| 263 | initial_indent=indent,
|
|---|
| 264 | subsequent_indent=indent)
|
|---|
| 265 |
|
|---|
| 266 | def format_description(self, description):
|
|---|
| 267 | if description:
|
|---|
| 268 | return self._format_text(description) + "\n"
|
|---|
| 269 | else:
|
|---|
| 270 | return ""
|
|---|
| 271 |
|
|---|
| 272 | def format_epilog(self, epilog):
|
|---|
| 273 | if epilog:
|
|---|
| 274 | return "\n" + self._format_text(epilog) + "\n"
|
|---|
| 275 | else:
|
|---|
| 276 | return ""
|
|---|
| 277 |
|
|---|
| 278 |
|
|---|
| 279 | def expand_default(self, option):
|
|---|
| 280 | if self.parser is None or not self.default_tag:
|
|---|
| 281 | return option.help
|
|---|
| 282 |
|
|---|
| 283 | default_value = self.parser.defaults.get(option.dest)
|
|---|
| 284 | if default_value is NO_DEFAULT or default_value is None:
|
|---|
| 285 | default_value = self.NO_DEFAULT_VALUE
|
|---|
| 286 |
|
|---|
| 287 | return option.help.replace(self.default_tag, str(default_value))
|
|---|
| 288 |
|
|---|
| 289 | def format_option(self, option):
|
|---|
| 290 | # The help for each option consists of two parts:
|
|---|
| 291 | # * the opt strings and metavars
|
|---|
| 292 | # eg. ("-x", or "-fFILENAME, --file=FILENAME")
|
|---|
| 293 | # * the user-supplied help string
|
|---|
| 294 | # eg. ("turn on expert mode", "read data from FILENAME")
|
|---|
| 295 | #
|
|---|
| 296 | # If possible, we write both of these on the same line:
|
|---|
| 297 | # -x turn on expert mode
|
|---|
| 298 | #
|
|---|
| 299 | # But if the opt string list is too long, we put the help
|
|---|
| 300 | # string on a second line, indented to the same column it would
|
|---|
| 301 | # start in if it fit on the first line.
|
|---|
| 302 | # -fFILENAME, --file=FILENAME
|
|---|
| 303 | # read data from FILENAME
|
|---|
| 304 | result = []
|
|---|
| 305 | opts = self.option_strings[option]
|
|---|
| 306 | opt_width = self.help_position - self.current_indent - 2
|
|---|
| 307 | if len(opts) > opt_width:
|
|---|
| 308 | opts = "%*s%s\n" % (self.current_indent, "", opts)
|
|---|
| 309 | indent_first = self.help_position
|
|---|
| 310 | else: # start help on same line as opts
|
|---|
| 311 | opts = "%*s%-*s " % (self.current_indent, "", opt_width, opts)
|
|---|
| 312 | indent_first = 0
|
|---|
| 313 | result.append(opts)
|
|---|
| 314 | if option.help:
|
|---|
| 315 | help_text = self.expand_default(option)
|
|---|
| 316 | help_lines = textwrap.wrap(help_text, self.help_width)
|
|---|
| 317 | result.append("%*s%s\n" % (indent_first, "", help_lines[0]))
|
|---|
| 318 | result.extend(["%*s%s\n" % (self.help_position, "", line)
|
|---|
| 319 | for line in help_lines[1:]])
|
|---|
| 320 | elif opts[-1] != "\n":
|
|---|
| 321 | result.append("\n")
|
|---|
| 322 | return "".join(result)
|
|---|
| 323 |
|
|---|
| 324 | def store_option_strings(self, parser):
|
|---|
| 325 | self.indent()
|
|---|
| 326 | max_len = 0
|
|---|
| 327 | for opt in parser.option_list:
|
|---|
| 328 | strings = self.format_option_strings(opt)
|
|---|
| 329 | self.option_strings[opt] = strings
|
|---|
| 330 | max_len = max(max_len, len(strings) + self.current_indent)
|
|---|
| 331 | self.indent()
|
|---|
| 332 | for group in parser.option_groups:
|
|---|
| 333 | for opt in group.option_list:
|
|---|
| 334 | strings = self.format_option_strings(opt)
|
|---|
| 335 | self.option_strings[opt] = strings
|
|---|
| 336 | max_len = max(max_len, len(strings) + self.current_indent)
|
|---|
| 337 | self.dedent()
|
|---|
| 338 | self.dedent()
|
|---|
| 339 | self.help_position = min(max_len + 2, self.max_help_position)
|
|---|
| 340 | self.help_width = self.width - self.help_position
|
|---|
| 341 |
|
|---|
| 342 | def format_option_strings(self, option):
|
|---|
| 343 | """Return a comma-separated list of option strings & metavariables."""
|
|---|
| 344 | if option.takes_value():
|
|---|
| 345 | metavar = option.metavar or option.dest.upper()
|
|---|
| 346 | short_opts = [self._short_opt_fmt % (sopt, metavar)
|
|---|
| 347 | for sopt in option._short_opts]
|
|---|
| 348 | long_opts = [self._long_opt_fmt % (lopt, metavar)
|
|---|
| 349 | for lopt in option._long_opts]
|
|---|
| 350 | else:
|
|---|
| 351 | short_opts = option._short_opts
|
|---|
| 352 | long_opts = option._long_opts
|
|---|
| 353 |
|
|---|
| 354 | if self.short_first:
|
|---|
| 355 | opts = short_opts + long_opts
|
|---|
| 356 | else:
|
|---|
| 357 | opts = long_opts + short_opts
|
|---|
| 358 |
|
|---|
| 359 | return ", ".join(opts)
|
|---|
| 360 |
|
|---|
| 361 | class IndentedHelpFormatter (HelpFormatter):
|
|---|
| 362 | """Format help with indented section bodies.
|
|---|
| 363 | """
|
|---|
| 364 |
|
|---|
| 365 | def __init__(self,
|
|---|
| 366 | indent_increment=2,
|
|---|
| 367 | max_help_position=24,
|
|---|
| 368 | width=None,
|
|---|
| 369 | short_first=1):
|
|---|
| 370 | HelpFormatter.__init__(
|
|---|
| 371 | self, indent_increment, max_help_position, width, short_first)
|
|---|
| 372 |
|
|---|
| 373 | def format_usage(self, usage):
|
|---|
| 374 | return _("Usage: %s\n") % usage
|
|---|
| 375 |
|
|---|
| 376 | def format_heading(self, heading):
|
|---|
| 377 | return "%*s%s:\n" % (self.current_indent, "", heading)
|
|---|
| 378 |
|
|---|
| 379 |
|
|---|
| 380 | class TitledHelpFormatter (HelpFormatter):
|
|---|
| 381 | """Format help with underlined section headers.
|
|---|
| 382 | """
|
|---|
| 383 |
|
|---|
| 384 | def __init__(self,
|
|---|
| 385 | indent_increment=0,
|
|---|
| 386 | max_help_position=24,
|
|---|
| 387 | width=None,
|
|---|
| 388 | short_first=0):
|
|---|
| 389 | HelpFormatter.__init__ (
|
|---|
| 390 | self, indent_increment, max_help_position, width, short_first)
|
|---|
| 391 |
|
|---|
| 392 | def format_usage(self, usage):
|
|---|
| 393 | return "%s %s\n" % (self.format_heading(_("Usage")), usage)
|
|---|
| 394 |
|
|---|
| 395 | def format_heading(self, heading):
|
|---|
| 396 | return "%s\n%s\n" % (heading, "=-"[self.level] * len(heading))
|
|---|
| 397 |
|
|---|
| 398 |
|
|---|
| 399 | def _parse_num(val, type):
|
|---|
| 400 | if val[:2].lower() == "0x": # hexadecimal
|
|---|
| 401 | radix = 16
|
|---|
| 402 | elif val[:2].lower() == "0b": # binary
|
|---|
| 403 | radix = 2
|
|---|
| 404 | val = val[2:] or "0" # have to remove "0b" prefix
|
|---|
| 405 | elif val[:1] == "0": # octal
|
|---|
| 406 | radix = 8
|
|---|
| 407 | else: # decimal
|
|---|
| 408 | radix = 10
|
|---|
| 409 |
|
|---|
| 410 | return type(val, radix)
|
|---|
| 411 |
|
|---|
| 412 | def _parse_int(val):
|
|---|
| 413 | return _parse_num(val, int)
|
|---|
| 414 |
|
|---|
| 415 | def _parse_long(val):
|
|---|
| 416 | return _parse_num(val, long)
|
|---|
| 417 |
|
|---|
| 418 | _builtin_cvt = { "int" : (_parse_int, _("integer")),
|
|---|
| 419 | "long" : (_parse_long, _("long integer")),
|
|---|
| 420 | "float" : (float, _("floating-point")),
|
|---|
| 421 | "complex" : (complex, _("complex")) }
|
|---|
| 422 |
|
|---|
| 423 | def check_builtin(option, opt, value):
|
|---|
| 424 | (cvt, what) = _builtin_cvt[option.type]
|
|---|
| 425 | try:
|
|---|
| 426 | return cvt(value)
|
|---|
| 427 | except ValueError:
|
|---|
| 428 | raise OptionValueError(
|
|---|
| 429 | _("option %s: invalid %s value: %r") % (opt, what, value))
|
|---|
| 430 |
|
|---|
| 431 | def check_choice(option, opt, value):
|
|---|
| 432 | if value in option.choices:
|
|---|
| 433 | return value
|
|---|
| 434 | else:
|
|---|
| 435 | choices = ", ".join(map(repr, option.choices))
|
|---|
| 436 | raise OptionValueError(
|
|---|
| 437 | _("option %s: invalid choice: %r (choose from %s)")
|
|---|
| 438 | % (opt, value, choices))
|
|---|
| 439 |
|
|---|
| 440 | # Not supplying a default is different from a default of None,
|
|---|
| 441 | # so we need an explicit "not supplied" value.
|
|---|
| 442 | NO_DEFAULT = ("NO", "DEFAULT")
|
|---|
| 443 |
|
|---|
| 444 |
|
|---|
| 445 | class Option:
|
|---|
| 446 | """
|
|---|
| 447 | Instance attributes:
|
|---|
| 448 | _short_opts : [string]
|
|---|
| 449 | _long_opts : [string]
|
|---|
| 450 |
|
|---|
| 451 | action : string
|
|---|
| 452 | type : string
|
|---|
| 453 | dest : string
|
|---|
| 454 | default : any
|
|---|
| 455 | nargs : int
|
|---|
| 456 | const : any
|
|---|
| 457 | choices : [string]
|
|---|
| 458 | callback : function
|
|---|
| 459 | callback_args : (any*)
|
|---|
| 460 | callback_kwargs : { string : any }
|
|---|
| 461 | help : string
|
|---|
| 462 | metavar : string
|
|---|
| 463 | """
|
|---|
| 464 |
|
|---|
| 465 | # The list of instance attributes that may be set through
|
|---|
| 466 | # keyword args to the constructor.
|
|---|
| 467 | ATTRS = ['action',
|
|---|
| 468 | 'type',
|
|---|
| 469 | 'dest',
|
|---|
| 470 | 'default',
|
|---|
| 471 | 'nargs',
|
|---|
| 472 | 'const',
|
|---|
| 473 | 'choices',
|
|---|
| 474 | 'callback',
|
|---|
| 475 | 'callback_args',
|
|---|
| 476 | 'callback_kwargs',
|
|---|
| 477 | 'help',
|
|---|
| 478 | 'metavar']
|
|---|
| 479 |
|
|---|
| 480 | # The set of actions allowed by option parsers. Explicitly listed
|
|---|
| 481 | # here so the constructor can validate its arguments.
|
|---|
| 482 | ACTIONS = ("store",
|
|---|
| 483 | "store_const",
|
|---|
| 484 | "store_true",
|
|---|
| 485 | "store_false",
|
|---|
| 486 | "append",
|
|---|
| 487 | "append_const",
|
|---|
| 488 | "count",
|
|---|
| 489 | "callback",
|
|---|
| 490 | "help",
|
|---|
| 491 | "version")
|
|---|
| 492 |
|
|---|
| 493 | # The set of actions that involve storing a value somewhere;
|
|---|
| 494 | # also listed just for constructor argument validation. (If
|
|---|
| 495 | # the action is one of these, there must be a destination.)
|
|---|
| 496 | STORE_ACTIONS = ("store",
|
|---|
| 497 | "store_const",
|
|---|
| 498 | "store_true",
|
|---|
| 499 | "store_false",
|
|---|
| 500 | "append",
|
|---|
| 501 | "append_const",
|
|---|
| 502 | "count")
|
|---|
| 503 |
|
|---|
| 504 | # The set of actions for which it makes sense to supply a value
|
|---|
| 505 | # type, ie. which may consume an argument from the command line.
|
|---|
| 506 | TYPED_ACTIONS = ("store",
|
|---|
| 507 | "append",
|
|---|
| 508 | "callback")
|
|---|
| 509 |
|
|---|
| 510 | # The set of actions which *require* a value type, ie. that
|
|---|
| 511 | # always consume an argument from the command line.
|
|---|
| 512 | ALWAYS_TYPED_ACTIONS = ("store",
|
|---|
| 513 | "append")
|
|---|
| 514 |
|
|---|
| 515 | # The set of actions which take a 'const' attribute.
|
|---|
| 516 | CONST_ACTIONS = ("store_const",
|
|---|
| 517 | "append_const")
|
|---|
| 518 |
|
|---|
| 519 | # The set of known types for option parsers. Again, listed here for
|
|---|
| 520 | # constructor argument validation.
|
|---|
| 521 | TYPES = ("string", "int", "long", "float", "complex", "choice")
|
|---|
| 522 |
|
|---|
| 523 | # Dictionary of argument checking functions, which convert and
|
|---|
| 524 | # validate option arguments according to the option type.
|
|---|
| 525 | #
|
|---|
| 526 | # Signature of checking functions is:
|
|---|
| 527 | # check(option : Option, opt : string, value : string) -> any
|
|---|
| 528 | # where
|
|---|
| 529 | # option is the Option instance calling the checker
|
|---|
| 530 | # opt is the actual option seen on the command-line
|
|---|
| 531 | # (eg. "-a", "--file")
|
|---|
| 532 | # value is the option argument seen on the command-line
|
|---|
| 533 | #
|
|---|
| 534 | # The return value should be in the appropriate Python type
|
|---|
| 535 | # for option.type -- eg. an integer if option.type == "int".
|
|---|
| 536 | #
|
|---|
| 537 | # If no checker is defined for a type, arguments will be
|
|---|
| 538 | # unchecked and remain strings.
|
|---|
| 539 | TYPE_CHECKER = { "int" : check_builtin,
|
|---|
| 540 | "long" : check_builtin,
|
|---|
| 541 | "float" : check_builtin,
|
|---|
| 542 | "complex": check_builtin,
|
|---|
| 543 | "choice" : check_choice,
|
|---|
| 544 | }
|
|---|
| 545 |
|
|---|
| 546 |
|
|---|
| 547 | # CHECK_METHODS is a list of unbound method objects; they are called
|
|---|
| 548 | # by the constructor, in order, after all attributes are
|
|---|
| 549 | # initialized. The list is created and filled in later, after all
|
|---|
| 550 | # the methods are actually defined. (I just put it here because I
|
|---|
| 551 | # like to define and document all class attributes in the same
|
|---|
| 552 | # place.) Subclasses that add another _check_*() method should
|
|---|
| 553 | # define their own CHECK_METHODS list that adds their check method
|
|---|
| 554 | # to those from this class.
|
|---|
| 555 | CHECK_METHODS = None
|
|---|
| 556 |
|
|---|
| 557 |
|
|---|
| 558 | # -- Constructor/initialization methods ----------------------------
|
|---|
| 559 |
|
|---|
| 560 | def __init__(self, *opts, **attrs):
|
|---|
| 561 | # Set _short_opts, _long_opts attrs from 'opts' tuple.
|
|---|
| 562 | # Have to be set now, in case no option strings are supplied.
|
|---|
| 563 | self._short_opts = []
|
|---|
| 564 | self._long_opts = []
|
|---|
| 565 | opts = self._check_opt_strings(opts)
|
|---|
| 566 | self._set_opt_strings(opts)
|
|---|
| 567 |
|
|---|
| 568 | # Set all other attrs (action, type, etc.) from 'attrs' dict
|
|---|
| 569 | self._set_attrs(attrs)
|
|---|
| 570 |
|
|---|
| 571 | # Check all the attributes we just set. There are lots of
|
|---|
| 572 | # complicated interdependencies, but luckily they can be farmed
|
|---|
| 573 | # out to the _check_*() methods listed in CHECK_METHODS -- which
|
|---|
| 574 | # could be handy for subclasses! The one thing these all share
|
|---|
| 575 | # is that they raise OptionError if they discover a problem.
|
|---|
| 576 | for checker in self.CHECK_METHODS:
|
|---|
| 577 | checker(self)
|
|---|
| 578 |
|
|---|
| 579 | def _check_opt_strings(self, opts):
|
|---|
| 580 | # Filter out None because early versions of Optik had exactly
|
|---|
| 581 | # one short option and one long option, either of which
|
|---|
| 582 | # could be None.
|
|---|
| 583 | opts = filter(None, opts)
|
|---|
| 584 | if not opts:
|
|---|
| 585 | raise TypeError("at least one option string must be supplied")
|
|---|
| 586 | return opts
|
|---|
| 587 |
|
|---|
| 588 | def _set_opt_strings(self, opts):
|
|---|
| 589 | for opt in opts:
|
|---|
| 590 | if len(opt) < 2:
|
|---|
| 591 | raise OptionError(
|
|---|
| 592 | "invalid option string %r: "
|
|---|
| 593 | "must be at least two characters long" % opt, self)
|
|---|
| 594 | elif len(opt) == 2:
|
|---|
| 595 | if not (opt[0] == "-" and opt[1] != "-"):
|
|---|
| 596 | raise OptionError(
|
|---|
| 597 | "invalid short option string %r: "
|
|---|
| 598 | "must be of the form -x, (x any non-dash char)" % opt,
|
|---|
| 599 | self)
|
|---|
| 600 | self._short_opts.append(opt)
|
|---|
| 601 | else:
|
|---|
| 602 | if not (opt[0:2] == "--" and opt[2] != "-"):
|
|---|
| 603 | raise OptionError(
|
|---|
| 604 | "invalid long option string %r: "
|
|---|
| 605 | "must start with --, followed by non-dash" % opt,
|
|---|
| 606 | self)
|
|---|
| 607 | self._long_opts.append(opt)
|
|---|
| 608 |
|
|---|
| 609 | def _set_attrs(self, attrs):
|
|---|
| 610 | for attr in self.ATTRS:
|
|---|
| 611 | if attr in attrs:
|
|---|
| 612 | setattr(self, attr, attrs[attr])
|
|---|
| 613 | del attrs[attr]
|
|---|
| 614 | else:
|
|---|
| 615 | if attr == 'default':
|
|---|
| 616 | setattr(self, attr, NO_DEFAULT)
|
|---|
| 617 | else:
|
|---|
| 618 | setattr(self, attr, None)
|
|---|
| 619 | if attrs:
|
|---|
| 620 | attrs = attrs.keys()
|
|---|
| 621 | attrs.sort()
|
|---|
| 622 | raise OptionError(
|
|---|
| 623 | "invalid keyword arguments: %s" % ", ".join(attrs),
|
|---|
| 624 | self)
|
|---|
| 625 |
|
|---|
| 626 |
|
|---|
| 627 | # -- Constructor validation methods --------------------------------
|
|---|
| 628 |
|
|---|
| 629 | def _check_action(self):
|
|---|
| 630 | if self.action is None:
|
|---|
| 631 | self.action = "store"
|
|---|
| 632 | elif self.action not in self.ACTIONS:
|
|---|
| 633 | raise OptionError("invalid action: %r" % self.action, self)
|
|---|
| 634 |
|
|---|
| 635 | def _check_type(self):
|
|---|
| 636 | if self.type is None:
|
|---|
| 637 | if self.action in self.ALWAYS_TYPED_ACTIONS:
|
|---|
| 638 | if self.choices is not None:
|
|---|
| 639 | # The "choices" attribute implies "choice" type.
|
|---|
| 640 | self.type = "choice"
|
|---|
| 641 | else:
|
|---|
| 642 | # No type given? "string" is the most sensible default.
|
|---|
| 643 | self.type = "string"
|
|---|
| 644 | else:
|
|---|
| 645 | # Allow type objects or builtin type conversion functions
|
|---|
| 646 | # (int, str, etc.) as an alternative to their names. (The
|
|---|
| 647 | # complicated check of __builtin__ is only necessary for
|
|---|
| 648 | # Python 2.1 and earlier, and is short-circuited by the
|
|---|
| 649 | # first check on modern Pythons.)
|
|---|
| 650 | import __builtin__
|
|---|
| 651 | if ( type(self.type) is types.TypeType or
|
|---|
| 652 | (hasattr(self.type, "__name__") and
|
|---|
| 653 | getattr(__builtin__, self.type.__name__, None) is self.type) ):
|
|---|
| 654 | self.type = self.type.__name__
|
|---|
| 655 |
|
|---|
| 656 | if self.type == "str":
|
|---|
| 657 | self.type = "string"
|
|---|
| 658 |
|
|---|
| 659 | if self.type not in self.TYPES:
|
|---|
| 660 | raise OptionError("invalid option type: %r" % self.type, self)
|
|---|
| 661 | if self.action not in self.TYPED_ACTIONS:
|
|---|
| 662 | raise OptionError(
|
|---|
| 663 | "must not supply a type for action %r" % self.action, self)
|
|---|
| 664 |
|
|---|
| 665 | def _check_choice(self):
|
|---|
| 666 | if self.type == "choice":
|
|---|
| 667 | if self.choices is None:
|
|---|
| 668 | raise OptionError(
|
|---|
| 669 | "must supply a list of choices for type 'choice'", self)
|
|---|
| 670 | elif type(self.choices) not in (types.TupleType, types.ListType):
|
|---|
| 671 | raise OptionError(
|
|---|
| 672 | "choices must be a list of strings ('%s' supplied)"
|
|---|
| 673 | % str(type(self.choices)).split("'")[1], self)
|
|---|
| 674 | elif self.choices is not None:
|
|---|
| 675 | raise OptionError(
|
|---|
| 676 | "must not supply choices for type %r" % self.type, self)
|
|---|
| 677 |
|
|---|
| 678 | def _check_dest(self):
|
|---|
| 679 | # No destination given, and we need one for this action. The
|
|---|
| 680 | # self.type check is for callbacks that take a value.
|
|---|
| 681 | takes_value = (self.action in self.STORE_ACTIONS or
|
|---|
| 682 | self.type is not None)
|
|---|
| 683 | if self.dest is None and takes_value:
|
|---|
| 684 |
|
|---|
| 685 | # Glean a destination from the first long option string,
|
|---|
| 686 | # or from the first short option string if no long options.
|
|---|
| 687 | if self._long_opts:
|
|---|
| 688 | # eg. "--foo-bar" -> "foo_bar"
|
|---|
| 689 | self.dest = self._long_opts[0][2:].replace('-', '_')
|
|---|
| 690 | else:
|
|---|
| 691 | self.dest = self._short_opts[0][1]
|
|---|
| 692 |
|
|---|
| 693 | def _check_const(self):
|
|---|
| 694 | if self.action not in self.CONST_ACTIONS and self.const is not None:
|
|---|
| 695 | raise OptionError(
|
|---|
| 696 | "'const' must not be supplied for action %r" % self.action,
|
|---|
| 697 | self)
|
|---|
| 698 |
|
|---|
| 699 | def _check_nargs(self):
|
|---|
| 700 | if self.action in self.TYPED_ACTIONS:
|
|---|
| 701 | if self.nargs is None:
|
|---|
| 702 | self.nargs = 1
|
|---|
| 703 | elif self.nargs is not None:
|
|---|
| 704 | raise OptionError(
|
|---|
| 705 | "'nargs' must not be supplied for action %r" % self.action,
|
|---|
| 706 | self)
|
|---|
| 707 |
|
|---|
| 708 | def _check_callback(self):
|
|---|
| 709 | if self.action == "callback":
|
|---|
| 710 | if not hasattr(self.callback, '__call__'):
|
|---|
| 711 | raise OptionError(
|
|---|
| 712 | "callback not callable: %r" % self.callback, self)
|
|---|
| 713 | if (self.callback_args is not None and
|
|---|
| 714 | type(self.callback_args) is not types.TupleType):
|
|---|
| 715 | raise OptionError(
|
|---|
| 716 | "callback_args, if supplied, must be a tuple: not %r"
|
|---|
| 717 | % self.callback_args, self)
|
|---|
| 718 | if (self.callback_kwargs is not None and
|
|---|
| 719 | type(self.callback_kwargs) is not types.DictType):
|
|---|
| 720 | raise OptionError(
|
|---|
| 721 | "callback_kwargs, if supplied, must be a dict: not %r"
|
|---|
| 722 | % self.callback_kwargs, self)
|
|---|
| 723 | else:
|
|---|
| 724 | if self.callback is not None:
|
|---|
| 725 | raise OptionError(
|
|---|
| 726 | "callback supplied (%r) for non-callback option"
|
|---|
| 727 | % self.callback, self)
|
|---|
| 728 | if self.callback_args is not None:
|
|---|
| 729 | raise OptionError(
|
|---|
| 730 | "callback_args supplied for non-callback option", self)
|
|---|
| 731 | if self.callback_kwargs is not None:
|
|---|
| 732 | raise OptionError(
|
|---|
| 733 | "callback_kwargs supplied for non-callback option", self)
|
|---|
| 734 |
|
|---|
| 735 |
|
|---|
| 736 | CHECK_METHODS = [_check_action,
|
|---|
| 737 | _check_type,
|
|---|
| 738 | _check_choice,
|
|---|
| 739 | _check_dest,
|
|---|
| 740 | _check_const,
|
|---|
| 741 | _check_nargs,
|
|---|
| 742 | _check_callback]
|
|---|
| 743 |
|
|---|
| 744 |
|
|---|
| 745 | # -- Miscellaneous methods -----------------------------------------
|
|---|
| 746 |
|
|---|
| 747 | def __str__(self):
|
|---|
| 748 | return "/".join(self._short_opts + self._long_opts)
|
|---|
| 749 |
|
|---|
| 750 | __repr__ = _repr
|
|---|
| 751 |
|
|---|
| 752 | def takes_value(self):
|
|---|
| 753 | return self.type is not None
|
|---|
| 754 |
|
|---|
| 755 | def get_opt_string(self):
|
|---|
| 756 | if self._long_opts:
|
|---|
| 757 | return self._long_opts[0]
|
|---|
| 758 | else:
|
|---|
| 759 | return self._short_opts[0]
|
|---|
| 760 |
|
|---|
| 761 |
|
|---|
| 762 | # -- Processing methods --------------------------------------------
|
|---|
| 763 |
|
|---|
| 764 | def check_value(self, opt, value):
|
|---|
| 765 | checker = self.TYPE_CHECKER.get(self.type)
|
|---|
| 766 | if checker is None:
|
|---|
| 767 | return value
|
|---|
| 768 | else:
|
|---|
| 769 | return checker(self, opt, value)
|
|---|
| 770 |
|
|---|
| 771 | def convert_value(self, opt, value):
|
|---|
| 772 | if value is not None:
|
|---|
| 773 | if self.nargs == 1:
|
|---|
| 774 | return self.check_value(opt, value)
|
|---|
| 775 | else:
|
|---|
| 776 | return tuple([self.check_value(opt, v) for v in value])
|
|---|
| 777 |
|
|---|
| 778 | def process(self, opt, value, values, parser):
|
|---|
| 779 |
|
|---|
| 780 | # First, convert the value(s) to the right type. Howl if any
|
|---|
| 781 | # value(s) are bogus.
|
|---|
| 782 | value = self.convert_value(opt, value)
|
|---|
| 783 |
|
|---|
| 784 | # And then take whatever action is expected of us.
|
|---|
| 785 | # This is a separate method to make life easier for
|
|---|
| 786 | # subclasses to add new actions.
|
|---|
| 787 | return self.take_action(
|
|---|
| 788 | self.action, self.dest, opt, value, values, parser)
|
|---|
| 789 |
|
|---|
| 790 | def take_action(self, action, dest, opt, value, values, parser):
|
|---|
| 791 | if action == "store":
|
|---|
| 792 | setattr(values, dest, value)
|
|---|
| 793 | elif action == "store_const":
|
|---|
| 794 | setattr(values, dest, self.const)
|
|---|
| 795 | elif action == "store_true":
|
|---|
| 796 | setattr(values, dest, True)
|
|---|
| 797 | elif action == "store_false":
|
|---|
| 798 | setattr(values, dest, False)
|
|---|
| 799 | elif action == "append":
|
|---|
| 800 | values.ensure_value(dest, []).append(value)
|
|---|
| 801 | elif action == "append_const":
|
|---|
| 802 | values.ensure_value(dest, []).append(self.const)
|
|---|
| 803 | elif action == "count":
|
|---|
| 804 | setattr(values, dest, values.ensure_value(dest, 0) + 1)
|
|---|
| 805 | elif action == "callback":
|
|---|
| 806 | args = self.callback_args or ()
|
|---|
| 807 | kwargs = self.callback_kwargs or {}
|
|---|
| 808 | self.callback(self, opt, value, parser, *args, **kwargs)
|
|---|
| 809 | elif action == "help":
|
|---|
| 810 | parser.print_help()
|
|---|
| 811 | parser.exit()
|
|---|
| 812 | elif action == "version":
|
|---|
| 813 | parser.print_version()
|
|---|
| 814 | parser.exit()
|
|---|
| 815 | else:
|
|---|
| 816 | raise RuntimeError, "unknown action %r" % self.action
|
|---|
| 817 |
|
|---|
| 818 | return 1
|
|---|
| 819 |
|
|---|
| 820 | # class Option
|
|---|
| 821 |
|
|---|
| 822 |
|
|---|
| 823 | SUPPRESS_HELP = "SUPPRESS"+"HELP"
|
|---|
| 824 | SUPPRESS_USAGE = "SUPPRESS"+"USAGE"
|
|---|
| 825 |
|
|---|
| 826 | try:
|
|---|
| 827 | basestring
|
|---|
| 828 | except NameError:
|
|---|
| 829 | def isbasestring(x):
|
|---|
| 830 | return isinstance(x, (types.StringType, types.UnicodeType))
|
|---|
| 831 | else:
|
|---|
| 832 | def isbasestring(x):
|
|---|
| 833 | return isinstance(x, basestring)
|
|---|
| 834 |
|
|---|
| 835 | class Values:
|
|---|
| 836 |
|
|---|
| 837 | def __init__(self, defaults=None):
|
|---|
| 838 | if defaults:
|
|---|
| 839 | for (attr, val) in defaults.items():
|
|---|
| 840 | setattr(self, attr, val)
|
|---|
| 841 |
|
|---|
| 842 | def __str__(self):
|
|---|
| 843 | return str(self.__dict__)
|
|---|
| 844 |
|
|---|
| 845 | __repr__ = _repr
|
|---|
| 846 |
|
|---|
| 847 | def __cmp__(self, other):
|
|---|
| 848 | if isinstance(other, Values):
|
|---|
| 849 | return cmp(self.__dict__, other.__dict__)
|
|---|
| 850 | elif isinstance(other, types.DictType):
|
|---|
| 851 | return cmp(self.__dict__, other)
|
|---|
| 852 | else:
|
|---|
| 853 | return -1
|
|---|
| 854 |
|
|---|
| 855 | def _update_careful(self, dict):
|
|---|
| 856 | """
|
|---|
| 857 | Update the option values from an arbitrary dictionary, but only
|
|---|
| 858 | use keys from dict that already have a corresponding attribute
|
|---|
| 859 | in self. Any keys in dict without a corresponding attribute
|
|---|
| 860 | are silently ignored.
|
|---|
| 861 | """
|
|---|
| 862 | for attr in dir(self):
|
|---|
| 863 | if attr in dict:
|
|---|
| 864 | dval = dict[attr]
|
|---|
| 865 | if dval is not None:
|
|---|
| 866 | setattr(self, attr, dval)
|
|---|
| 867 |
|
|---|
| 868 | def _update_loose(self, dict):
|
|---|
| 869 | """
|
|---|
| 870 | Update the option values from an arbitrary dictionary,
|
|---|
| 871 | using all keys from the dictionary regardless of whether
|
|---|
| 872 | they have a corresponding attribute in self or not.
|
|---|
| 873 | """
|
|---|
| 874 | self.__dict__.update(dict)
|
|---|
| 875 |
|
|---|
| 876 | def _update(self, dict, mode):
|
|---|
| 877 | if mode == "careful":
|
|---|
| 878 | self._update_careful(dict)
|
|---|
| 879 | elif mode == "loose":
|
|---|
| 880 | self._update_loose(dict)
|
|---|
| 881 | else:
|
|---|
| 882 | raise ValueError, "invalid update mode: %r" % mode
|
|---|
| 883 |
|
|---|
| 884 | def read_module(self, modname, mode="careful"):
|
|---|
| 885 | __import__(modname)
|
|---|
| 886 | mod = sys.modules[modname]
|
|---|
| 887 | self._update(vars(mod), mode)
|
|---|
| 888 |
|
|---|
| 889 | def read_file(self, filename, mode="careful"):
|
|---|
| 890 | vars = {}
|
|---|
| 891 | execfile(filename, vars)
|
|---|
| 892 | self._update(vars, mode)
|
|---|
| 893 |
|
|---|
| 894 | def ensure_value(self, attr, value):
|
|---|
| 895 | if not hasattr(self, attr) or getattr(self, attr) is None:
|
|---|
| 896 | setattr(self, attr, value)
|
|---|
| 897 | return getattr(self, attr)
|
|---|
| 898 |
|
|---|
| 899 |
|
|---|
| 900 | class OptionContainer:
|
|---|
| 901 |
|
|---|
| 902 | """
|
|---|
| 903 | Abstract base class.
|
|---|
| 904 |
|
|---|
| 905 | Class attributes:
|
|---|
| 906 | standard_option_list : [Option]
|
|---|
| 907 | list of standard options that will be accepted by all instances
|
|---|
| 908 | of this parser class (intended to be overridden by subclasses).
|
|---|
| 909 |
|
|---|
| 910 | Instance attributes:
|
|---|
| 911 | option_list : [Option]
|
|---|
| 912 | the list of Option objects contained by this OptionContainer
|
|---|
| 913 | _short_opt : { string : Option }
|
|---|
| 914 | dictionary mapping short option strings, eg. "-f" or "-X",
|
|---|
| 915 | to the Option instances that implement them. If an Option
|
|---|
| 916 | has multiple short option strings, it will appears in this
|
|---|
| 917 | dictionary multiple times. [1]
|
|---|
| 918 | _long_opt : { string : Option }
|
|---|
| 919 | dictionary mapping long option strings, eg. "--file" or
|
|---|
| 920 | "--exclude", to the Option instances that implement them.
|
|---|
| 921 | Again, a given Option can occur multiple times in this
|
|---|
| 922 | dictionary. [1]
|
|---|
| 923 | defaults : { string : any }
|
|---|
| 924 | dictionary mapping option destination names to default
|
|---|
| 925 | values for each destination [1]
|
|---|
| 926 |
|
|---|
| 927 | [1] These mappings are common to (shared by) all components of the
|
|---|
| 928 | controlling OptionParser, where they are initially created.
|
|---|
| 929 |
|
|---|
| 930 | """
|
|---|
| 931 |
|
|---|
| 932 | def __init__(self, option_class, conflict_handler, description):
|
|---|
| 933 | # Initialize the option list and related data structures.
|
|---|
| 934 | # This method must be provided by subclasses, and it must
|
|---|
| 935 | # initialize at least the following instance attributes:
|
|---|
| 936 | # option_list, _short_opt, _long_opt, defaults.
|
|---|
| 937 | self._create_option_list()
|
|---|
| 938 |
|
|---|
| 939 | self.option_class = option_class
|
|---|
| 940 | self.set_conflict_handler(conflict_handler)
|
|---|
| 941 | self.set_description(description)
|
|---|
| 942 |
|
|---|
| 943 | def _create_option_mappings(self):
|
|---|
| 944 | # For use by OptionParser constructor -- create the master
|
|---|
| 945 | # option mappings used by this OptionParser and all
|
|---|
| 946 | # OptionGroups that it owns.
|
|---|
| 947 | self._short_opt = {} # single letter -> Option instance
|
|---|
| 948 | self._long_opt = {} # long option -> Option instance
|
|---|
| 949 | self.defaults = {} # maps option dest -> default value
|
|---|
| 950 |
|
|---|
| 951 |
|
|---|
| 952 | def _share_option_mappings(self, parser):
|
|---|
| 953 | # For use by OptionGroup constructor -- use shared option
|
|---|
| 954 | # mappings from the OptionParser that owns this OptionGroup.
|
|---|
| 955 | self._short_opt = parser._short_opt
|
|---|
| 956 | self._long_opt = parser._long_opt
|
|---|
| 957 | self.defaults = parser.defaults
|
|---|
| 958 |
|
|---|
| 959 | def set_conflict_handler(self, handler):
|
|---|
| 960 | if handler not in ("error", "resolve"):
|
|---|
| 961 | raise ValueError, "invalid conflict_resolution value %r" % handler
|
|---|
| 962 | self.conflict_handler = handler
|
|---|
| 963 |
|
|---|
| 964 | def set_description(self, description):
|
|---|
| 965 | self.description = description
|
|---|
| 966 |
|
|---|
| 967 | def get_description(self):
|
|---|
| 968 | return self.description
|
|---|
| 969 |
|
|---|
| 970 |
|
|---|
| 971 | def destroy(self):
|
|---|
| 972 | """see OptionParser.destroy()."""
|
|---|
| 973 | del self._short_opt
|
|---|
| 974 | del self._long_opt
|
|---|
| 975 | del self.defaults
|
|---|
| 976 |
|
|---|
| 977 |
|
|---|
| 978 | # -- Option-adding methods -----------------------------------------
|
|---|
| 979 |
|
|---|
| 980 | def _check_conflict(self, option):
|
|---|
| 981 | conflict_opts = []
|
|---|
| 982 | for opt in option._short_opts:
|
|---|
| 983 | if opt in self._short_opt:
|
|---|
| 984 | conflict_opts.append((opt, self._short_opt[opt]))
|
|---|
| 985 | for opt in option._long_opts:
|
|---|
| 986 | if opt in self._long_opt:
|
|---|
| 987 | conflict_opts.append((opt, self._long_opt[opt]))
|
|---|
| 988 |
|
|---|
| 989 | if conflict_opts:
|
|---|
| 990 | handler = self.conflict_handler
|
|---|
| 991 | if handler == "error":
|
|---|
| 992 | raise OptionConflictError(
|
|---|
| 993 | "conflicting option string(s): %s"
|
|---|
| 994 | % ", ".join([co[0] for co in conflict_opts]),
|
|---|
| 995 | option)
|
|---|
| 996 | elif handler == "resolve":
|
|---|
| 997 | for (opt, c_option) in conflict_opts:
|
|---|
| 998 | if opt.startswith("--"):
|
|---|
| 999 | c_option._long_opts.remove(opt)
|
|---|
| 1000 | del self._long_opt[opt]
|
|---|
| 1001 | else:
|
|---|
| 1002 | c_option._short_opts.remove(opt)
|
|---|
| 1003 | del self._short_opt[opt]
|
|---|
| 1004 | if not (c_option._short_opts or c_option._long_opts):
|
|---|
| 1005 | c_option.container.option_list.remove(c_option)
|
|---|
| 1006 |
|
|---|
| 1007 | def add_option(self, *args, **kwargs):
|
|---|
| 1008 | """add_option(Option)
|
|---|
| 1009 | add_option(opt_str, ..., kwarg=val, ...)
|
|---|
| 1010 | """
|
|---|
| 1011 | if type(args[0]) in types.StringTypes:
|
|---|
| 1012 | option = self.option_class(*args, **kwargs)
|
|---|
| 1013 | elif len(args) == 1 and not kwargs:
|
|---|
| 1014 | option = args[0]
|
|---|
| 1015 | if not isinstance(option, Option):
|
|---|
| 1016 | raise TypeError, "not an Option instance: %r" % option
|
|---|
| 1017 | else:
|
|---|
| 1018 | raise TypeError, "invalid arguments"
|
|---|
| 1019 |
|
|---|
| 1020 | self._check_conflict(option)
|
|---|
| 1021 |
|
|---|
| 1022 | self.option_list.append(option)
|
|---|
| 1023 | option.container = self
|
|---|
| 1024 | for opt in option._short_opts:
|
|---|
| 1025 | self._short_opt[opt] = option
|
|---|
| 1026 | for opt in option._long_opts:
|
|---|
| 1027 | self._long_opt[opt] = option
|
|---|
| 1028 |
|
|---|
| 1029 | if option.dest is not None: # option has a dest, we need a default
|
|---|
| 1030 | if option.default is not NO_DEFAULT:
|
|---|
| 1031 | self.defaults[option.dest] = option.default
|
|---|
| 1032 | elif option.dest not in self.defaults:
|
|---|
| 1033 | self.defaults[option.dest] = None
|
|---|
| 1034 |
|
|---|
| 1035 | return option
|
|---|
| 1036 |
|
|---|
| 1037 | def add_options(self, option_list):
|
|---|
| 1038 | for option in option_list:
|
|---|
| 1039 | self.add_option(option)
|
|---|
| 1040 |
|
|---|
| 1041 | # -- Option query/removal methods ----------------------------------
|
|---|
| 1042 |
|
|---|
| 1043 | def get_option(self, opt_str):
|
|---|
| 1044 | return (self._short_opt.get(opt_str) or
|
|---|
| 1045 | self._long_opt.get(opt_str))
|
|---|
| 1046 |
|
|---|
| 1047 | def has_option(self, opt_str):
|
|---|
| 1048 | return (opt_str in self._short_opt or
|
|---|
| 1049 | opt_str in self._long_opt)
|
|---|
| 1050 |
|
|---|
| 1051 | def remove_option(self, opt_str):
|
|---|
| 1052 | option = self._short_opt.get(opt_str)
|
|---|
| 1053 | if option is None:
|
|---|
| 1054 | option = self._long_opt.get(opt_str)
|
|---|
| 1055 | if option is None:
|
|---|
| 1056 | raise ValueError("no such option %r" % opt_str)
|
|---|
| 1057 |
|
|---|
| 1058 | for opt in option._short_opts:
|
|---|
| 1059 | del self._short_opt[opt]
|
|---|
| 1060 | for opt in option._long_opts:
|
|---|
| 1061 | del self._long_opt[opt]
|
|---|
| 1062 | option.container.option_list.remove(option)
|
|---|
| 1063 |
|
|---|
| 1064 |
|
|---|
| 1065 | # -- Help-formatting methods ---------------------------------------
|
|---|
| 1066 |
|
|---|
| 1067 | def format_option_help(self, formatter):
|
|---|
| 1068 | if not self.option_list:
|
|---|
| 1069 | return ""
|
|---|
| 1070 | result = []
|
|---|
| 1071 | for option in self.option_list:
|
|---|
| 1072 | if not option.help is SUPPRESS_HELP:
|
|---|
| 1073 | result.append(formatter.format_option(option))
|
|---|
| 1074 | return "".join(result)
|
|---|
| 1075 |
|
|---|
| 1076 | def format_description(self, formatter):
|
|---|
| 1077 | return formatter.format_description(self.get_description())
|
|---|
| 1078 |
|
|---|
| 1079 | def format_help(self, formatter):
|
|---|
| 1080 | result = []
|
|---|
| 1081 | if self.description:
|
|---|
| 1082 | result.append(self.format_description(formatter))
|
|---|
| 1083 | if self.option_list:
|
|---|
| 1084 | result.append(self.format_option_help(formatter))
|
|---|
| 1085 | return "\n".join(result)
|
|---|
| 1086 |
|
|---|
| 1087 |
|
|---|
| 1088 | class OptionGroup (OptionContainer):
|
|---|
| 1089 |
|
|---|
| 1090 | def __init__(self, parser, title, description=None):
|
|---|
| 1091 | self.parser = parser
|
|---|
| 1092 | OptionContainer.__init__(
|
|---|
| 1093 | self, parser.option_class, parser.conflict_handler, description)
|
|---|
| 1094 | self.title = title
|
|---|
| 1095 |
|
|---|
| 1096 | def _create_option_list(self):
|
|---|
| 1097 | self.option_list = []
|
|---|
| 1098 | self._share_option_mappings(self.parser)
|
|---|
| 1099 |
|
|---|
| 1100 | def set_title(self, title):
|
|---|
| 1101 | self.title = title
|
|---|
| 1102 |
|
|---|
| 1103 | def destroy(self):
|
|---|
| 1104 | """see OptionParser.destroy()."""
|
|---|
| 1105 | OptionContainer.destroy(self)
|
|---|
| 1106 | del self.option_list
|
|---|
| 1107 |
|
|---|
| 1108 | # -- Help-formatting methods ---------------------------------------
|
|---|
| 1109 |
|
|---|
| 1110 | def format_help(self, formatter):
|
|---|
| 1111 | result = formatter.format_heading(self.title)
|
|---|
| 1112 | formatter.indent()
|
|---|
| 1113 | result += OptionContainer.format_help(self, formatter)
|
|---|
| 1114 | formatter.dedent()
|
|---|
| 1115 | return result
|
|---|
| 1116 |
|
|---|
| 1117 |
|
|---|
| 1118 | class OptionParser (OptionContainer):
|
|---|
| 1119 |
|
|---|
| 1120 | """
|
|---|
| 1121 | Class attributes:
|
|---|
| 1122 | standard_option_list : [Option]
|
|---|
| 1123 | list of standard options that will be accepted by all instances
|
|---|
| 1124 | of this parser class (intended to be overridden by subclasses).
|
|---|
| 1125 |
|
|---|
| 1126 | Instance attributes:
|
|---|
| 1127 | usage : string
|
|---|
| 1128 | a usage string for your program. Before it is displayed
|
|---|
| 1129 | to the user, "%prog" will be expanded to the name of
|
|---|
| 1130 | your program (self.prog or os.path.basename(sys.argv[0])).
|
|---|
| 1131 | prog : string
|
|---|
| 1132 | the name of the current program (to override
|
|---|
| 1133 | os.path.basename(sys.argv[0])).
|
|---|
| 1134 | epilog : string
|
|---|
| 1135 | paragraph of help text to print after option help
|
|---|
| 1136 |
|
|---|
| 1137 | option_groups : [OptionGroup]
|
|---|
| 1138 | list of option groups in this parser (option groups are
|
|---|
| 1139 | irrelevant for parsing the command-line, but very useful
|
|---|
| 1140 | for generating help)
|
|---|
| 1141 |
|
|---|
| 1142 | allow_interspersed_args : bool = true
|
|---|
| 1143 | if true, positional arguments may be interspersed with options.
|
|---|
| 1144 | Assuming -a and -b each take a single argument, the command-line
|
|---|
| 1145 | -ablah foo bar -bboo baz
|
|---|
| 1146 | will be interpreted the same as
|
|---|
| 1147 | -ablah -bboo -- foo bar baz
|
|---|
| 1148 | If this flag were false, that command line would be interpreted as
|
|---|
| 1149 | -ablah -- foo bar -bboo baz
|
|---|
| 1150 | -- ie. we stop processing options as soon as we see the first
|
|---|
| 1151 | non-option argument. (This is the tradition followed by
|
|---|
| 1152 | Python's getopt module, Perl's Getopt::Std, and other argument-
|
|---|
| 1153 | parsing libraries, but it is generally annoying to users.)
|
|---|
| 1154 |
|
|---|
| 1155 | process_default_values : bool = true
|
|---|
| 1156 | if true, option default values are processed similarly to option
|
|---|
| 1157 | values from the command line: that is, they are passed to the
|
|---|
| 1158 | type-checking function for the option's type (as long as the
|
|---|
| 1159 | default value is a string). (This really only matters if you
|
|---|
| 1160 | have defined custom types; see SF bug #955889.) Set it to false
|
|---|
| 1161 | to restore the behaviour of Optik 1.4.1 and earlier.
|
|---|
| 1162 |
|
|---|
| 1163 | rargs : [string]
|
|---|
| 1164 | the argument list currently being parsed. Only set when
|
|---|
| 1165 | parse_args() is active, and continually trimmed down as
|
|---|
| 1166 | we consume arguments. Mainly there for the benefit of
|
|---|
| 1167 | callback options.
|
|---|
| 1168 | largs : [string]
|
|---|
| 1169 | the list of leftover arguments that we have skipped while
|
|---|
| 1170 | parsing options. If allow_interspersed_args is false, this
|
|---|
| 1171 | list is always empty.
|
|---|
| 1172 | values : Values
|
|---|
| 1173 | the set of option values currently being accumulated. Only
|
|---|
| 1174 | set when parse_args() is active. Also mainly for callbacks.
|
|---|
| 1175 |
|
|---|
| 1176 | Because of the 'rargs', 'largs', and 'values' attributes,
|
|---|
| 1177 | OptionParser is not thread-safe. If, for some perverse reason, you
|
|---|
| 1178 | need to parse command-line arguments simultaneously in different
|
|---|
| 1179 | threads, use different OptionParser instances.
|
|---|
| 1180 |
|
|---|
| 1181 | """
|
|---|
| 1182 |
|
|---|
| 1183 | standard_option_list = []
|
|---|
| 1184 |
|
|---|
| 1185 | def __init__(self,
|
|---|
| 1186 | usage=None,
|
|---|
| 1187 | option_list=None,
|
|---|
| 1188 | option_class=Option,
|
|---|
| 1189 | version=None,
|
|---|
| 1190 | conflict_handler="error",
|
|---|
| 1191 | description=None,
|
|---|
| 1192 | formatter=None,
|
|---|
| 1193 | add_help_option=True,
|
|---|
| 1194 | prog=None,
|
|---|
| 1195 | epilog=None):
|
|---|
| 1196 | OptionContainer.__init__(
|
|---|
| 1197 | self, option_class, conflict_handler, description)
|
|---|
| 1198 | self.set_usage(usage)
|
|---|
| 1199 | self.prog = prog
|
|---|
| 1200 | self.version = version
|
|---|
| 1201 | self.allow_interspersed_args = True
|
|---|
| 1202 | self.process_default_values = True
|
|---|
| 1203 | if formatter is None:
|
|---|
| 1204 | formatter = IndentedHelpFormatter()
|
|---|
| 1205 | self.formatter = formatter
|
|---|
| 1206 | self.formatter.set_parser(self)
|
|---|
| 1207 | self.epilog = epilog
|
|---|
| 1208 |
|
|---|
| 1209 | # Populate the option list; initial sources are the
|
|---|
| 1210 | # standard_option_list class attribute, the 'option_list'
|
|---|
| 1211 | # argument, and (if applicable) the _add_version_option() and
|
|---|
| 1212 | # _add_help_option() methods.
|
|---|
| 1213 | self._populate_option_list(option_list,
|
|---|
| 1214 | add_help=add_help_option)
|
|---|
| 1215 |
|
|---|
| 1216 | self._init_parsing_state()
|
|---|
| 1217 |
|
|---|
| 1218 |
|
|---|
| 1219 | def destroy(self):
|
|---|
| 1220 | """
|
|---|
| 1221 | Declare that you are done with this OptionParser. This cleans up
|
|---|
| 1222 | reference cycles so the OptionParser (and all objects referenced by
|
|---|
| 1223 | it) can be garbage-collected promptly. After calling destroy(), the
|
|---|
| 1224 | OptionParser is unusable.
|
|---|
| 1225 | """
|
|---|
| 1226 | OptionContainer.destroy(self)
|
|---|
| 1227 | for group in self.option_groups:
|
|---|
| 1228 | group.destroy()
|
|---|
| 1229 | del self.option_list
|
|---|
| 1230 | del self.option_groups
|
|---|
| 1231 | del self.formatter
|
|---|
| 1232 |
|
|---|
| 1233 |
|
|---|
| 1234 | # -- Private methods -----------------------------------------------
|
|---|
| 1235 | # (used by our or OptionContainer's constructor)
|
|---|
| 1236 |
|
|---|
| 1237 | def _create_option_list(self):
|
|---|
| 1238 | self.option_list = []
|
|---|
| 1239 | self.option_groups = []
|
|---|
| 1240 | self._create_option_mappings()
|
|---|
| 1241 |
|
|---|
| 1242 | def _add_help_option(self):
|
|---|
| 1243 | self.add_option("-h", "--help",
|
|---|
| 1244 | action="help",
|
|---|
| 1245 | help=_("show this help message and exit"))
|
|---|
| 1246 |
|
|---|
| 1247 | def _add_version_option(self):
|
|---|
| 1248 | self.add_option("--version",
|
|---|
| 1249 | action="version",
|
|---|
| 1250 | help=_("show program's version number and exit"))
|
|---|
| 1251 |
|
|---|
| 1252 | def _populate_option_list(self, option_list, add_help=True):
|
|---|
| 1253 | if self.standard_option_list:
|
|---|
| 1254 | self.add_options(self.standard_option_list)
|
|---|
| 1255 | if option_list:
|
|---|
| 1256 | self.add_options(option_list)
|
|---|
| 1257 | if self.version:
|
|---|
| 1258 | self._add_version_option()
|
|---|
| 1259 | if add_help:
|
|---|
| 1260 | self._add_help_option()
|
|---|
| 1261 |
|
|---|
| 1262 | def _init_parsing_state(self):
|
|---|
| 1263 | # These are set in parse_args() for the convenience of callbacks.
|
|---|
| 1264 | self.rargs = None
|
|---|
| 1265 | self.largs = None
|
|---|
| 1266 | self.values = None
|
|---|
| 1267 |
|
|---|
| 1268 |
|
|---|
| 1269 | # -- Simple modifier methods ---------------------------------------
|
|---|
| 1270 |
|
|---|
| 1271 | def set_usage(self, usage):
|
|---|
| 1272 | if usage is None:
|
|---|
| 1273 | self.usage = _("%prog [options]")
|
|---|
| 1274 | elif usage is SUPPRESS_USAGE:
|
|---|
| 1275 | self.usage = None
|
|---|
| 1276 | # For backwards compatibility with Optik 1.3 and earlier.
|
|---|
| 1277 | elif usage.lower().startswith("usage: "):
|
|---|
| 1278 | self.usage = usage[7:]
|
|---|
| 1279 | else:
|
|---|
| 1280 | self.usage = usage
|
|---|
| 1281 |
|
|---|
| 1282 | def enable_interspersed_args(self):
|
|---|
| 1283 | """Set parsing to not stop on the first non-option, allowing
|
|---|
| 1284 | interspersing switches with command arguments. This is the
|
|---|
| 1285 | default behavior. See also disable_interspersed_args() and the
|
|---|
| 1286 | class documentation description of the attribute
|
|---|
| 1287 | allow_interspersed_args."""
|
|---|
| 1288 | self.allow_interspersed_args = True
|
|---|
| 1289 |
|
|---|
| 1290 | def disable_interspersed_args(self):
|
|---|
| 1291 | """Set parsing to stop on the first non-option. Use this if
|
|---|
| 1292 | you have a command processor which runs another command that
|
|---|
| 1293 | has options of its own and you want to make sure these options
|
|---|
| 1294 | don't get confused.
|
|---|
| 1295 | """
|
|---|
| 1296 | self.allow_interspersed_args = False
|
|---|
| 1297 |
|
|---|
| 1298 | def set_process_default_values(self, process):
|
|---|
| 1299 | self.process_default_values = process
|
|---|
| 1300 |
|
|---|
| 1301 | def set_default(self, dest, value):
|
|---|
| 1302 | self.defaults[dest] = value
|
|---|
| 1303 |
|
|---|
| 1304 | def set_defaults(self, **kwargs):
|
|---|
| 1305 | self.defaults.update(kwargs)
|
|---|
| 1306 |
|
|---|
| 1307 | def _get_all_options(self):
|
|---|
| 1308 | options = self.option_list[:]
|
|---|
| 1309 | for group in self.option_groups:
|
|---|
| 1310 | options.extend(group.option_list)
|
|---|
| 1311 | return options
|
|---|
| 1312 |
|
|---|
| 1313 | def get_default_values(self):
|
|---|
| 1314 | if not self.process_default_values:
|
|---|
| 1315 | # Old, pre-Optik 1.5 behaviour.
|
|---|
| 1316 | return Values(self.defaults)
|
|---|
| 1317 |
|
|---|
| 1318 | defaults = self.defaults.copy()
|
|---|
| 1319 | for option in self._get_all_options():
|
|---|
| 1320 | default = defaults.get(option.dest)
|
|---|
| 1321 | if isbasestring(default):
|
|---|
| 1322 | opt_str = option.get_opt_string()
|
|---|
| 1323 | defaults[option.dest] = option.check_value(opt_str, default)
|
|---|
| 1324 |
|
|---|
| 1325 | return Values(defaults)
|
|---|
| 1326 |
|
|---|
| 1327 |
|
|---|
| 1328 | # -- OptionGroup methods -------------------------------------------
|
|---|
| 1329 |
|
|---|
| 1330 | def add_option_group(self, *args, **kwargs):
|
|---|
| 1331 | # XXX lots of overlap with OptionContainer.add_option()
|
|---|
| 1332 | if type(args[0]) is types.StringType:
|
|---|
| 1333 | group = OptionGroup(self, *args, **kwargs)
|
|---|
| 1334 | elif len(args) == 1 and not kwargs:
|
|---|
| 1335 | group = args[0]
|
|---|
| 1336 | if not isinstance(group, OptionGroup):
|
|---|
| 1337 | raise TypeError, "not an OptionGroup instance: %r" % group
|
|---|
| 1338 | if group.parser is not self:
|
|---|
| 1339 | raise ValueError, "invalid OptionGroup (wrong parser)"
|
|---|
| 1340 | else:
|
|---|
| 1341 | raise TypeError, "invalid arguments"
|
|---|
| 1342 |
|
|---|
| 1343 | self.option_groups.append(group)
|
|---|
| 1344 | return group
|
|---|
| 1345 |
|
|---|
| 1346 | def get_option_group(self, opt_str):
|
|---|
| 1347 | option = (self._short_opt.get(opt_str) or
|
|---|
| 1348 | self._long_opt.get(opt_str))
|
|---|
| 1349 | if option and option.container is not self:
|
|---|
| 1350 | return option.container
|
|---|
| 1351 | return None
|
|---|
| 1352 |
|
|---|
| 1353 |
|
|---|
| 1354 | # -- Option-parsing methods ----------------------------------------
|
|---|
| 1355 |
|
|---|
| 1356 | def _get_args(self, args):
|
|---|
| 1357 | if args is None:
|
|---|
| 1358 | return sys.argv[1:]
|
|---|
| 1359 | else:
|
|---|
| 1360 | return args[:] # don't modify caller's list
|
|---|
| 1361 |
|
|---|
| 1362 | def parse_args(self, args=None, values=None):
|
|---|
| 1363 | """
|
|---|
| 1364 | parse_args(args : [string] = sys.argv[1:],
|
|---|
| 1365 | values : Values = None)
|
|---|
| 1366 | -> (values : Values, args : [string])
|
|---|
| 1367 |
|
|---|
| 1368 | Parse the command-line options found in 'args' (default:
|
|---|
| 1369 | sys.argv[1:]). Any errors result in a call to 'error()', which
|
|---|
| 1370 | by default prints the usage message to stderr and calls
|
|---|
| 1371 | sys.exit() with an error message. On success returns a pair
|
|---|
| 1372 | (values, args) where 'values' is an Values instance (with all
|
|---|
| 1373 | your option values) and 'args' is the list of arguments left
|
|---|
| 1374 | over after parsing options.
|
|---|
| 1375 | """
|
|---|
| 1376 | rargs = self._get_args(args)
|
|---|
| 1377 | if values is None:
|
|---|
| 1378 | values = self.get_default_values()
|
|---|
| 1379 |
|
|---|
| 1380 | # Store the halves of the argument list as attributes for the
|
|---|
| 1381 | # convenience of callbacks:
|
|---|
| 1382 | # rargs
|
|---|
| 1383 | # the rest of the command-line (the "r" stands for
|
|---|
| 1384 | # "remaining" or "right-hand")
|
|---|
| 1385 | # largs
|
|---|
| 1386 | # the leftover arguments -- ie. what's left after removing
|
|---|
| 1387 | # options and their arguments (the "l" stands for "leftover"
|
|---|
| 1388 | # or "left-hand")
|
|---|
| 1389 | self.rargs = rargs
|
|---|
| 1390 | self.largs = largs = []
|
|---|
| 1391 | self.values = values
|
|---|
| 1392 |
|
|---|
| 1393 | try:
|
|---|
| 1394 | stop = self._process_args(largs, rargs, values)
|
|---|
| 1395 | except (BadOptionError, OptionValueError), err:
|
|---|
| 1396 | self.error(str(err))
|
|---|
| 1397 |
|
|---|
| 1398 | args = largs + rargs
|
|---|
| 1399 | return self.check_values(values, args)
|
|---|
| 1400 |
|
|---|
| 1401 | def check_values(self, values, args):
|
|---|
| 1402 | """
|
|---|
| 1403 | check_values(values : Values, args : [string])
|
|---|
| 1404 | -> (values : Values, args : [string])
|
|---|
| 1405 |
|
|---|
| 1406 | Check that the supplied option values and leftover arguments are
|
|---|
| 1407 | valid. Returns the option values and leftover arguments
|
|---|
| 1408 | (possibly adjusted, possibly completely new -- whatever you
|
|---|
| 1409 | like). Default implementation just returns the passed-in
|
|---|
| 1410 | values; subclasses may override as desired.
|
|---|
| 1411 | """
|
|---|
| 1412 | return (values, args)
|
|---|
| 1413 |
|
|---|
| 1414 | def _process_args(self, largs, rargs, values):
|
|---|
| 1415 | """_process_args(largs : [string],
|
|---|
| 1416 | rargs : [string],
|
|---|
| 1417 | values : Values)
|
|---|
| 1418 |
|
|---|
| 1419 | Process command-line arguments and populate 'values', consuming
|
|---|
| 1420 | options and arguments from 'rargs'. If 'allow_interspersed_args' is
|
|---|
| 1421 | false, stop at the first non-option argument. If true, accumulate any
|
|---|
| 1422 | interspersed non-option arguments in 'largs'.
|
|---|
| 1423 | """
|
|---|
| 1424 | while rargs:
|
|---|
| 1425 | arg = rargs[0]
|
|---|
| 1426 | # We handle bare "--" explicitly, and bare "-" is handled by the
|
|---|
| 1427 | # standard arg handler since the short arg case ensures that the
|
|---|
| 1428 | # len of the opt string is greater than 1.
|
|---|
| 1429 | if arg == "--":
|
|---|
| 1430 | del rargs[0]
|
|---|
| 1431 | return
|
|---|
| 1432 | elif arg[0:2] == "--":
|
|---|
| 1433 | # process a single long option (possibly with value(s))
|
|---|
| 1434 | self._process_long_opt(rargs, values)
|
|---|
| 1435 | elif arg[:1] == "-" and len(arg) > 1:
|
|---|
| 1436 | # process a cluster of short options (possibly with
|
|---|
| 1437 | # value(s) for the last one only)
|
|---|
| 1438 | self._process_short_opts(rargs, values)
|
|---|
| 1439 | elif self.allow_interspersed_args:
|
|---|
| 1440 | largs.append(arg)
|
|---|
| 1441 | del rargs[0]
|
|---|
| 1442 | else:
|
|---|
| 1443 | return # stop now, leave this arg in rargs
|
|---|
| 1444 |
|
|---|
| 1445 | # Say this is the original argument list:
|
|---|
| 1446 | # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)]
|
|---|
| 1447 | # ^
|
|---|
| 1448 | # (we are about to process arg(i)).
|
|---|
| 1449 | #
|
|---|
| 1450 | # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of
|
|---|
| 1451 | # [arg0, ..., arg(i-1)] (any options and their arguments will have
|
|---|
| 1452 | # been removed from largs).
|
|---|
| 1453 | #
|
|---|
| 1454 | # The while loop will usually consume 1 or more arguments per pass.
|
|---|
| 1455 | # If it consumes 1 (eg. arg is an option that takes no arguments),
|
|---|
| 1456 | # then after _process_arg() is done the situation is:
|
|---|
| 1457 | #
|
|---|
| 1458 | # largs = subset of [arg0, ..., arg(i)]
|
|---|
| 1459 | # rargs = [arg(i+1), ..., arg(N-1)]
|
|---|
| 1460 | #
|
|---|
| 1461 | # If allow_interspersed_args is false, largs will always be
|
|---|
| 1462 | # *empty* -- still a subset of [arg0, ..., arg(i-1)], but
|
|---|
| 1463 | # not a very interesting subset!
|
|---|
| 1464 |
|
|---|
| 1465 | def _match_long_opt(self, opt):
|
|---|
| 1466 | """_match_long_opt(opt : string) -> string
|
|---|
| 1467 |
|
|---|
| 1468 | Determine which long option string 'opt' matches, ie. which one
|
|---|
| 1469 | it is an unambiguous abbrevation for. Raises BadOptionError if
|
|---|
| 1470 | 'opt' doesn't unambiguously match any long option string.
|
|---|
| 1471 | """
|
|---|
| 1472 | return _match_abbrev(opt, self._long_opt)
|
|---|
| 1473 |
|
|---|
| 1474 | def _process_long_opt(self, rargs, values):
|
|---|
| 1475 | arg = rargs.pop(0)
|
|---|
| 1476 |
|
|---|
| 1477 | # Value explicitly attached to arg? Pretend it's the next
|
|---|
| 1478 | # argument.
|
|---|
| 1479 | if "=" in arg:
|
|---|
| 1480 | (opt, next_arg) = arg.split("=", 1)
|
|---|
| 1481 | rargs.insert(0, next_arg)
|
|---|
| 1482 | had_explicit_value = True
|
|---|
| 1483 | else:
|
|---|
| 1484 | opt = arg
|
|---|
| 1485 | had_explicit_value = False
|
|---|
| 1486 |
|
|---|
| 1487 | opt = self._match_long_opt(opt)
|
|---|
| 1488 | option = self._long_opt[opt]
|
|---|
| 1489 | if option.takes_value():
|
|---|
| 1490 | nargs = option.nargs
|
|---|
| 1491 | if len(rargs) < nargs:
|
|---|
| 1492 | if nargs == 1:
|
|---|
| 1493 | self.error(_("%s option requires an argument") % opt)
|
|---|
| 1494 | else:
|
|---|
| 1495 | self.error(_("%s option requires %d arguments")
|
|---|
| 1496 | % (opt, nargs))
|
|---|
| 1497 | elif nargs == 1:
|
|---|
| 1498 | value = rargs.pop(0)
|
|---|
| 1499 | else:
|
|---|
| 1500 | value = tuple(rargs[0:nargs])
|
|---|
| 1501 | del rargs[0:nargs]
|
|---|
| 1502 |
|
|---|
| 1503 | elif had_explicit_value:
|
|---|
| 1504 | self.error(_("%s option does not take a value") % opt)
|
|---|
| 1505 |
|
|---|
| 1506 | else:
|
|---|
| 1507 | value = None
|
|---|
| 1508 |
|
|---|
| 1509 | option.process(opt, value, values, self)
|
|---|
| 1510 |
|
|---|
| 1511 | def _process_short_opts(self, rargs, values):
|
|---|
| 1512 | arg = rargs.pop(0)
|
|---|
| 1513 | stop = False
|
|---|
| 1514 | i = 1
|
|---|
| 1515 | for ch in arg[1:]:
|
|---|
| 1516 | opt = "-" + ch
|
|---|
| 1517 | option = self._short_opt.get(opt)
|
|---|
| 1518 | i += 1 # we have consumed a character
|
|---|
| 1519 |
|
|---|
| 1520 | if not option:
|
|---|
| 1521 | raise BadOptionError(opt)
|
|---|
| 1522 | if option.takes_value():
|
|---|
| 1523 | # Any characters left in arg? Pretend they're the
|
|---|
| 1524 | # next arg, and stop consuming characters of arg.
|
|---|
| 1525 | if i < len(arg):
|
|---|
| 1526 | rargs.insert(0, arg[i:])
|
|---|
| 1527 | stop = True
|
|---|
| 1528 |
|
|---|
| 1529 | nargs = option.nargs
|
|---|
| 1530 | if len(rargs) < nargs:
|
|---|
| 1531 | if nargs == 1:
|
|---|
| 1532 | self.error(_("%s option requires an argument") % opt)
|
|---|
| 1533 | else:
|
|---|
| 1534 | self.error(_("%s option requires %d arguments")
|
|---|
| 1535 | % (opt, nargs))
|
|---|
| 1536 | elif nargs == 1:
|
|---|
| 1537 | value = rargs.pop(0)
|
|---|
| 1538 | else:
|
|---|
| 1539 | value = tuple(rargs[0:nargs])
|
|---|
| 1540 | del rargs[0:nargs]
|
|---|
| 1541 |
|
|---|
| 1542 | else: # option doesn't take a value
|
|---|
| 1543 | value = None
|
|---|
| 1544 |
|
|---|
| 1545 | option.process(opt, value, values, self)
|
|---|
| 1546 |
|
|---|
| 1547 | if stop:
|
|---|
| 1548 | break
|
|---|
| 1549 |
|
|---|
| 1550 |
|
|---|
| 1551 | # -- Feedback methods ----------------------------------------------
|
|---|
| 1552 |
|
|---|
| 1553 | def get_prog_name(self):
|
|---|
| 1554 | if self.prog is None:
|
|---|
| 1555 | return os.path.basename(sys.argv[0])
|
|---|
| 1556 | else:
|
|---|
| 1557 | return self.prog
|
|---|
| 1558 |
|
|---|
| 1559 | def expand_prog_name(self, s):
|
|---|
| 1560 | return s.replace("%prog", self.get_prog_name())
|
|---|
| 1561 |
|
|---|
| 1562 | def get_description(self):
|
|---|
| 1563 | return self.expand_prog_name(self.description)
|
|---|
| 1564 |
|
|---|
| 1565 | def exit(self, status=0, msg=None):
|
|---|
| 1566 | if msg:
|
|---|
| 1567 | sys.stderr.write(msg)
|
|---|
| 1568 | sys.exit(status)
|
|---|
| 1569 |
|
|---|
| 1570 | def error(self, msg):
|
|---|
| 1571 | """error(msg : string)
|
|---|
| 1572 |
|
|---|
| 1573 | Print a usage message incorporating 'msg' to stderr and exit.
|
|---|
| 1574 | If you override this in a subclass, it should not return -- it
|
|---|
| 1575 | should either exit or raise an exception.
|
|---|
| 1576 | """
|
|---|
| 1577 | self.print_usage(sys.stderr)
|
|---|
| 1578 | self.exit(2, "%s: error: %s\n" % (self.get_prog_name(), msg))
|
|---|
| 1579 |
|
|---|
| 1580 | def get_usage(self):
|
|---|
| 1581 | if self.usage:
|
|---|
| 1582 | return self.formatter.format_usage(
|
|---|
| 1583 | self.expand_prog_name(self.usage))
|
|---|
| 1584 | else:
|
|---|
| 1585 | return ""
|
|---|
| 1586 |
|
|---|
| 1587 | def print_usage(self, file=None):
|
|---|
| 1588 | """print_usage(file : file = stdout)
|
|---|
| 1589 |
|
|---|
| 1590 | Print the usage message for the current program (self.usage) to
|
|---|
| 1591 | 'file' (default stdout). Any occurrence of the string "%prog" in
|
|---|
| 1592 | self.usage is replaced with the name of the current program
|
|---|
| 1593 | (basename of sys.argv[0]). Does nothing if self.usage is empty
|
|---|
| 1594 | or not defined.
|
|---|
| 1595 | """
|
|---|
| 1596 | if self.usage:
|
|---|
| 1597 | print >>file, self.get_usage()
|
|---|
| 1598 |
|
|---|
| 1599 | def get_version(self):
|
|---|
| 1600 | if self.version:
|
|---|
| 1601 | return self.expand_prog_name(self.version)
|
|---|
| 1602 | else:
|
|---|
| 1603 | return ""
|
|---|
| 1604 |
|
|---|
| 1605 | def print_version(self, file=None):
|
|---|
| 1606 | """print_version(file : file = stdout)
|
|---|
| 1607 |
|
|---|
| 1608 | Print the version message for this program (self.version) to
|
|---|
| 1609 | 'file' (default stdout). As with print_usage(), any occurrence
|
|---|
| 1610 | of "%prog" in self.version is replaced by the current program's
|
|---|
| 1611 | name. Does nothing if self.version is empty or undefined.
|
|---|
| 1612 | """
|
|---|
| 1613 | if self.version:
|
|---|
| 1614 | print >>file, self.get_version()
|
|---|
| 1615 |
|
|---|
| 1616 | def format_option_help(self, formatter=None):
|
|---|
| 1617 | if formatter is None:
|
|---|
| 1618 | formatter = self.formatter
|
|---|
| 1619 | formatter.store_option_strings(self)
|
|---|
| 1620 | result = []
|
|---|
| 1621 | result.append(formatter.format_heading(_("Options")))
|
|---|
| 1622 | formatter.indent()
|
|---|
| 1623 | if self.option_list:
|
|---|
| 1624 | result.append(OptionContainer.format_option_help(self, formatter))
|
|---|
| 1625 | result.append("\n")
|
|---|
| 1626 | for group in self.option_groups:
|
|---|
| 1627 | result.append(group.format_help(formatter))
|
|---|
| 1628 | result.append("\n")
|
|---|
| 1629 | formatter.dedent()
|
|---|
| 1630 | # Drop the last "\n", or the header if no options or option groups:
|
|---|
| 1631 | return "".join(result[:-1])
|
|---|
| 1632 |
|
|---|
| 1633 | def format_epilog(self, formatter):
|
|---|
| 1634 | return formatter.format_epilog(self.epilog)
|
|---|
| 1635 |
|
|---|
| 1636 | def format_help(self, formatter=None):
|
|---|
| 1637 | if formatter is None:
|
|---|
| 1638 | formatter = self.formatter
|
|---|
| 1639 | result = []
|
|---|
| 1640 | if self.usage:
|
|---|
| 1641 | result.append(self.get_usage() + "\n")
|
|---|
| 1642 | if self.description:
|
|---|
| 1643 | result.append(self.format_description(formatter) + "\n")
|
|---|
| 1644 | result.append(self.format_option_help(formatter))
|
|---|
| 1645 | result.append(self.format_epilog(formatter))
|
|---|
| 1646 | return "".join(result)
|
|---|
| 1647 |
|
|---|
| 1648 | # used by test suite
|
|---|
| 1649 | def _get_encoding(self, file):
|
|---|
| 1650 | encoding = getattr(file, "encoding", None)
|
|---|
| 1651 | if not encoding:
|
|---|
| 1652 | encoding = sys.getdefaultencoding()
|
|---|
| 1653 | return encoding
|
|---|
| 1654 |
|
|---|
| 1655 | def print_help(self, file=None):
|
|---|
| 1656 | """print_help(file : file = stdout)
|
|---|
| 1657 |
|
|---|
| 1658 | Print an extended help message, listing all options and any
|
|---|
| 1659 | help text provided with them, to 'file' (default stdout).
|
|---|
| 1660 | """
|
|---|
| 1661 | if file is None:
|
|---|
| 1662 | file = sys.stdout
|
|---|
| 1663 | encoding = self._get_encoding(file)
|
|---|
| 1664 | file.write(self.format_help().encode(encoding, "replace"))
|
|---|
| 1665 |
|
|---|
| 1666 | # class OptionParser
|
|---|
| 1667 |
|
|---|
| 1668 |
|
|---|
| 1669 | def _match_abbrev(s, wordmap):
|
|---|
| 1670 | """_match_abbrev(s : string, wordmap : {string : Option}) -> string
|
|---|
| 1671 |
|
|---|
| 1672 | Return the string key in 'wordmap' for which 's' is an unambiguous
|
|---|
| 1673 | abbreviation. If 's' is found to be ambiguous or doesn't match any of
|
|---|
| 1674 | 'words', raise BadOptionError.
|
|---|
| 1675 | """
|
|---|
| 1676 | # Is there an exact match?
|
|---|
| 1677 | if s in wordmap:
|
|---|
| 1678 | return s
|
|---|
| 1679 | else:
|
|---|
| 1680 | # Isolate all words with s as a prefix.
|
|---|
| 1681 | possibilities = [word for word in wordmap.keys()
|
|---|
| 1682 | if word.startswith(s)]
|
|---|
| 1683 | # No exact match, so there had better be just one possibility.
|
|---|
| 1684 | if len(possibilities) == 1:
|
|---|
| 1685 | return possibilities[0]
|
|---|
| 1686 | elif not possibilities:
|
|---|
| 1687 | raise BadOptionError(s)
|
|---|
| 1688 | else:
|
|---|
| 1689 | # More than one possible completion: ambiguous prefix.
|
|---|
| 1690 | possibilities.sort()
|
|---|
| 1691 | raise AmbiguousOptionError(s, possibilities)
|
|---|
| 1692 |
|
|---|
| 1693 |
|
|---|
| 1694 | # Some day, there might be many Option classes. As of Optik 1.3, the
|
|---|
| 1695 | # preferred way to instantiate Options is indirectly, via make_option(),
|
|---|
| 1696 | # which will become a factory function when there are many Option
|
|---|
| 1697 | # classes.
|
|---|
| 1698 | make_option = Option
|
|---|
