Lib/optparse.py

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