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