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         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 ValueError("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]) is types.StringType:
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