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