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