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