AppPkg/Applications/Python/Python-2.7.10/Lib/optparse.py

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