Lib/optparse.py

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