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