Lib/optparse.py

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