docutils/optik.py

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