optparse.py revision 456d3258d64f4c60a7787dd59f5c68bafb81584c
1"""optparse - a powerful, extensible, and easy-to-use option parser. 2 3By Greg Ward <gward@python.net> 4 5Originally distributed as Optik; see http://optik.sourceforge.net/ . 6 7If you have problems with this module, please do not file bugs, 8patches, or feature requests with Python; instead, use Optik's 9SourceForge project page: 10 http://sourceforge.net/projects/optik 11 12For 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__ = """ 40Copyright (c) 2001-2003 Gregory P. Ward. All rights reserved. 41 42Redistribution and use in source and binary forms, with or without 43modification, are permitted provided that the following conditions are 44met: 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 57THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 58IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 59TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 60PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR 61CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 62EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 63PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 64PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 65LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 66NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 67SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 68""" 69 70import sys, os 71import types 72import textwrap 73 74class OptParseError (Exception): 75 def __init__ (self, msg): 76 self.msg = msg 77 78 def __str__ (self): 79 return self.msg 80 81 82class 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 98class OptionConflictError (OptionError): 99 """ 100 Raised if conflicting options are added to an OptionParser. 101 """ 102 103class OptionValueError (OptParseError): 104 """ 105 Raised if an invalid option value is encountered on the command 106 line. 107 """ 108 109class BadOptionError (OptParseError): 110 """ 111 Raised if an invalid or ambiguous option is seen on the command-line. 112 """ 113 114 115class 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 243class 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=79, 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 262class 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=79, 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 286def 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 295def 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. 306NO_DEFAULT = "NO"+"DEFAULT" 307 308 309class 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 645def get_prog_name (): 646 return os.path.basename(sys.argv[0]) 647 648 649SUPPRESS_HELP = "SUPPRESS"+"HELP" 650SUPPRESS_USAGE = "SUPPRESS"+"USAGE" 651 652STD_HELP_OPTION = Option("-h", "--help", 653 action="help", 654 help="show this help message and exit") 655STD_VERSION_OPTION = Option("--version", 656 action="version", 657 help="show program's version number and exit") 658 659 660class 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 716class 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 898class 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 923class 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 def _get_prog_name(self): 1029 if self.prog: 1030 return self.prog 1031 else: 1032 return get_prog_name() 1033 1034 # -- Simple modifier methods --------------------------------------- 1035 1036 def set_usage (self, usage): 1037 if usage is None: 1038 self.usage = "%prog [options]" 1039 elif usage is SUPPRESS_USAGE: 1040 self.usage = None 1041 elif usage.lower().startswith("usage: "): 1042 # for backwards compatibility with Optik 1.3 and earlier 1043 self.usage = usage[7:] 1044 else: 1045 self.usage = usage 1046 1047 def enable_interspersed_args (self): 1048 self.allow_interspersed_args = 1 1049 1050 def disable_interspersed_args (self): 1051 self.allow_interspersed_args = 0 1052 1053 def set_default (self, dest, value): 1054 self.defaults[dest] = value 1055 1056 def set_defaults (self, **kwargs): 1057 self.defaults.update(kwargs) 1058 1059 def get_default_values (self): 1060 return Values(self.defaults) 1061 1062 1063 # -- OptionGroup methods ------------------------------------------- 1064 1065 def add_option_group (self, *args, **kwargs): 1066 # XXX lots of overlap with OptionContainer.add_option() 1067 if type(args[0]) is types.StringType: 1068 group = OptionGroup(self, *args, **kwargs) 1069 elif len(args) == 1 and not kwargs: 1070 group = args[0] 1071 if not isinstance(group, OptionGroup): 1072 raise TypeError, "not an OptionGroup instance: %r" % group 1073 if group.parser is not self: 1074 raise ValueError, "invalid OptionGroup (wrong parser)" 1075 else: 1076 raise TypeError, "invalid arguments" 1077 1078 self.option_groups.append(group) 1079 return group 1080 1081 def get_option_group (self, opt_str): 1082 option = (self._short_opt.get(opt_str) or 1083 self._long_opt.get(opt_str)) 1084 if option and option.container is not self: 1085 return option.container 1086 return None 1087 1088 1089 # -- Option-parsing methods ---------------------------------------- 1090 1091 def _get_args (self, args): 1092 if args is None: 1093 return sys.argv[1:] 1094 else: 1095 return args[:] # don't modify caller's list 1096 1097 def parse_args (self, args=None, values=None): 1098 """ 1099 parse_args(args : [string] = sys.argv[1:], 1100 values : Values = None) 1101 -> (values : Values, args : [string]) 1102 1103 Parse the command-line options found in 'args' (default: 1104 sys.argv[1:]). Any errors result in a call to 'error()', which 1105 by default prints the usage message to stderr and calls 1106 sys.exit() with an error message. On success returns a pair 1107 (values, args) where 'values' is an Values instance (with all 1108 your option values) and 'args' is the list of arguments left 1109 over after parsing options. 1110 """ 1111 rargs = self._get_args(args) 1112 if values is None: 1113 values = self.get_default_values() 1114 1115 # Store the halves of the argument list as attributes for the 1116 # convenience of callbacks: 1117 # rargs 1118 # the rest of the command-line (the "r" stands for 1119 # "remaining" or "right-hand") 1120 # largs 1121 # the leftover arguments -- ie. what's left after removing 1122 # options and their arguments (the "l" stands for "leftover" 1123 # or "left-hand") 1124 self.rargs = rargs 1125 self.largs = largs = [] 1126 self.values = values 1127 1128 try: 1129 stop = self._process_args(largs, rargs, values) 1130 except (BadOptionError, OptionValueError), err: 1131 self.error(err.msg) 1132 1133 args = largs + rargs 1134 return self.check_values(values, args) 1135 1136 def check_values (self, values, args): 1137 """ 1138 check_values(values : Values, args : [string]) 1139 -> (values : Values, args : [string]) 1140 1141 Check that the supplied option values and leftover arguments are 1142 valid. Returns the option values and leftover arguments 1143 (possibly adjusted, possibly completely new -- whatever you 1144 like). Default implementation just returns the passed-in 1145 values; subclasses may override as desired. 1146 """ 1147 return (values, args) 1148 1149 def _process_args (self, largs, rargs, values): 1150 """_process_args(largs : [string], 1151 rargs : [string], 1152 values : Values) 1153 1154 Process command-line arguments and populate 'values', consuming 1155 options and arguments from 'rargs'. If 'allow_interspersed_args' is 1156 false, stop at the first non-option argument. If true, accumulate any 1157 interspersed non-option arguments in 'largs'. 1158 """ 1159 while rargs: 1160 arg = rargs[0] 1161 # We handle bare "--" explicitly, and bare "-" is handled by the 1162 # standard arg handler since the short arg case ensures that the 1163 # len of the opt string is greater than 1. 1164 if arg == "--": 1165 del rargs[0] 1166 return 1167 elif arg[0:2] == "--": 1168 # process a single long option (possibly with value(s)) 1169 self._process_long_opt(rargs, values) 1170 elif arg[:1] == "-" and len(arg) > 1: 1171 # process a cluster of short options (possibly with 1172 # value(s) for the last one only) 1173 self._process_short_opts(rargs, values) 1174 elif self.allow_interspersed_args: 1175 largs.append(arg) 1176 del rargs[0] 1177 else: 1178 return # stop now, leave this arg in rargs 1179 1180 # Say this is the original argument list: 1181 # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)] 1182 # ^ 1183 # (we are about to process arg(i)). 1184 # 1185 # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of 1186 # [arg0, ..., arg(i-1)] (any options and their arguments will have 1187 # been removed from largs). 1188 # 1189 # The while loop will usually consume 1 or more arguments per pass. 1190 # If it consumes 1 (eg. arg is an option that takes no arguments), 1191 # then after _process_arg() is done the situation is: 1192 # 1193 # largs = subset of [arg0, ..., arg(i)] 1194 # rargs = [arg(i+1), ..., arg(N-1)] 1195 # 1196 # If allow_interspersed_args is false, largs will always be 1197 # *empty* -- still a subset of [arg0, ..., arg(i-1)], but 1198 # not a very interesting subset! 1199 1200 def _match_long_opt (self, opt): 1201 """_match_long_opt(opt : string) -> string 1202 1203 Determine which long option string 'opt' matches, ie. which one 1204 it is an unambiguous abbrevation for. Raises BadOptionError if 1205 'opt' doesn't unambiguously match any long option string. 1206 """ 1207 return _match_abbrev(opt, self._long_opt) 1208 1209 def _process_long_opt (self, rargs, values): 1210 arg = rargs.pop(0) 1211 1212 # Value explicitly attached to arg? Pretend it's the next 1213 # argument. 1214 if "=" in arg: 1215 (opt, next_arg) = arg.split("=", 1) 1216 rargs.insert(0, next_arg) 1217 had_explicit_value = 1 1218 else: 1219 opt = arg 1220 had_explicit_value = 0 1221 1222 opt = self._match_long_opt(opt) 1223 option = self._long_opt[opt] 1224 if option.takes_value(): 1225 nargs = option.nargs 1226 if len(rargs) < nargs: 1227 if nargs == 1: 1228 self.error("%s option requires a value" % opt) 1229 else: 1230 self.error("%s option requires %d values" 1231 % (opt, nargs)) 1232 elif nargs == 1: 1233 value = rargs.pop(0) 1234 else: 1235 value = tuple(rargs[0:nargs]) 1236 del rargs[0:nargs] 1237 1238 elif had_explicit_value: 1239 self.error("%s option does not take a value" % opt) 1240 1241 else: 1242 value = None 1243 1244 option.process(opt, value, values, self) 1245 1246 def _process_short_opts (self, rargs, values): 1247 arg = rargs.pop(0) 1248 stop = 0 1249 i = 1 1250 for ch in arg[1:]: 1251 opt = "-" + ch 1252 option = self._short_opt.get(opt) 1253 i += 1 # we have consumed a character 1254 1255 if not option: 1256 self.error("no such option: %s" % opt) 1257 if option.takes_value(): 1258 # Any characters left in arg? Pretend they're the 1259 # next arg, and stop consuming characters of arg. 1260 if i < len(arg): 1261 rargs.insert(0, arg[i:]) 1262 stop = 1 1263 1264 nargs = option.nargs 1265 if len(rargs) < nargs: 1266 if nargs == 1: 1267 self.error("%s option requires a value" % opt) 1268 else: 1269 self.error("%s option requires %s values" 1270 % (opt, nargs)) 1271 elif nargs == 1: 1272 value = rargs.pop(0) 1273 else: 1274 value = tuple(rargs[0:nargs]) 1275 del rargs[0:nargs] 1276 1277 else: # option doesn't take a value 1278 value = None 1279 1280 option.process(opt, value, values, self) 1281 1282 if stop: 1283 break 1284 1285 1286 # -- Feedback methods ---------------------------------------------- 1287 1288 def error (self, msg): 1289 """error(msg : string) 1290 1291 Print a usage message incorporating 'msg' to stderr and exit. 1292 If you override this in a subclass, it should not return -- it 1293 should either exit or raise an exception. 1294 """ 1295 self.print_usage(sys.stderr) 1296 sys.exit("%s: error: %s" % (self._get_prog_name(), msg)) 1297 1298 def get_usage (self): 1299 if self.usage: 1300 return self.formatter.format_usage( 1301 self.usage.replace("%prog", self._get_prog_name())) 1302 else: 1303 return "" 1304 1305 def print_usage (self, file=None): 1306 """print_usage(file : file = stdout) 1307 1308 Print the usage message for the current program (self.usage) to 1309 'file' (default stdout). Any occurence of the string "%prog" in 1310 self.usage is replaced with the name of the current program 1311 (basename of sys.argv[0]). Does nothing if self.usage is empty 1312 or not defined. 1313 """ 1314 if self.usage: 1315 print >>file, self.get_usage() 1316 1317 def get_version (self): 1318 if self.version: 1319 return self.version.replace("%prog", self._get_prog_name()) 1320 else: 1321 return "" 1322 1323 def print_version (self, file=None): 1324 """print_version(file : file = stdout) 1325 1326 Print the version message for this program (self.version) to 1327 'file' (default stdout). As with print_usage(), any occurence 1328 of "%prog" in self.version is replaced by the current program's 1329 name. Does nothing if self.version is empty or undefined. 1330 """ 1331 if self.version: 1332 print >>file, self.get_version() 1333 1334 def format_option_help (self, formatter=None): 1335 if formatter is None: 1336 formatter = self.formatter 1337 formatter.store_option_strings(self) 1338 result = [] 1339 result.append(formatter.format_heading("options")) 1340 formatter.indent() 1341 if self.option_list: 1342 result.append(OptionContainer.format_option_help(self, formatter)) 1343 result.append("\n") 1344 for group in self.option_groups: 1345 result.append(group.format_help(formatter)) 1346 result.append("\n") 1347 formatter.dedent() 1348 # Drop the last "\n", or the header if no options or option groups: 1349 return "".join(result[:-1]) 1350 1351 def format_help (self, formatter=None): 1352 if formatter is None: 1353 formatter = self.formatter 1354 result = [] 1355 if self.usage: 1356 result.append(self.get_usage() + "\n") 1357 if self.description: 1358 result.append(self.format_description(formatter) + "\n") 1359 result.append(self.format_option_help(formatter)) 1360 return "".join(result) 1361 1362 def print_help (self, file=None): 1363 """print_help(file : file = stdout) 1364 1365 Print an extended help message, listing all options and any 1366 help text provided with them, to 'file' (default stdout). 1367 """ 1368 if file is None: 1369 file = sys.stdout 1370 file.write(self.format_help()) 1371 1372# class OptionParser 1373 1374 1375def _match_abbrev (s, wordmap): 1376 """_match_abbrev(s : string, wordmap : {string : Option}) -> string 1377 1378 Return the string key in 'wordmap' for which 's' is an unambiguous 1379 abbreviation. If 's' is found to be ambiguous or doesn't match any of 1380 'words', raise BadOptionError. 1381 """ 1382 # Is there an exact match? 1383 if wordmap.has_key(s): 1384 return s 1385 else: 1386 # Isolate all words with s as a prefix. 1387 possibilities = [word for word in wordmap.keys() 1388 if word.startswith(s)] 1389 # No exact match, so there had better be just one possibility. 1390 if len(possibilities) == 1: 1391 return possibilities[0] 1392 elif not possibilities: 1393 raise BadOptionError("no such option: %s" % s) 1394 else: 1395 # More than one possible completion: ambiguous prefix. 1396 raise BadOptionError("ambiguous option: %s (%s?)" 1397 % (s, ", ".join(possibilities))) 1398 1399 1400# Some day, there might be many Option classes. As of Optik 1.3, the 1401# preferred way to instantiate Options is indirectly, via make_option(), 1402# which will become a factory function when there are many Option 1403# classes. 1404make_option = Option 1405