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.3"
  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 527 2006-07-23 15:21:30Z greg
  79 #   Id: option.py 522 2006-06-11 16:22:03Z gward
  80 #   Id: help.py 527 2006-07-23 15:21:30Z greg
  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             attrs = attrs.keys()
 615             attrs.sort()
 616             raise OptionError(
 617                 "invalid keyword arguments: %s" % ", ".join(attrs),
 618                 self)
 619
 620
 621     # -- Constructor validation methods --------------------------------
 622
 623     def _check_action(self):
 624         if self.action is None:
 625             self.action = "store"
 626         elif self.action not in self.ACTIONS:
 627             raise OptionError("invalid action: %r" % self.action, self)
 628
 629     def _check_type(self):
 630         if self.type is None:
 631             if self.action in self.ALWAYS_TYPED_ACTIONS:
 632                 if self.choices is not None:
 633                     # The "choices" attribute implies "choice" type.
 634                     self.type = "choice"
 635                 else:
 636                     # No type given?  "string" is the most sensible default.
 637                     self.type = "string"
 638         else:
 639             # Allow type objects or builtin type conversion functions
 640             # (int, str, etc.) as an alternative to their names.  (The
 641             # complicated check of __builtin__ is only necessary for
 642             # Python 2.1 and earlier, and is short-circuited by the
 643             # first check on modern Pythons.)
 644             import __builtin__
 645             if ( type(self.type) is types.TypeType or
 646                  (hasattr(self.type, "__name__") and
 647                   getattr(__builtin__, self.type.__name__, None) is self.type) ):
 648                 self.type = self.type.__name__
 649
 650             if self.type == "str":
 651                 self.type = "string"
 652
 653             if self.type not in self.TYPES:
 654                 raise OptionError("invalid option type: %r" % self.type, self)
 655             if self.action not in self.TYPED_ACTIONS:
 656                 raise OptionError(
 657                     "must not supply a type for action %r" % self.action, self)
 658
 659     def _check_choice(self):
 660         if self.type == "choice":
 661             if self.choices is None:
 662                 raise OptionError(
 663                     "must supply a list of choices for type 'choice'", self)
 664             elif type(self.choices) not in (types.TupleType, types.ListType):
 665                 raise OptionError(
 666                     "choices must be a list of strings ('%s' supplied)"
 667                     % str(type(self.choices)).split("'")[1], self)
 668         elif self.choices is not None:
 669             raise OptionError(
 670                 "must not supply choices for type %r" % self.type, self)
 671
 672     def _check_dest(self):
 673         # No destination given, and we need one for this action.  The
 674         # self.type check is for callbacks that take a value.
 675         takes_value = (self.action in self.STORE_ACTIONS or
 676                        self.type is not None)
 677         if self.dest is None and takes_value:
 678
 679             # Glean a destination from the first long option string,
 680             # or from the first short option string if no long options.
 681             if self._long_opts:
 682                 # eg. "--foo-bar" -> "foo_bar"
 683                 self.dest = self._long_opts[0][2:].replace('-', '_')
 684             else:
 685                 self.dest = self._short_opts[0][1]
 686
 687     def _check_const(self):
 688         if self.action not in self.CONST_ACTIONS and self.const is not None:
 689             raise OptionError(
 690                 "'const' must not be supplied for action %r" % self.action,
 691                 self)
 692
 693     def _check_nargs(self):
 694         if self.action in self.TYPED_ACTIONS:
 695             if self.nargs is None:
 696                 self.nargs = 1
 697         elif self.nargs is not None:
 698             raise OptionError(
 699                 "'nargs' must not be supplied for action %r" % self.action,
 700                 self)
 701
 702     def _check_callback(self):
 703         if self.action == "callback":
 704             if not callable(self.callback):
 705                 raise OptionError(
 706                     "callback not callable: %r" % self.callback, self)
 707             if (self.callback_args is not None and
 708                 type(self.callback_args) is not types.TupleType):
 709                 raise OptionError(
 710                     "callback_args, if supplied, must be a tuple: not %r"
 711                     % self.callback_args, self)
 712             if (self.callback_kwargs is not None and
 713                 type(self.callback_kwargs) is not types.DictType):
 714                 raise OptionError(
 715                     "callback_kwargs, if supplied, must be a dict: not %r"
 716                     % self.callback_kwargs, self)
 717         else:
 718             if self.callback is not None:
 719                 raise OptionError(
 720                     "callback supplied (%r) for non-callback option"
 721                     % self.callback, self)
 722             if self.callback_args is not None:
 723                 raise OptionError(
 724                     "callback_args supplied for non-callback option", self)
 725             if self.callback_kwargs is not None:
 726                 raise OptionError(
 727                     "callback_kwargs supplied for non-callback option", self)
 728
 729
 730     CHECK_METHODS = [_check_action,
 731                      _check_type,
 732                      _check_choice,
 733                      _check_dest,
 734                      _check_const,
 735                      _check_nargs,
 736                      _check_callback]
 737
 738
 739     # -- Miscellaneous methods -----------------------------------------
 740
 741     def __str__(self):
 742         return "/".join(self._short_opts + self._long_opts)
 743
 744     __repr__ = _repr
 745
 746     def takes_value(self):
 747         return self.type is not None
 748
 749     def get_opt_string(self):
 750         if self._long_opts:
 751             return self._long_opts[0]
 752         else:
 753             return self._short_opts[0]
 754
 755
 756     # -- Processing methods --------------------------------------------
 757
 758     def check_value(self, opt, value):
 759         checker = self.TYPE_CHECKER.get(self.type)
 760         if checker is None:
 761             return value
 762         else:
 763             return checker(self, opt, value)
 764
 765     def convert_value(self, opt, value):
 766         if value is not None:
 767             if self.nargs == 1:
 768                 return self.check_value(opt, value)
 769             else:
 770                 return tuple([self.check_value(opt, v) for v in value])
 771
 772     def process(self, opt, value, values, parser):
 773
 774         # First, convert the value(s) to the right type.  Howl if any
 775         # value(s) are bogus.
 776         value = self.convert_value(opt, value)
 777
 778         # And then take whatever action is expected of us.
 779         # This is a separate method to make life easier for
 780         # subclasses to add new actions.
 781         return self.take_action(
 782             self.action, self.dest, opt, value, values, parser)
 783
 784     def take_action(self, action, dest, opt, value, values, parser):
 785         if action == "store":
 786             setattr(values, dest, value)
 787         elif action == "store_const":
 788             setattr(values, dest, self.const)
 789         elif action == "store_true":
 790             setattr(values, dest, True)
 791         elif action == "store_false":
 792             setattr(values, dest, False)
 793         elif action == "append":
 794             values.ensure_value(dest, []).append(value)
 795         elif action == "append_const":
 796             values.ensure_value(dest, []).append(self.const)
 797         elif action == "count":
 798             setattr(values, dest, values.ensure_value(dest, 0) + 1)
 799         elif action == "callback":
 800             args = self.callback_args or ()
 801             kwargs = self.callback_kwargs or {}
 802             self.callback(self, opt, value, parser, *args, **kwargs)
 803         elif action == "help":
 804             parser.print_help()
 805             parser.exit()
 806         elif action == "version":
 807             parser.print_version()
 808             parser.exit()
 809         else:
 810             raise RuntimeError, "unknown action %r" % self.action
 811
 812         return 1
 813
 814 # class Option
 815
 816
 817 SUPPRESS_HELP = "SUPPRESS"+"HELP"
 818 SUPPRESS_USAGE = "SUPPRESS"+"USAGE"
 819
 820 # For compatibility with Python 2.2
 821 try:
 822     True, False
 823 except NameError:
 824     (True, False) = (1, 0)
 825
 826 try:
 827     basestring
 828 except NameError:
 829     def isbasestring(x):
 830         return isinstance(x, (types.StringType, types.UnicodeType))
 831 else:
 832     def isbasestring(x):
 833         return isinstance(x, basestring)
 834
 835 class Values:
 836
 837     def __init__(self, defaults=None):
 838         if defaults:
 839             for (attr, val) in defaults.items():
 840                 setattr(self, attr, val)
 841
 842     def __str__(self):
 843         return str(self.__dict__)
 844
 845     __repr__ = _repr
 846
 847     def __cmp__(self, other):
 848         if isinstance(other, Values):
 849             return cmp(self.__dict__, other.__dict__)
 850         elif isinstance(other, types.DictType):
 851             return cmp(self.__dict__, other)
 852         else:
 853             return -1
 854
 855     def _update_careful(self, dict):
 856         """
 857         Update the option values from an arbitrary dictionary, but only
 858         use keys from dict that already have a corresponding attribute
 859         in self.  Any keys in dict without a corresponding attribute
 860         are silently ignored.
 861         """
 862         for attr in dir(self):
 863             if dict.has_key(attr):
 864                 dval = dict[attr]
 865                 if dval is not None:
 866                     setattr(self, attr, dval)
 867
 868     def _update_loose(self, dict):
 869         """
 870         Update the option values from an arbitrary dictionary,
 871         using all keys from the dictionary regardless of whether
 872         they have a corresponding attribute in self or not.
 873         """
 874         self.__dict__.update(dict)
 875
 876     def _update(self, dict, mode):
 877         if mode == "careful":
 878             self._update_careful(dict)
 879         elif mode == "loose":
 880             self._update_loose(dict)
 881         else:
 882             raise ValueError, "invalid update mode: %r" % mode
 883
 884     def read_module(self, modname, mode="careful"):
 885         __import__(modname)
 886         mod = sys.modules[modname]
 887         self._update(vars(mod), mode)
 888
 889     def read_file(self, filename, mode="careful"):
 890         vars = {}
 891         execfile(filename, vars)
 892         self._update(vars, mode)
 893
 894     def ensure_value(self, attr, value):
 895         if not hasattr(self, attr) or getattr(self, attr) is None:
 896             setattr(self, attr, value)
 897         return getattr(self, attr)
 898
 899
 900 class OptionContainer:
 901
 902     """
 903     Abstract base class.
 904
 905     Class attributes:
 906       standard_option_list : [Option]
 907         list of standard options that will be accepted by all instances
 908         of this parser class (intended to be overridden by subclasses).
 909
 910     Instance attributes:
 911       option_list : [Option]
 912         the list of Option objects contained by this OptionContainer
 913       _short_opt : { string : Option }
 914         dictionary mapping short option strings, eg. "-f" or "-X",
 915         to the Option instances that implement them.  If an Option
 916         has multiple short option strings, it will appears in this
 917         dictionary multiple times. [1]
 918       _long_opt : { string : Option }
 919         dictionary mapping long option strings, eg. "--file" or
 920         "--exclude", to the Option instances that implement them.
 921         Again, a given Option can occur multiple times in this
 922         dictionary. [1]
 923       defaults : { string : any }
 924         dictionary mapping option destination names to default
 925         values for each destination [1]
 926
 927     [1] These mappings are common to (shared by) all components of the
 928         controlling OptionParser, where they are initially created.
 929
 930     """
 931
 932     def __init__(self, option_class, conflict_handler, description):
 933         # Initialize the option list and related data structures.
 934         # This method must be provided by subclasses, and it must
 935         # initialize at least the following instance attributes:
 936         # option_list, _short_opt, _long_opt, defaults.
 937         self._create_option_list()
 938
 939         self.option_class = option_class
 940         self.set_conflict_handler(conflict_handler)
 941         self.set_description(description)
 942
 943     def _create_option_mappings(self):
 944         # For use by OptionParser constructor -- create the master
 945         # option mappings used by this OptionParser and all
 946         # OptionGroups that it owns.
 947         self._short_opt = {}            # single letter -> Option instance
 948         self._long_opt = {}             # long option -> Option instance
 949         self.defaults = {}              # maps option dest -> default value
 950
 951
 952     def _share_option_mappings(self, parser):
 953         # For use by OptionGroup constructor -- use shared option
 954         # mappings from the OptionParser that owns this OptionGroup.
 955         self._short_opt = parser._short_opt
 956         self._long_opt = parser._long_opt
 957         self.defaults = parser.defaults
 958
 959     def set_conflict_handler(self, handler):
 960         if handler not in ("error", "resolve"):
 961             raise ValueError, "invalid conflict_resolution value %r" % handler
 962         self.conflict_handler = handler
 963
 964     def set_description(self, description):
 965         self.description = description
 966
 967     def get_description(self):
 968         return self.description
 969
 970
 971     def destroy(self):
 972         """see OptionParser.destroy()."""
 973         del self._short_opt
 974         del self._long_opt
 975         del self.defaults
 976
 977
 978     # -- Option-adding methods -----------------------------------------
 979
 980     def _check_conflict(self, option):
 981         conflict_opts = []
 982         for opt in option._short_opts:
 983             if self._short_opt.has_key(opt):
 984                 conflict_opts.append((opt, self._short_opt[opt]))
 985         for opt in option._long_opts:
 986             if self._long_opt.has_key(opt):
 987                 conflict_opts.append((opt, self._long_opt[opt]))
 988
 989         if conflict_opts:
 990             handler = self.conflict_handler
 991             if handler == "error":
 992                 raise OptionConflictError(
 993                     "conflicting option string(s): %s"
 994                     % ", ".join([co[0] for co in conflict_opts]),
 995                     option)
 996             elif handler == "resolve":
 997                 for (opt, c_option) in conflict_opts:
 998                     if opt.startswith("--"):
 999                         c_option._long_opts.remove(opt)
1000                         del self._long_opt[opt]
1001                     else:
1002                         c_option._short_opts.remove(opt)
1003                         del self._short_opt[opt]
1004                     if not (c_option._short_opts or c_option._long_opts):
1005                         c_option.container.option_list.remove(c_option)
1006
1007     def add_option(self, *args, **kwargs):
1008         """add_option(Option)
1009            add_option(opt_str, ..., kwarg=val, ...)
1010         """
1011         if type(args[0]) is types.StringType:
1012             option = self.option_class(*args, **kwargs)
1013         elif len(args) == 1 and not kwargs:
1014             option = args[0]
1015             if not isinstance(option, Option):
1016                 raise TypeError, "not an Option instance: %r" % option
1017         else:
1018             raise TypeError, "invalid arguments"
1019
1020         self._check_conflict(option)
1021
1022         self.option_list.append(option)
1023         option.container = self
1024         for opt in option._short_opts:
1025             self._short_opt[opt] = option
1026         for opt in option._long_opts:
1027             self._long_opt[opt] = option
1028
1029         if option.dest is not None:     # option has a dest, we need a default
1030             if option.default is not NO_DEFAULT:
1031                 self.defaults[option.dest] = option.default
1032             elif not self.defaults.has_key(option.dest):
1033                 self.defaults[option.dest] = None
1034
1035         return option
1036
1037     def add_options(self, option_list):
1038         for option in option_list:
1039             self.add_option(option)
1040
1041     # -- Option query/removal methods ----------------------------------
1042
1043     def get_option(self, opt_str):
1044         return (self._short_opt.get(opt_str) or
1045                 self._long_opt.get(opt_str))
1046
1047     def has_option(self, opt_str):
1048         return (self._short_opt.has_key(opt_str) or
1049                 self._long_opt.has_key(opt_str))
1050
1051     def remove_option(self, opt_str):
1052         option = self._short_opt.get(opt_str)
1053         if option is None:
1054             option = self._long_opt.get(opt_str)
1055         if option is None:
1056             raise ValueError("no such option %r" % opt_str)
1057
1058         for opt in option._short_opts:
1059             del self._short_opt[opt]
1060         for opt in option._long_opts:
1061             del self._long_opt[opt]
1062         option.container.option_list.remove(option)
1063
1064
1065     # -- Help-formatting methods ---------------------------------------
1066
1067     def format_option_help(self, formatter):
1068         if not self.option_list:
1069             return ""
1070         result = []
1071         for option in self.option_list:
1072             if not option.help is SUPPRESS_HELP:
1073                 result.append(formatter.format_option(option))
1074         return "".join(result)
1075
1076     def format_description(self, formatter):
1077         return formatter.format_description(self.get_description())
1078
1079     def format_help(self, formatter):
1080         result = []
1081         if self.description:
1082             result.append(self.format_description(formatter))
1083         if self.option_list:
1084             result.append(self.format_option_help(formatter))
1085         return "\n".join(result)
1086
1087
1088 class OptionGroup (OptionContainer):
1089
1090     def __init__(self, parser, title, description=None):
1091         self.parser = parser
1092         OptionContainer.__init__(
1093             self, parser.option_class, parser.conflict_handler, description)
1094         self.title = title
1095
1096     def _create_option_list(self):
1097         self.option_list = []
1098         self._share_option_mappings(self.parser)
1099
1100     def set_title(self, title):
1101         self.title = title
1102
1103     def destroy(self):
1104         """see OptionParser.destroy()."""
1105         OptionContainer.destroy(self)
1106         del self.option_list
1107
1108     # -- Help-formatting methods ---------------------------------------
1109
1110     def format_help(self, formatter):
1111         result = formatter.format_heading(self.title)
1112         formatter.indent()
1113         result += OptionContainer.format_help(self, formatter)
1114         formatter.dedent()
1115         return result
1116
1117
1118 class OptionParser (OptionContainer):
1119
1120     """
1121     Class attributes:
1122       standard_option_list : [Option]
1123         list of standard options that will be accepted by all instances
1124         of this parser class (intended to be overridden by subclasses).
1125
1126     Instance attributes:
1127       usage : string
1128         a usage string for your program.  Before it is displayed
1129         to the user, "%prog" will be expanded to the name of
1130         your program (self.prog or os.path.basename(sys.argv[0])).
1131       prog : string
1132         the name of the current program (to override
1133         os.path.basename(sys.argv[0])).
1134       epilog : string
1135         paragraph of help text to print after option help
1136
1137       option_groups : [OptionGroup]
1138         list of option groups in this parser (option groups are
1139         irrelevant for parsing the command-line, but very useful
1140         for generating help)
1141
1142       allow_interspersed_args : bool = true
1143         if true, positional arguments may be interspersed with options.
1144         Assuming -a and -b each take a single argument, the command-line
1145           -ablah foo bar -bboo baz
1146         will be interpreted the same as
1147           -ablah -bboo -- foo bar baz
1148         If this flag were false, that command line would be interpreted as
1149           -ablah -- foo bar -bboo baz
1150         -- ie. we stop processing options as soon as we see the first
1151         non-option argument.  (This is the tradition followed by
1152         Python's getopt module, Perl's Getopt::Std, and other argument-
1153         parsing libraries, but it is generally annoying to users.)
1154
1155       process_default_values : bool = true
1156         if true, option default values are processed similarly to option
1157         values from the command line: that is, they are passed to the
1158         type-checking function for the option's type (as long as the
1159         default value is a string).  (This really only matters if you
1160         have defined custom types; see SF bug #955889.)  Set it to false
1161         to restore the behaviour of Optik 1.4.1 and earlier.
1162
1163       rargs : [string]
1164         the argument list currently being parsed.  Only set when
1165         parse_args() is active, and continually trimmed down as
1166         we consume arguments.  Mainly there for the benefit of
1167         callback options.
1168       largs : [string]
1169         the list of leftover arguments that we have skipped while
1170         parsing options.  If allow_interspersed_args is false, this
1171         list is always empty.
1172       values : Values
1173         the set of option values currently being accumulated.  Only
1174         set when parse_args() is active.  Also mainly for callbacks.
1175
1176     Because of the 'rargs', 'largs', and 'values' attributes,
1177     OptionParser is not thread-safe.  If, for some perverse reason, you
1178     need to parse command-line arguments simultaneously in different
1179     threads, use different OptionParser instances.
1180
1181     """
1182
1183     standard_option_list = []
1184
1185     def __init__(self,
1186                  usage=None,
1187                  option_list=None,
1188                  option_class=Option,
1189                  version=None,
1190                  conflict_handler="error",
1191                  description=None,
1192                  formatter=None,
1193                  add_help_option=True,
1194                  prog=None,
1195                  epilog=None):
1196         OptionContainer.__init__(
1197             self, option_class, conflict_handler, description)
1198         self.set_usage(usage)
1199         self.prog = prog
1200         self.version = version
1201         self.allow_interspersed_args = True
1202         self.process_default_values = True
1203         if formatter is None:
1204             formatter = IndentedHelpFormatter()
1205         self.formatter = formatter
1206         self.formatter.set_parser(self)
1207         self.epilog = epilog
1208
1209         # Populate the option list; initial sources are the
1210         # standard_option_list class attribute, the 'option_list'
1211         # argument, and (if applicable) the _add_version_option() and
1212         # _add_help_option() methods.
1213         self._populate_option_list(option_list,
1214                                    add_help=add_help_option)
1215
1216         self._init_parsing_state()
1217
1218
1219     def destroy(self):
1220         """
1221         Declare that you are done with this OptionParser.  This cleans up
1222         reference cycles so the OptionParser (and all objects referenced by
1223         it) can be garbage-collected promptly.  After calling destroy(), the
1224         OptionParser is unusable.
1225         """
1226         OptionContainer.destroy(self)
1227         for group in self.option_groups:
1228             group.destroy()
1229         del self.option_list
1230         del self.option_groups
1231         del self.formatter
1232
1233
1234     # -- Private methods -----------------------------------------------
1235     # (used by our or OptionContainer's constructor)
1236
1237     def _create_option_list(self):
1238         self.option_list = []
1239         self.option_groups = []
1240         self._create_option_mappings()
1241
1242     def _add_help_option(self):
1243         self.add_option("-h", "--help",
1244                         action="help",
1245                         help=_("show this help message and exit"))
1246
1247     def _add_version_option(self):
1248         self.add_option("--version",
1249                         action="version",
1250                         help=_("show program's version number and exit"))
1251
1252     def _populate_option_list(self, option_list, add_help=True):
1253         if self.standard_option_list:
1254             self.add_options(self.standard_option_list)
1255         if option_list:
1256             self.add_options(option_list)
1257         if self.version:
1258             self._add_version_option()
1259         if add_help:
1260             self._add_help_option()
1261
1262     def _init_parsing_state(self):
1263         # These are set in parse_args() for the convenience of callbacks.
1264         self.rargs = None
1265         self.largs = None
1266         self.values = None
1267
1268
1269     # -- Simple modifier methods ---------------------------------------
1270
1271     def set_usage(self, usage):
1272         if usage is None:
1273             self.usage = _("%prog [options]")
1274         elif usage is SUPPRESS_USAGE:
1275             self.usage = None
1276         # For backwards compatibility with Optik 1.3 and earlier.
1277         elif usage.lower().startswith("usage: "):
1278             self.usage = usage[7:]
1279         else:
1280             self.usage = usage
1281
1282     def enable_interspersed_args(self):
1283         self.allow_interspersed_args = True
1284
1285     def disable_interspersed_args(self):
1286         self.allow_interspersed_args = False
1287
1288     def set_process_default_values(self, process):
1289         self.process_default_values = process
1290
1291     def set_default(self, dest, value):
1292         self.defaults[dest] = value
1293
1294     def set_defaults(self, **kwargs):
1295         self.defaults.update(kwargs)
1296
1297     def _get_all_options(self):
1298         options = self.option_list[:]
1299         for group in self.option_groups:
1300             options.extend(group.option_list)
1301         return options
1302
1303     def get_default_values(self):
1304         if not self.process_default_values:
1305             # Old, pre-Optik 1.5 behaviour.
1306             return Values(self.defaults)
1307
1308         defaults = self.defaults.copy()
1309         for option in self._get_all_options():
1310             default = defaults.get(option.dest)
1311             if isbasestring(default):
1312                 opt_str = option.get_opt_string()
1313                 defaults[option.dest] = option.check_value(opt_str, default)
1314
1315         return Values(defaults)
1316
1317
1318     # -- OptionGroup methods -------------------------------------------
1319
1320     def add_option_group(self, *args, **kwargs):
1321         # XXX lots of overlap with OptionContainer.add_option()
1322         if type(args[0]) is types.StringType:
1323             group = OptionGroup(self, *args, **kwargs)
1324         elif len(args) == 1 and not kwargs:
1325             group = args[0]
1326             if not isinstance(group, OptionGroup):
1327                 raise TypeError, "not an OptionGroup instance: %r" % group
1328             if group.parser is not self:
1329                 raise ValueError, "invalid OptionGroup (wrong parser)"
1330         else:
1331             raise TypeError, "invalid arguments"
1332
1333         self.option_groups.append(group)
1334         return group
1335
1336     def get_option_group(self, opt_str):
1337         option = (self._short_opt.get(opt_str) or
1338                   self._long_opt.get(opt_str))
1339         if option and option.container is not self:
1340             return option.container
1341         return None
1342
1343
1344     # -- Option-parsing methods ----------------------------------------
1345
1346     def _get_args(self, args):
1347         if args is None:
1348             return sys.argv[1:]
1349         else:
1350             return args[:]              # don't modify caller's list
1351
1352     def parse_args(self, args=None, values=None):
1353         """
1354         parse_args(args : [string] = sys.argv[1:],
1355                    values : Values = None)
1356         -> (values : Values, args : [string])
1357
1358         Parse the command-line options found in 'args' (default:
1359         sys.argv[1:]).  Any errors result in a call to 'error()', which
1360         by default prints the usage message to stderr and calls
1361         sys.exit() with an error message.  On success returns a pair
1362         (values, args) where 'values' is an Values instance (with all
1363         your option values) and 'args' is the list of arguments left
1364         over after parsing options.
1365         """
1366         rargs = self._get_args(args)
1367         if values is None:
1368             values = self.get_default_values()
1369
1370         # Store the halves of the argument list as attributes for the
1371         # convenience of callbacks:
1372         #   rargs
1373         #     the rest of the command-line (the "r" stands for
1374         #     "remaining" or "right-hand")
1375         #   largs
1376         #     the leftover arguments -- ie. what's left after removing
1377         #     options and their arguments (the "l" stands for "leftover"
1378         #     or "left-hand")
1379         self.rargs = rargs
1380         self.largs = largs = []
1381         self.values = values
1382
1383         try:
1384             stop = self._process_args(largs, rargs, values)
1385         except (BadOptionError, OptionValueError), err:
1386             self.error(str(err))
1387
1388         args = largs + rargs
1389         return self.check_values(values, args)
1390
1391     def check_values(self, values, args):
1392         """
1393         check_values(values : Values, args : [string])
1394         -> (values : Values, args : [string])
1395
1396         Check that the supplied option values and leftover arguments are
1397         valid.  Returns the option values and leftover arguments
1398         (possibly adjusted, possibly completely new -- whatever you
1399         like).  Default implementation just returns the passed-in
1400         values; subclasses may override as desired.
1401         """
1402         return (values, args)
1403
1404     def _process_args(self, largs, rargs, values):
1405         """_process_args(largs : [string],
1406                          rargs : [string],
1407                          values : Values)
1408
1409         Process command-line arguments and populate 'values', consuming
1410         options and arguments from 'rargs'.  If 'allow_interspersed_args' is
1411         false, stop at the first non-option argument.  If true, accumulate any
1412         interspersed non-option arguments in 'largs'.
1413         """
1414         while rargs:
1415             arg = rargs[0]
1416             # We handle bare "--" explicitly, and bare "-" is handled by the
1417             # standard arg handler since the short arg case ensures that the
1418             # len of the opt string is greater than 1.
1419             if arg == "--":
1420                 del rargs[0]
1421                 return
1422             elif arg[0:2] == "--":
1423                 # process a single long option (possibly with value(s))
1424                 self._process_long_opt(rargs, values)
1425             elif arg[:1] == "-" and len(arg) > 1:
1426                 # process a cluster of short options (possibly with
1427                 # value(s) for the last one only)
1428                 self._process_short_opts(rargs, values)
1429             elif self.allow_interspersed_args:
1430                 largs.append(arg)
1431                 del rargs[0]
1432             else:
1433                 return                  # stop now, leave this arg in rargs
1434
1435         # Say this is the original argument list:
1436         # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)]
1437         #                            ^
1438         # (we are about to process arg(i)).
1439         #
1440         # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of
1441         # [arg0, ..., arg(i-1)] (any options and their arguments will have
1442         # been removed from largs).
1443         #
1444         # The while loop will usually consume 1 or more arguments per pass.
1445         # If it consumes 1 (eg. arg is an option that takes no arguments),
1446         # then after _process_arg() is done the situation is:
1447         #
1448         #   largs = subset of [arg0, ..., arg(i)]
1449         #   rargs = [arg(i+1), ..., arg(N-1)]
1450         #
1451         # If allow_interspersed_args is false, largs will always be
1452         # *empty* -- still a subset of [arg0, ..., arg(i-1)], but
1453         # not a very interesting subset!
1454
1455     def _match_long_opt(self, opt):
1456         """_match_long_opt(opt : string) -> string
1457
1458         Determine which long option string 'opt' matches, ie. which one
1459         it is an unambiguous abbrevation for.  Raises BadOptionError if
1460         'opt' doesn't unambiguously match any long option string.
1461         """
1462         return _match_abbrev(opt, self._long_opt)
1463
1464     def _process_long_opt(self, rargs, values):
1465         arg = rargs.pop(0)
1466
1467         # Value explicitly attached to arg?  Pretend it's the next
1468         # argument.
1469         if "=" in arg:
1470             (opt, next_arg) = arg.split("=", 1)
1471             rargs.insert(0, next_arg)
1472             had_explicit_value = True
1473         else:
1474             opt = arg
1475             had_explicit_value = False
1476
1477         opt = self._match_long_opt(opt)
1478         option = self._long_opt[opt]
1479         if option.takes_value():
1480             nargs = option.nargs
1481             if len(rargs) < nargs:
1482                 if nargs == 1:
1483                     self.error(_("%s option requires an argument") % opt)
1484                 else:
1485                     self.error(_("%s option requires %d arguments")
1486                                % (opt, nargs))
1487             elif nargs == 1:
1488                 value = rargs.pop(0)
1489             else:
1490                 value = tuple(rargs[0:nargs])
1491                 del rargs[0:nargs]
1492
1493         elif had_explicit_value:
1494             self.error(_("%s option does not take a value") % opt)
1495
1496         else:
1497             value = None
1498
1499         option.process(opt, value, values, self)
1500
1501     def _process_short_opts(self, rargs, values):
1502         arg = rargs.pop(0)
1503         stop = False
1504         i = 1
1505         for ch in arg[1:]:
1506             opt = "-" + ch
1507             option = self._short_opt.get(opt)
1508             i += 1                      # we have consumed a character
1509
1510             if not option:
1511                 raise BadOptionError(opt)
1512             if option.takes_value():
1513                 # Any characters left in arg?  Pretend they're the
1514                 # next arg, and stop consuming characters of arg.
1515                 if i < len(arg):
1516                     rargs.insert(0, arg[i:])
1517                     stop = True
1518
1519                 nargs = option.nargs
1520                 if len(rargs) < nargs:
1521                     if nargs == 1:
1522                         self.error(_("%s option requires an argument") % opt)
1523                     else:
1524                         self.error(_("%s option requires %d arguments")
1525                                    % (opt, nargs))
1526                 elif nargs == 1:
1527                     value = rargs.pop(0)
1528                 else:
1529                     value = tuple(rargs[0:nargs])
1530                     del rargs[0:nargs]
1531
1532             else:                       # option doesn't take a value
1533                 value = None
1534
1535             option.process(opt, value, values, self)
1536
1537             if stop:
1538                 break
1539
1540
1541     # -- Feedback methods ----------------------------------------------
1542
1543     def get_prog_name(self):
1544         if self.prog is None:
1545             return os.path.basename(sys.argv[0])
1546         else:
1547             return self.prog
1548
1549     def expand_prog_name(self, s):
1550         return s.replace("%prog", self.get_prog_name())
1551
1552     def get_description(self):
1553         return self.expand_prog_name(self.description)
1554
1555     def exit(self, status=0, msg=None):
1556         if msg:
1557             sys.stderr.write(msg)
1558         sys.exit(status)
1559
1560     def error(self, msg):
1561         """error(msg : string)
1562
1563         Print a usage message incorporating 'msg' to stderr and exit.
1564         If you override this in a subclass, it should not return -- it
1565         should either exit or raise an exception.
1566         """
1567         self.print_usage(sys.stderr)
1568         self.exit(2, "%s: error: %s\n" % (self.get_prog_name(), msg))
1569
1570     def get_usage(self):
1571         if self.usage:
1572             return self.formatter.format_usage(
1573                 self.expand_prog_name(self.usage))
1574         else:
1575             return ""
1576
1577     def print_usage(self, file=None):
1578         """print_usage(file : file = stdout)
1579
1580         Print the usage message for the current program (self.usage) to
1581         'file' (default stdout).  Any occurence of the string "%prog" in
1582         self.usage is replaced with the name of the current program
1583         (basename of sys.argv[0]).  Does nothing if self.usage is empty
1584         or not defined.
1585         """
1586         if self.usage:
1587             print >>file, self.get_usage()
1588
1589     def get_version(self):
1590         if self.version:
1591             return self.expand_prog_name(self.version)
1592         else:
1593             return ""
1594
1595     def print_version(self, file=None):
1596         """print_version(file : file = stdout)
1597
1598         Print the version message for this program (self.version) to
1599         'file' (default stdout).  As with print_usage(), any occurence
1600         of "%prog" in self.version is replaced by the current program's
1601         name.  Does nothing if self.version is empty or undefined.
1602         """
1603         if self.version:
1604             print >>file, self.get_version()
1605
1606     def format_option_help(self, formatter=None):
1607         if formatter is None:
1608             formatter = self.formatter
1609         formatter.store_option_strings(self)
1610         result = []
1611         result.append(formatter.format_heading(_("Options")))
1612         formatter.indent()
1613         if self.option_list:
1614             result.append(OptionContainer.format_option_help(self, formatter))
1615             result.append("\n")
1616         for group in self.option_groups:
1617             result.append(group.format_help(formatter))
1618             result.append("\n")
1619         formatter.dedent()
1620         # Drop the last "\n", or the header if no options or option groups:
1621         return "".join(result[:-1])
1622
1623     def format_epilog(self, formatter):
1624         return formatter.format_epilog(self.epilog)
1625
1626     def format_help(self, formatter=None):
1627         if formatter is None:
1628             formatter = self.formatter
1629         result = []
1630         if self.usage:
1631             result.append(self.get_usage() + "\n")
1632         if self.description:
1633             result.append(self.format_description(formatter) + "\n")
1634         result.append(self.format_option_help(formatter))
1635         result.append(self.format_epilog(formatter))
1636         return "".join(result)
1637
1638     # used by test suite
1639     def _get_encoding(self, file):
1640         encoding = getattr(file, "encoding", None)
1641         if not encoding:
1642             encoding = sys.getdefaultencoding()
1643         return encoding
1644
1645     def print_help(self, file=None):
1646         """print_help(file : file = stdout)
1647
1648         Print an extended help message, listing all options and any
1649         help text provided with them, to 'file' (default stdout).
1650         """
1651         if file is None:
1652             file = sys.stdout
1653         encoding = self._get_encoding(file)
1654         file.write(self.format_help().encode(encoding, "replace"))
1655
1656 # class OptionParser
1657
1658
1659 def _match_abbrev(s, wordmap):
1660     """_match_abbrev(s : string, wordmap : {string : Option}) -> string
1661
1662     Return the string key in 'wordmap' for which 's' is an unambiguous
1663     abbreviation.  If 's' is found to be ambiguous or doesn't match any of
1664     'words', raise BadOptionError.
1665     """
1666     # Is there an exact match?
1667     if wordmap.has_key(s):
1668         return s
1669     else:
1670         # Isolate all words with s as a prefix.
1671         possibilities = [word for word in wordmap.keys()
1672                          if word.startswith(s)]
1673         # No exact match, so there had better be just one possibility.
1674         if len(possibilities) == 1:
1675             return possibilities[0]
1676         elif not possibilities:
1677             raise BadOptionError(s)
1678         else:
1679             # More than one possible completion: ambiguous prefix.
1680             possibilities.sort()
1681             raise AmbiguousOptionError(s, possibilities)
1682
1683
1684 # Some day, there might be many Option classes.  As of Optik 1.3, the
1685 # preferred way to instantiate Options is indirectly, via make_option(),
1686 # which will become a factory function when there are many Option
1687 # classes.
1688 make_option = Option