1# Author: Steven J. Bethard <steven.bethard@gmail.com>. 2 3"""Command-line parsing library 4 5This module is an optparse-inspired command-line parsing library that: 6 7 - handles both optional and positional arguments 8 - produces highly informative usage messages 9 - supports parsers that dispatch to sub-parsers 10 11The following is a simple usage example that sums integers from the 12command-line and writes the result to a file:: 13 14 parser = argparse.ArgumentParser( 15 description='sum the integers at the command line') 16 parser.add_argument( 17 'integers', metavar='int', nargs='+', type=int, 18 help='an integer to be summed') 19 parser.add_argument( 20 '--log', default=sys.stdout, type=argparse.FileType('w'), 21 help='the file where the sum should be written') 22 args = parser.parse_args() 23 args.log.write('%s' % sum(args.integers)) 24 args.log.close() 25 26The module contains the following public classes: 27 28 - ArgumentParser -- The main entry point for command-line parsing. As the 29 example above shows, the add_argument() method is used to populate 30 the parser with actions for optional and positional arguments. Then 31 the parse_args() method is invoked to convert the args at the 32 command-line into an object with attributes. 33 34 - ArgumentError -- The exception raised by ArgumentParser objects when 35 there are errors with the parser's actions. Errors raised while 36 parsing the command-line are caught by ArgumentParser and emitted 37 as command-line messages. 38 39 - FileType -- A factory for defining types of files to be created. As the 40 example above shows, instances of FileType are typically passed as 41 the type= argument of add_argument() calls. 42 43 - Action -- The base class for parser actions. Typically actions are 44 selected by passing strings like 'store_true' or 'append_const' to 45 the action= argument of add_argument(). However, for greater 46 customization of ArgumentParser actions, subclasses of Action may 47 be defined and passed as the action= argument. 48 49 - HelpFormatter, RawDescriptionHelpFormatter, RawTextHelpFormatter, 50 ArgumentDefaultsHelpFormatter -- Formatter classes which 51 may be passed as the formatter_class= argument to the 52 ArgumentParser constructor. HelpFormatter is the default, 53 RawDescriptionHelpFormatter and RawTextHelpFormatter tell the parser 54 not to change the formatting for help text, and 55 ArgumentDefaultsHelpFormatter adds information about argument defaults 56 to the help. 57 58All other classes in this module are considered implementation details. 59(Also note that HelpFormatter and RawDescriptionHelpFormatter are only 60considered public as object names -- the API of the formatter objects is 61still considered an implementation detail.) 62""" 63 64__version__ = '1.2.1' 65__all__ = [ 66 'ArgumentParser', 67 'ArgumentError', 68 'ArgumentTypeError', 69 'FileType', 70 'HelpFormatter', 71 'ArgumentDefaultsHelpFormatter', 72 'RawDescriptionHelpFormatter', 73 'RawTextHelpFormatter', 74 'Namespace', 75 'Action', 76 'ONE_OR_MORE', 77 'OPTIONAL', 78 'PARSER', 79 'REMAINDER', 80 'SUPPRESS', 81 'ZERO_OR_MORE', 82] 83 84 85import copy as _copy 86import os as _os 87import re as _re 88import sys as _sys 89import textwrap as _textwrap 90 91from gettext import gettext as _ 92 93try: 94 set 95except NameError: 96 # for python < 2.4 compatibility (sets module is there since 2.3): 97 from sets import Set as set 98 99try: 100 basestring 101except NameError: 102 basestring = str 103 104try: 105 sorted 106except NameError: 107 # for python < 2.4 compatibility: 108 def sorted(iterable, reverse=False): 109 result = list(iterable) 110 result.sort() 111 if reverse: 112 result.reverse() 113 return result 114 115 116def _callable(obj): 117 return hasattr(obj, '__call__') or hasattr(obj, '__bases__') 118 119 120SUPPRESS = '==SUPPRESS==' 121 122OPTIONAL = '?' 123ZERO_OR_MORE = '*' 124ONE_OR_MORE = '+' 125PARSER = 'A...' 126REMAINDER = '...' 127_UNRECOGNIZED_ARGS_ATTR = '_unrecognized_args' 128 129# ============================= 130# Utility functions and classes 131# ============================= 132 133class _AttributeHolder(object): 134 """Abstract base class that provides __repr__. 135 136 The __repr__ method returns a string in the format:: 137 ClassName(attr=name, attr=name, ...) 138 The attributes are determined either by a class-level attribute, 139 '_kwarg_names', or by inspecting the instance __dict__. 140 """ 141 142 def __repr__(self): 143 type_name = type(self).__name__ 144 arg_strings = [] 145 for arg in self._get_args(): 146 arg_strings.append(repr(arg)) 147 for name, value in self._get_kwargs(): 148 arg_strings.append('%s=%r' % (name, value)) 149 return '%s(%s)' % (type_name, ', '.join(arg_strings)) 150 151 def _get_kwargs(self): 152 return sorted(self.__dict__.items()) 153 154 def _get_args(self): 155 return [] 156 157 158def _ensure_value(namespace, name, value): 159 if getattr(namespace, name, None) is None: 160 setattr(namespace, name, value) 161 return getattr(namespace, name) 162 163 164# =============== 165# Formatting Help 166# =============== 167 168class HelpFormatter(object): 169 """Formatter for generating usage messages and argument help strings. 170 171 Only the name of this class is considered a public API. All the methods 172 provided by the class are considered an implementation detail. 173 """ 174 175 def __init__(self, 176 prog, 177 indent_increment=2, 178 max_help_position=24, 179 width=None): 180 181 # default setting for width 182 if width is None: 183 try: 184 width = int(_os.environ['COLUMNS']) 185 except (KeyError, ValueError): 186 width = 80 187 width -= 2 188 189 self._prog = prog 190 self._indent_increment = indent_increment 191 self._max_help_position = max_help_position 192 self._width = width 193 194 self._current_indent = 0 195 self._level = 0 196 self._action_max_length = 0 197 198 self._root_section = self._Section(self, None) 199 self._current_section = self._root_section 200 201 self._whitespace_matcher = _re.compile(r'\s+') 202 self._long_break_matcher = _re.compile(r'\n\n\n+') 203 204 # =============================== 205 # Section and indentation methods 206 # =============================== 207 def _indent(self): 208 self._current_indent += self._indent_increment 209 self._level += 1 210 211 def _dedent(self): 212 self._current_indent -= self._indent_increment 213 assert self._current_indent >= 0, 'Indent decreased below 0.' 214 self._level -= 1 215 216 class _Section(object): 217 218 def __init__(self, formatter, parent, heading=None): 219 self.formatter = formatter 220 self.parent = parent 221 self.heading = heading 222 self.items = [] 223 224 def format_help(self): 225 # format the indented section 226 if self.parent is not None: 227 self.formatter._indent() 228 join = self.formatter._join_parts 229 for func, args in self.items: 230 func(*args) 231 item_help = join([func(*args) for func, args in self.items]) 232 if self.parent is not None: 233 self.formatter._dedent() 234 235 # return nothing if the section was empty 236 if not item_help: 237 return '' 238 239 # add the heading if the section was non-empty 240 if self.heading is not SUPPRESS and self.heading is not None: 241 current_indent = self.formatter._current_indent 242 heading = '%*s%s:\n' % (current_indent, '', self.heading) 243 else: 244 heading = '' 245 246 # join the section-initial newline, the heading and the help 247 return join(['\n', heading, item_help, '\n']) 248 249 def _add_item(self, func, args): 250 self._current_section.items.append((func, args)) 251 252 # ======================== 253 # Message building methods 254 # ======================== 255 def start_section(self, heading): 256 self._indent() 257 section = self._Section(self, self._current_section, heading) 258 self._add_item(section.format_help, []) 259 self._current_section = section 260 261 def end_section(self): 262 self._current_section = self._current_section.parent 263 self._dedent() 264 265 def add_text(self, text): 266 if text is not SUPPRESS and text is not None: 267 self._add_item(self._format_text, [text]) 268 269 def add_usage(self, usage, actions, groups, prefix=None): 270 if usage is not SUPPRESS: 271 args = usage, actions, groups, prefix 272 self._add_item(self._format_usage, args) 273 274 def add_argument(self, action): 275 if action.help is not SUPPRESS: 276 277 # find all invocations 278 get_invocation = self._format_action_invocation 279 invocations = [get_invocation(action)] 280 for subaction in self._iter_indented_subactions(action): 281 invocations.append(get_invocation(subaction)) 282 283 # update the maximum item length 284 invocation_length = max([len(s) for s in invocations]) 285 action_length = invocation_length + self._current_indent 286 self._action_max_length = max(self._action_max_length, 287 action_length) 288 289 # add the item to the list 290 self._add_item(self._format_action, [action]) 291 292 def add_arguments(self, actions): 293 for action in actions: 294 self.add_argument(action) 295 296 # ======================= 297 # Help-formatting methods 298 # ======================= 299 def format_help(self): 300 help = self._root_section.format_help() 301 if help: 302 help = self._long_break_matcher.sub('\n\n', help) 303 help = help.strip('\n') + '\n' 304 return help 305 306 def _join_parts(self, part_strings): 307 return ''.join([part 308 for part in part_strings 309 if part and part is not SUPPRESS]) 310 311 def _format_usage(self, usage, actions, groups, prefix): 312 if prefix is None: 313 prefix = _('usage: ') 314 315 # if usage is specified, use that 316 if usage is not None: 317 usage = usage % dict(prog=self._prog) 318 319 # if no optionals or positionals are available, usage is just prog 320 elif usage is None and not actions: 321 usage = '%(prog)s' % dict(prog=self._prog) 322 323 # if optionals and positionals are available, calculate usage 324 elif usage is None: 325 prog = '%(prog)s' % dict(prog=self._prog) 326 327 # split optionals from positionals 328 optionals = [] 329 positionals = [] 330 for action in actions: 331 if action.option_strings: 332 optionals.append(action) 333 else: 334 positionals.append(action) 335 336 # build full usage string 337 format = self._format_actions_usage 338 action_usage = format(optionals + positionals, groups) 339 usage = ' '.join([s for s in [prog, action_usage] if s]) 340 341 # wrap the usage parts if it's too long 342 text_width = self._width - self._current_indent 343 if len(prefix) + len(usage) > text_width: 344 345 # break usage into wrappable parts 346 part_regexp = r'\(.*?\)+|\[.*?\]+|\S+' 347 opt_usage = format(optionals, groups) 348 pos_usage = format(positionals, groups) 349 opt_parts = _re.findall(part_regexp, opt_usage) 350 pos_parts = _re.findall(part_regexp, pos_usage) 351 assert ' '.join(opt_parts) == opt_usage 352 assert ' '.join(pos_parts) == pos_usage 353 354 # helper for wrapping lines 355 def get_lines(parts, indent, prefix=None): 356 lines = [] 357 line = [] 358 if prefix is not None: 359 line_len = len(prefix) - 1 360 else: 361 line_len = len(indent) - 1 362 for part in parts: 363 if line_len + 1 + len(part) > text_width: 364 lines.append(indent + ' '.join(line)) 365 line = [] 366 line_len = len(indent) - 1 367 line.append(part) 368 line_len += len(part) + 1 369 if line: 370 lines.append(indent + ' '.join(line)) 371 if prefix is not None: 372 lines[0] = lines[0][len(indent):] 373 return lines 374 375 # if prog is short, follow it with optionals or positionals 376 if len(prefix) + len(prog) <= 0.75 * text_width: 377 indent = ' ' * (len(prefix) + len(prog) + 1) 378 if opt_parts: 379 lines = get_lines([prog] + opt_parts, indent, prefix) 380 lines.extend(get_lines(pos_parts, indent)) 381 elif pos_parts: 382 lines = get_lines([prog] + pos_parts, indent, prefix) 383 else: 384 lines = [prog] 385 386 # if prog is long, put it on its own line 387 else: 388 indent = ' ' * len(prefix) 389 parts = opt_parts + pos_parts 390 lines = get_lines(parts, indent) 391 if len(lines) > 1: 392 lines = [] 393 lines.extend(get_lines(opt_parts, indent)) 394 lines.extend(get_lines(pos_parts, indent)) 395 lines = [prog] + lines 396 397 # join lines into usage 398 usage = '\n'.join(lines) 399 400 # prefix with 'usage:' 401 return '%s%s\n\n' % (prefix, usage) 402 403 def _format_actions_usage(self, actions, groups): 404 # find group indices and identify actions in groups 405 group_actions = set() 406 inserts = {} 407 for group in groups: 408 try: 409 start = actions.index(group._group_actions[0]) 410 except ValueError: 411 continue 412 else: 413 end = start + len(group._group_actions) 414 if actions[start:end] == group._group_actions: 415 for action in group._group_actions: 416 group_actions.add(action) 417 if not group.required: 418 if start in inserts: 419 inserts[start] += ' [' 420 else: 421 inserts[start] = '[' 422 inserts[end] = ']' 423 else: 424 if start in inserts: 425 inserts[start] += ' (' 426 else: 427 inserts[start] = '(' 428 inserts[end] = ')' 429 for i in range(start + 1, end): 430 inserts[i] = '|' 431 432 # collect all actions format strings 433 parts = [] 434 for i, action in enumerate(actions): 435 436 # suppressed arguments are marked with None 437 # remove | separators for suppressed arguments 438 if action.help is SUPPRESS: 439 parts.append(None) 440 if inserts.get(i) == '|': 441 inserts.pop(i) 442 elif inserts.get(i + 1) == '|': 443 inserts.pop(i + 1) 444 445 # produce all arg strings 446 elif not action.option_strings: 447 part = self._format_args(action, action.dest) 448 449 # if it's in a group, strip the outer [] 450 if action in group_actions: 451 if part[0] == '[' and part[-1] == ']': 452 part = part[1:-1] 453 454 # add the action string to the list 455 parts.append(part) 456 457 # produce the first way to invoke the option in brackets 458 else: 459 option_string = action.option_strings[0] 460 461 # if the Optional doesn't take a value, format is: 462 # -s or --long 463 if action.nargs == 0: 464 part = '%s' % option_string 465 466 # if the Optional takes a value, format is: 467 # -s ARGS or --long ARGS 468 else: 469 default = action.dest.upper() 470 args_string = self._format_args(action, default) 471 part = '%s %s' % (option_string, args_string) 472 473 # make it look optional if it's not required or in a group 474 if not action.required and action not in group_actions: 475 part = '[%s]' % part 476 477 # add the action string to the list 478 parts.append(part) 479 480 # insert things at the necessary indices 481 for i in sorted(inserts, reverse=True): 482 parts[i:i] = [inserts[i]] 483 484 # join all the action items with spaces 485 text = ' '.join([item for item in parts if item is not None]) 486 487 # clean up separators for mutually exclusive groups 488 open = r'[\[(]' 489 close = r'[\])]' 490 text = _re.sub(r'(%s) ' % open, r'\1', text) 491 text = _re.sub(r' (%s)' % close, r'\1', text) 492 text = _re.sub(r'%s *%s' % (open, close), r'', text) 493 text = _re.sub(r'\(([^|]*)\)', r'\1', text) 494 text = text.strip() 495 496 # return the text 497 return text 498 499 def _format_text(self, text): 500 if '%(prog)' in text: 501 text = text % dict(prog=self._prog) 502 text_width = self._width - self._current_indent 503 indent = ' ' * self._current_indent 504 return self._fill_text(text, text_width, indent) + '\n\n' 505 506 def _format_action(self, action): 507 # determine the required width and the entry label 508 help_position = min(self._action_max_length + 2, 509 self._max_help_position) 510 help_width = self._width - help_position 511 action_width = help_position - self._current_indent - 2 512 action_header = self._format_action_invocation(action) 513 514 # ho nelp; start on same line and add a final newline 515 if not action.help: 516 tup = self._current_indent, '', action_header 517 action_header = '%*s%s\n' % tup 518 519 # short action name; start on the same line and pad two spaces 520 elif len(action_header) <= action_width: 521 tup = self._current_indent, '', action_width, action_header 522 action_header = '%*s%-*s ' % tup 523 indent_first = 0 524 525 # long action name; start on the next line 526 else: 527 tup = self._current_indent, '', action_header 528 action_header = '%*s%s\n' % tup 529 indent_first = help_position 530 531 # collect the pieces of the action help 532 parts = [action_header] 533 534 # if there was help for the action, add lines of help text 535 if action.help: 536 help_text = self._expand_help(action) 537 help_lines = self._split_lines(help_text, help_width) 538 parts.append('%*s%s\n' % (indent_first, '', help_lines[0])) 539 for line in help_lines[1:]: 540 parts.append('%*s%s\n' % (help_position, '', line)) 541 542 # or add a newline if the description doesn't end with one 543 elif not action_header.endswith('\n'): 544 parts.append('\n') 545 546 # if there are any sub-actions, add their help as well 547 for subaction in self._iter_indented_subactions(action): 548 parts.append(self._format_action(subaction)) 549 550 # return a single string 551 return self._join_parts(parts) 552 553 def _format_action_invocation(self, action): 554 if not action.option_strings: 555 metavar, = self._metavar_formatter(action, action.dest)(1) 556 return metavar 557 558 else: 559 parts = [] 560 561 # if the Optional doesn't take a value, format is: 562 # -s, --long 563 if action.nargs == 0: 564 parts.extend(action.option_strings) 565 566 # if the Optional takes a value, format is: 567 # -s ARGS, --long ARGS 568 else: 569 default = action.dest.upper() 570 args_string = self._format_args(action, default) 571 for option_string in action.option_strings: 572 parts.append('%s %s' % (option_string, args_string)) 573 574 return ', '.join(parts) 575 576 def _metavar_formatter(self, action, default_metavar): 577 if action.metavar is not None: 578 result = action.metavar 579 elif action.choices is not None: 580 choice_strs = [str(choice) for choice in action.choices] 581 result = '{%s}' % ','.join(choice_strs) 582 else: 583 result = default_metavar 584 585 def format(tuple_size): 586 if isinstance(result, tuple): 587 return result 588 else: 589 return (result, ) * tuple_size 590 return format 591 592 def _format_args(self, action, default_metavar): 593 get_metavar = self._metavar_formatter(action, default_metavar) 594 if action.nargs is None: 595 result = '%s' % get_metavar(1) 596 elif action.nargs == OPTIONAL: 597 result = '[%s]' % get_metavar(1) 598 elif action.nargs == ZERO_OR_MORE: 599 result = '[%s [%s ...]]' % get_metavar(2) 600 elif action.nargs == ONE_OR_MORE: 601 result = '%s [%s ...]' % get_metavar(2) 602 elif action.nargs == REMAINDER: 603 result = '...' 604 elif action.nargs == PARSER: 605 result = '%s ...' % get_metavar(1) 606 else: 607 formats = ['%s' for _ in range(action.nargs)] 608 result = ' '.join(formats) % get_metavar(action.nargs) 609 return result 610 611 def _expand_help(self, action): 612 params = dict(vars(action), prog=self._prog) 613 for name in list(params): 614 if params[name] is SUPPRESS: 615 del params[name] 616 for name in list(params): 617 if hasattr(params[name], '__name__'): 618 params[name] = params[name].__name__ 619 if params.get('choices') is not None: 620 choices_str = ', '.join([str(c) for c in params['choices']]) 621 params['choices'] = choices_str 622 return self._get_help_string(action) % params 623 624 def _iter_indented_subactions(self, action): 625 try: 626 get_subactions = action._get_subactions 627 except AttributeError: 628 pass 629 else: 630 self._indent() 631 for subaction in get_subactions(): 632 yield subaction 633 self._dedent() 634 635 def _split_lines(self, text, width): 636 text = self._whitespace_matcher.sub(' ', text).strip() 637 return _textwrap.wrap(text, width) 638 639 def _fill_text(self, text, width, indent): 640 text = self._whitespace_matcher.sub(' ', text).strip() 641 return _textwrap.fill(text, width, initial_indent=indent, 642 subsequent_indent=indent) 643 644 def _get_help_string(self, action): 645 return action.help 646 647 648class RawDescriptionHelpFormatter(HelpFormatter): 649 """Help message formatter which retains any formatting in descriptions. 650 651 Only the name of this class is considered a public API. All the methods 652 provided by the class are considered an implementation detail. 653 """ 654 655 def _fill_text(self, text, width, indent): 656 return ''.join([indent + line for line in text.splitlines(True)]) 657 658 659class RawTextHelpFormatter(RawDescriptionHelpFormatter): 660 """Help message formatter which retains formatting of all help text. 661 662 Only the name of this class is considered a public API. All the methods 663 provided by the class are considered an implementation detail. 664 """ 665 666 def _split_lines(self, text, width): 667 return text.splitlines() 668 669 670class ArgumentDefaultsHelpFormatter(HelpFormatter): 671 """Help message formatter which adds default values to argument help. 672 673 Only the name of this class is considered a public API. All the methods 674 provided by the class are considered an implementation detail. 675 """ 676 677 def _get_help_string(self, action): 678 help = action.help 679 if '%(default)' not in action.help: 680 if action.default is not SUPPRESS: 681 defaulting_nargs = [OPTIONAL, ZERO_OR_MORE] 682 if action.option_strings or action.nargs in defaulting_nargs: 683 help += ' (default: %(default)s)' 684 return help 685 686 687# ===================== 688# Options and Arguments 689# ===================== 690 691def _get_action_name(argument): 692 if argument is None: 693 return None 694 elif argument.option_strings: 695 return '/'.join(argument.option_strings) 696 elif argument.metavar not in (None, SUPPRESS): 697 return argument.metavar 698 elif argument.dest not in (None, SUPPRESS): 699 return argument.dest 700 else: 701 return None 702 703 704class ArgumentError(Exception): 705 """An error from creating or using an argument (optional or positional). 706 707 The string value of this exception is the message, augmented with 708 information about the argument that caused it. 709 """ 710 711 def __init__(self, argument, message): 712 self.argument_name = _get_action_name(argument) 713 self.message = message 714 715 def __str__(self): 716 if self.argument_name is None: 717 format = '%(message)s' 718 else: 719 format = 'argument %(argument_name)s: %(message)s' 720 return format % dict(message=self.message, 721 argument_name=self.argument_name) 722 723 724class ArgumentTypeError(Exception): 725 """An error from trying to convert a command line string to a type.""" 726 pass 727 728 729# ============== 730# Action classes 731# ============== 732 733class Action(_AttributeHolder): 734 """Information about how to convert command line strings to Python objects. 735 736 Action objects are used by an ArgumentParser to represent the information 737 needed to parse a single argument from one or more strings from the 738 command line. The keyword arguments to the Action constructor are also 739 all attributes of Action instances. 740 741 Keyword Arguments: 742 743 - option_strings -- A list of command-line option strings which 744 should be associated with this action. 745 746 - dest -- The name of the attribute to hold the created object(s) 747 748 - nargs -- The number of command-line arguments that should be 749 consumed. By default, one argument will be consumed and a single 750 value will be produced. Other values include: 751 - N (an integer) consumes N arguments (and produces a list) 752 - '?' consumes zero or one arguments 753 - '*' consumes zero or more arguments (and produces a list) 754 - '+' consumes one or more arguments (and produces a list) 755 Note that the difference between the default and nargs=1 is that 756 with the default, a single value will be produced, while with 757 nargs=1, a list containing a single value will be produced. 758 759 - const -- The value to be produced if the option is specified and the 760 option uses an action that takes no values. 761 762 - default -- The value to be produced if the option is not specified. 763 764 - type -- The type which the command-line arguments should be converted 765 to, should be one of 'string', 'int', 'float', 'complex' or a 766 callable object that accepts a single string argument. If None, 767 'string' is assumed. 768 769 - choices -- A container of values that should be allowed. If not None, 770 after a command-line argument has been converted to the appropriate 771 type, an exception will be raised if it is not a member of this 772 collection. 773 774 - required -- True if the action must always be specified at the 775 command line. This is only meaningful for optional command-line 776 arguments. 777 778 - help -- The help string describing the argument. 779 780 - metavar -- The name to be used for the option's argument with the 781 help string. If None, the 'dest' value will be used as the name. 782 """ 783 784 def __init__(self, 785 option_strings, 786 dest, 787 nargs=None, 788 const=None, 789 default=None, 790 type=None, 791 choices=None, 792 required=False, 793 help=None, 794 metavar=None): 795 self.option_strings = option_strings 796 self.dest = dest 797 self.nargs = nargs 798 self.const = const 799 self.default = default 800 self.type = type 801 self.choices = choices 802 self.required = required 803 self.help = help 804 self.metavar = metavar 805 806 def _get_kwargs(self): 807 names = [ 808 'option_strings', 809 'dest', 810 'nargs', 811 'const', 812 'default', 813 'type', 814 'choices', 815 'help', 816 'metavar', 817 ] 818 return [(name, getattr(self, name)) for name in names] 819 820 def __call__(self, parser, namespace, values, option_string=None): 821 raise NotImplementedError(_('.__call__() not defined')) 822 823 824class _StoreAction(Action): 825 826 def __init__(self, 827 option_strings, 828 dest, 829 nargs=None, 830 const=None, 831 default=None, 832 type=None, 833 choices=None, 834 required=False, 835 help=None, 836 metavar=None): 837 if nargs == 0: 838 raise ValueError('nargs for store actions must be > 0; if you ' 839 'have nothing to store, actions such as store ' 840 'true or store const may be more appropriate') 841 if const is not None and nargs != OPTIONAL: 842 raise ValueError('nargs must be %r to supply const' % OPTIONAL) 843 super(_StoreAction, self).__init__( 844 option_strings=option_strings, 845 dest=dest, 846 nargs=nargs, 847 const=const, 848 default=default, 849 type=type, 850 choices=choices, 851 required=required, 852 help=help, 853 metavar=metavar) 854 855 def __call__(self, parser, namespace, values, option_string=None): 856 setattr(namespace, self.dest, values) 857 858 859class _StoreConstAction(Action): 860 861 def __init__(self, 862 option_strings, 863 dest, 864 const, 865 default=None, 866 required=False, 867 help=None, 868 metavar=None): 869 super(_StoreConstAction, self).__init__( 870 option_strings=option_strings, 871 dest=dest, 872 nargs=0, 873 const=const, 874 default=default, 875 required=required, 876 help=help) 877 878 def __call__(self, parser, namespace, values, option_string=None): 879 setattr(namespace, self.dest, self.const) 880 881 882class _StoreTrueAction(_StoreConstAction): 883 884 def __init__(self, 885 option_strings, 886 dest, 887 default=False, 888 required=False, 889 help=None): 890 super(_StoreTrueAction, self).__init__( 891 option_strings=option_strings, 892 dest=dest, 893 const=True, 894 default=default, 895 required=required, 896 help=help) 897 898 899class _StoreFalseAction(_StoreConstAction): 900 901 def __init__(self, 902 option_strings, 903 dest, 904 default=True, 905 required=False, 906 help=None): 907 super(_StoreFalseAction, self).__init__( 908 option_strings=option_strings, 909 dest=dest, 910 const=False, 911 default=default, 912 required=required, 913 help=help) 914 915 916class _AppendAction(Action): 917 918 def __init__(self, 919 option_strings, 920 dest, 921 nargs=None, 922 const=None, 923 default=None, 924 type=None, 925 choices=None, 926 required=False, 927 help=None, 928 metavar=None): 929 if nargs == 0: 930 raise ValueError('nargs for append actions must be > 0; if arg ' 931 'strings are not supplying the value to append, ' 932 'the append const action may be more appropriate') 933 if const is not None and nargs != OPTIONAL: 934 raise ValueError('nargs must be %r to supply const' % OPTIONAL) 935 super(_AppendAction, self).__init__( 936 option_strings=option_strings, 937 dest=dest, 938 nargs=nargs, 939 const=const, 940 default=default, 941 type=type, 942 choices=choices, 943 required=required, 944 help=help, 945 metavar=metavar) 946 947 def __call__(self, parser, namespace, values, option_string=None): 948 items = _copy.copy(_ensure_value(namespace, self.dest, [])) 949 items.append(values) 950 setattr(namespace, self.dest, items) 951 952 953class _AppendConstAction(Action): 954 955 def __init__(self, 956 option_strings, 957 dest, 958 const, 959 default=None, 960 required=False, 961 help=None, 962 metavar=None): 963 super(_AppendConstAction, self).__init__( 964 option_strings=option_strings, 965 dest=dest, 966 nargs=0, 967 const=const, 968 default=default, 969 required=required, 970 help=help, 971 metavar=metavar) 972 973 def __call__(self, parser, namespace, values, option_string=None): 974 items = _copy.copy(_ensure_value(namespace, self.dest, [])) 975 items.append(self.const) 976 setattr(namespace, self.dest, items) 977 978 979class _CountAction(Action): 980 981 def __init__(self, 982 option_strings, 983 dest, 984 default=None, 985 required=False, 986 help=None): 987 super(_CountAction, self).__init__( 988 option_strings=option_strings, 989 dest=dest, 990 nargs=0, 991 default=default, 992 required=required, 993 help=help) 994 995 def __call__(self, parser, namespace, values, option_string=None): 996 new_count = _ensure_value(namespace, self.dest, 0) + 1 997 setattr(namespace, self.dest, new_count) 998 999 1000class _HelpAction(Action): 1001 1002 def __init__(self, 1003 option_strings, 1004 dest=SUPPRESS, 1005 default=SUPPRESS, 1006 help=None): 1007 super(_HelpAction, self).__init__( 1008 option_strings=option_strings, 1009 dest=dest, 1010 default=default, 1011 nargs=0, 1012 help=help) 1013 1014 def __call__(self, parser, namespace, values, option_string=None): 1015 parser.print_help() 1016 parser.exit() 1017 1018 1019class _VersionAction(Action): 1020 1021 def __init__(self, 1022 option_strings, 1023 version=None, 1024 dest=SUPPRESS, 1025 default=SUPPRESS, 1026 help="show program's version number and exit"): 1027 super(_VersionAction, self).__init__( 1028 option_strings=option_strings, 1029 dest=dest, 1030 default=default, 1031 nargs=0, 1032 help=help) 1033 self.version = version 1034 1035 def __call__(self, parser, namespace, values, option_string=None): 1036 version = self.version 1037 if version is None: 1038 version = parser.version 1039 formatter = parser._get_formatter() 1040 formatter.add_text(version) 1041 parser.exit(message=formatter.format_help()) 1042 1043 1044class _SubParsersAction(Action): 1045 1046 class _ChoicesPseudoAction(Action): 1047 1048 def __init__(self, name, help): 1049 sup = super(_SubParsersAction._ChoicesPseudoAction, self) 1050 sup.__init__(option_strings=[], dest=name, help=help) 1051 1052 def __init__(self, 1053 option_strings, 1054 prog, 1055 parser_class, 1056 dest=SUPPRESS, 1057 help=None, 1058 metavar=None): 1059 1060 self._prog_prefix = prog 1061 self._parser_class = parser_class 1062 self._name_parser_map = {} 1063 self._choices_actions = [] 1064 1065 super(_SubParsersAction, self).__init__( 1066 option_strings=option_strings, 1067 dest=dest, 1068 nargs=PARSER, 1069 choices=self._name_parser_map, 1070 help=help, 1071 metavar=metavar) 1072 1073 def add_parser(self, name, **kwargs): 1074 # set prog from the existing prefix 1075 if kwargs.get('prog') is None: 1076 kwargs['prog'] = '%s %s' % (self._prog_prefix, name) 1077 1078 # create a pseudo-action to hold the choice help 1079 if 'help' in kwargs: 1080 help = kwargs.pop('help') 1081 choice_action = self._ChoicesPseudoAction(name, help) 1082 self._choices_actions.append(choice_action) 1083 1084 # create the parser and add it to the map 1085 parser = self._parser_class(**kwargs) 1086 self._name_parser_map[name] = parser 1087 return parser 1088 1089 def _get_subactions(self): 1090 return self._choices_actions 1091 1092 def __call__(self, parser, namespace, values, option_string=None): 1093 parser_name = values[0] 1094 arg_strings = values[1:] 1095 1096 # set the parser name if requested 1097 if self.dest is not SUPPRESS: 1098 setattr(namespace, self.dest, parser_name) 1099 1100 # select the parser 1101 try: 1102 parser = self._name_parser_map[parser_name] 1103 except KeyError: 1104 tup = parser_name, ', '.join(self._name_parser_map) 1105 msg = _('unknown parser %r (choices: %s)' % tup) 1106 raise ArgumentError(self, msg) 1107 1108 # parse all the remaining options into the namespace 1109 # store any unrecognized options on the object, so that the top 1110 # level parser can decide what to do with them 1111 namespace, arg_strings = parser.parse_known_args(arg_strings, namespace) 1112 if arg_strings: 1113 vars(namespace).setdefault(_UNRECOGNIZED_ARGS_ATTR, []) 1114 getattr(namespace, _UNRECOGNIZED_ARGS_ATTR).extend(arg_strings) 1115 1116 1117# ============== 1118# Type classes 1119# ============== 1120 1121class FileType(object): 1122 """Factory for creating file object types 1123 1124 Instances of FileType are typically passed as type= arguments to the 1125 ArgumentParser add_argument() method. 1126 1127 Keyword Arguments: 1128 - mode -- A string indicating how the file is to be opened. Accepts the 1129 same values as the builtin open() function. 1130 - bufsize -- The file's desired buffer size. Accepts the same values as 1131 the builtin open() function. 1132 """ 1133 1134 def __init__(self, mode='r', bufsize=None): 1135 self._mode = mode 1136 self._bufsize = bufsize 1137 1138 def __call__(self, string): 1139 # the special argument "-" means sys.std{in,out} 1140 if string == '-': 1141 if 'r' in self._mode: 1142 return _sys.stdin 1143 elif 'w' in self._mode: 1144 return _sys.stdout 1145 else: 1146 msg = _('argument "-" with mode %r' % self._mode) 1147 raise ValueError(msg) 1148 1149 # all other arguments are used as file names 1150 if self._bufsize: 1151 return open(string, self._mode, self._bufsize) 1152 else: 1153 return open(string, self._mode) 1154 1155 def __repr__(self): 1156 args = [self._mode, self._bufsize] 1157 args_str = ', '.join([repr(arg) for arg in args if arg is not None]) 1158 return '%s(%s)' % (type(self).__name__, args_str) 1159 1160# =========================== 1161# Optional and Positional Parsing 1162# =========================== 1163 1164class Namespace(_AttributeHolder): 1165 """Simple object for storing attributes. 1166 1167 Implements equality by attribute names and values, and provides a simple 1168 string representation. 1169 """ 1170 1171 def __init__(self, **kwargs): 1172 for name in kwargs: 1173 setattr(self, name, kwargs[name]) 1174 1175 __hash__ = None 1176 1177 def __eq__(self, other): 1178 return vars(self) == vars(other) 1179 1180 def __ne__(self, other): 1181 return not (self == other) 1182 1183 def __contains__(self, key): 1184 return key in self.__dict__ 1185 1186 1187class _ActionsContainer(object): 1188 1189 def __init__(self, 1190 description, 1191 prefix_chars, 1192 argument_default, 1193 conflict_handler): 1194 super(_ActionsContainer, self).__init__() 1195 1196 self.description = description 1197 self.argument_default = argument_default 1198 self.prefix_chars = prefix_chars 1199 self.conflict_handler = conflict_handler 1200 1201 # set up registries 1202 self._registries = {} 1203 1204 # register actions 1205 self.register('action', None, _StoreAction) 1206 self.register('action', 'store', _StoreAction) 1207 self.register('action', 'store_const', _StoreConstAction) 1208 self.register('action', 'store_true', _StoreTrueAction) 1209 self.register('action', 'store_false', _StoreFalseAction) 1210 self.register('action', 'append', _AppendAction) 1211 self.register('action', 'append_const', _AppendConstAction) 1212 self.register('action', 'count', _CountAction) 1213 self.register('action', 'help', _HelpAction) 1214 self.register('action', 'version', _VersionAction) 1215 self.register('action', 'parsers', _SubParsersAction) 1216 1217 # raise an exception if the conflict handler is invalid 1218 self._get_handler() 1219 1220 # action storage 1221 self._actions = [] 1222 self._option_string_actions = {} 1223 1224 # groups 1225 self._action_groups = [] 1226 self._mutually_exclusive_groups = [] 1227 1228 # defaults storage 1229 self._defaults = {} 1230 1231 # determines whether an "option" looks like a negative number 1232 self._negative_number_matcher = _re.compile(r'^-\d+$|^-\d*\.\d+$') 1233 1234 # whether or not there are any optionals that look like negative 1235 # numbers -- uses a list so it can be shared and edited 1236 self._has_negative_number_optionals = [] 1237 1238 # ==================== 1239 # Registration methods 1240 # ==================== 1241 def register(self, registry_name, value, object): 1242 registry = self._registries.setdefault(registry_name, {}) 1243 registry[value] = object 1244 1245 def _registry_get(self, registry_name, value, default=None): 1246 return self._registries[registry_name].get(value, default) 1247 1248 # ================================== 1249 # Namespace default accessor methods 1250 # ================================== 1251 def set_defaults(self, **kwargs): 1252 self._defaults.update(kwargs) 1253 1254 # if these defaults match any existing arguments, replace 1255 # the previous default on the object with the new one 1256 for action in self._actions: 1257 if action.dest in kwargs: 1258 action.default = kwargs[action.dest] 1259 1260 def get_default(self, dest): 1261 for action in self._actions: 1262 if action.dest == dest and action.default is not None: 1263 return action.default 1264 return self._defaults.get(dest, None) 1265 1266 1267 # ======================= 1268 # Adding argument actions 1269 # ======================= 1270 def add_argument(self, *args, **kwargs): 1271 """ 1272 add_argument(dest, ..., name=value, ...) 1273 add_argument(option_string, option_string, ..., name=value, ...) 1274 """ 1275 1276 # if no positional args are supplied or only one is supplied and 1277 # it doesn't look like an option string, parse a positional 1278 # argument 1279 chars = self.prefix_chars 1280 if not args or len(args) == 1 and args[0][0] not in chars: 1281 if args and 'dest' in kwargs: 1282 raise ValueError('dest supplied twice for positional argument') 1283 kwargs = self._get_positional_kwargs(*args, **kwargs) 1284 1285 # otherwise, we're adding an optional argument 1286 else: 1287 kwargs = self._get_optional_kwargs(*args, **kwargs) 1288 1289 # if no default was supplied, use the parser-level default 1290 if 'default' not in kwargs: 1291 dest = kwargs['dest'] 1292 if dest in self._defaults: 1293 kwargs['default'] = self._defaults[dest] 1294 elif self.argument_default is not None: 1295 kwargs['default'] = self.argument_default 1296 1297 # create the action object, and add it to the parser 1298 action_class = self._pop_action_class(kwargs) 1299 if not _callable(action_class): 1300 raise ValueError('unknown action "%s"' % action_class) 1301 action = action_class(**kwargs) 1302 1303 # raise an error if the action type is not callable 1304 type_func = self._registry_get('type', action.type, action.type) 1305 if not _callable(type_func): 1306 raise ValueError('%r is not callable' % type_func) 1307 1308 return self._add_action(action) 1309 1310 def add_argument_group(self, *args, **kwargs): 1311 group = _ArgumentGroup(self, *args, **kwargs) 1312 self._action_groups.append(group) 1313 return group 1314 1315 def add_mutually_exclusive_group(self, **kwargs): 1316 group = _MutuallyExclusiveGroup(self, **kwargs) 1317 self._mutually_exclusive_groups.append(group) 1318 return group 1319 1320 def _add_action(self, action): 1321 # resolve any conflicts 1322 self._check_conflict(action) 1323 1324 # add to actions list 1325 self._actions.append(action) 1326 action.container = self 1327 1328 # index the action by any option strings it has 1329 for option_string in action.option_strings: 1330 self._option_string_actions[option_string] = action 1331 1332 # set the flag if any option strings look like negative numbers 1333 for option_string in action.option_strings: 1334 if self._negative_number_matcher.match(option_string): 1335 if not self._has_negative_number_optionals: 1336 self._has_negative_number_optionals.append(True) 1337 1338 # return the created action 1339 return action 1340 1341 def _remove_action(self, action): 1342 self._actions.remove(action) 1343 1344 def _add_container_actions(self, container): 1345 # collect groups by titles 1346 title_group_map = {} 1347 for group in self._action_groups: 1348 if group.title in title_group_map: 1349 msg = _('cannot merge actions - two groups are named %r') 1350 raise ValueError(msg % (group.title)) 1351 title_group_map[group.title] = group 1352 1353 # map each action to its group 1354 group_map = {} 1355 for group in container._action_groups: 1356 1357 # if a group with the title exists, use that, otherwise 1358 # create a new group matching the container's group 1359 if group.title not in title_group_map: 1360 title_group_map[group.title] = self.add_argument_group( 1361 title=group.title, 1362 description=group.description, 1363 conflict_handler=group.conflict_handler) 1364 1365 # map the actions to their new group 1366 for action in group._group_actions: 1367 group_map[action] = title_group_map[group.title] 1368 1369 # add container's mutually exclusive groups 1370 # NOTE: if add_mutually_exclusive_group ever gains title= and 1371 # description= then this code will need to be expanded as above 1372 for group in container._mutually_exclusive_groups: 1373 mutex_group = self.add_mutually_exclusive_group( 1374 required=group.required) 1375 1376 # map the actions to their new mutex group 1377 for action in group._group_actions: 1378 group_map[action] = mutex_group 1379 1380 # add all actions to this container or their group 1381 for action in container._actions: 1382 group_map.get(action, self)._add_action(action) 1383 1384 def _get_positional_kwargs(self, dest, **kwargs): 1385 # make sure required is not specified 1386 if 'required' in kwargs: 1387 msg = _("'required' is an invalid argument for positionals") 1388 raise TypeError(msg) 1389 1390 # mark positional arguments as required if at least one is 1391 # always required 1392 if kwargs.get('nargs') not in [OPTIONAL, ZERO_OR_MORE]: 1393 kwargs['required'] = True 1394 if kwargs.get('nargs') == ZERO_OR_MORE and 'default' not in kwargs: 1395 kwargs['required'] = True 1396 1397 # return the keyword arguments with no option strings 1398 return dict(kwargs, dest=dest, option_strings=[]) 1399 1400 def _get_optional_kwargs(self, *args, **kwargs): 1401 # determine short and long option strings 1402 option_strings = [] 1403 long_option_strings = [] 1404 for option_string in args: 1405 # error on strings that don't start with an appropriate prefix 1406 if not option_string[0] in self.prefix_chars: 1407 msg = _('invalid option string %r: ' 1408 'must start with a character %r') 1409 tup = option_string, self.prefix_chars 1410 raise ValueError(msg % tup) 1411 1412 # strings starting with two prefix characters are long options 1413 option_strings.append(option_string) 1414 if option_string[0] in self.prefix_chars: 1415 if len(option_string) > 1: 1416 if option_string[1] in self.prefix_chars: 1417 long_option_strings.append(option_string) 1418 1419 # infer destination, '--foo-bar' -> 'foo_bar' and '-x' -> 'x' 1420 dest = kwargs.pop('dest', None) 1421 if dest is None: 1422 if long_option_strings: 1423 dest_option_string = long_option_strings[0] 1424 else: 1425 dest_option_string = option_strings[0] 1426 dest = dest_option_string.lstrip(self.prefix_chars) 1427 if not dest: 1428 msg = _('dest= is required for options like %r') 1429 raise ValueError(msg % option_string) 1430 dest = dest.replace('-', '_') 1431 1432 # return the updated keyword arguments 1433 return dict(kwargs, dest=dest, option_strings=option_strings) 1434 1435 def _pop_action_class(self, kwargs, default=None): 1436 action = kwargs.pop('action', default) 1437 return self._registry_get('action', action, action) 1438 1439 def _get_handler(self): 1440 # determine function from conflict handler string 1441 handler_func_name = '_handle_conflict_%s' % self.conflict_handler 1442 try: 1443 return getattr(self, handler_func_name) 1444 except AttributeError: 1445 msg = _('invalid conflict_resolution value: %r') 1446 raise ValueError(msg % self.conflict_handler) 1447 1448 def _check_conflict(self, action): 1449 1450 # find all options that conflict with this option 1451 confl_optionals = [] 1452 for option_string in action.option_strings: 1453 if option_string in self._option_string_actions: 1454 confl_optional = self._option_string_actions[option_string] 1455 confl_optionals.append((option_string, confl_optional)) 1456 1457 # resolve any conflicts 1458 if confl_optionals: 1459 conflict_handler = self._get_handler() 1460 conflict_handler(action, confl_optionals) 1461 1462 def _handle_conflict_error(self, action, conflicting_actions): 1463 message = _('conflicting option string(s): %s') 1464 conflict_string = ', '.join([option_string 1465 for option_string, action 1466 in conflicting_actions]) 1467 raise ArgumentError(action, message % conflict_string) 1468 1469 def _handle_conflict_resolve(self, action, conflicting_actions): 1470 1471 # remove all conflicting options 1472 for option_string, action in conflicting_actions: 1473 1474 # remove the conflicting option 1475 action.option_strings.remove(option_string) 1476 self._option_string_actions.pop(option_string, None) 1477 1478 # if the option now has no option string, remove it from the 1479 # container holding it 1480 if not action.option_strings: 1481 action.container._remove_action(action) 1482 1483 1484class _ArgumentGroup(_ActionsContainer): 1485 1486 def __init__(self, container, title=None, description=None, **kwargs): 1487 # add any missing keyword arguments by checking the container 1488 update = kwargs.setdefault 1489 update('conflict_handler', container.conflict_handler) 1490 update('prefix_chars', container.prefix_chars) 1491 update('argument_default', container.argument_default) 1492 super_init = super(_ArgumentGroup, self).__init__ 1493 super_init(description=description, **kwargs) 1494 1495 # group attributes 1496 self.title = title 1497 self._group_actions = [] 1498 1499 # share most attributes with the container 1500 self._registries = container._registries 1501 self._actions = container._actions 1502 self._option_string_actions = container._option_string_actions 1503 self._defaults = container._defaults 1504 self._has_negative_number_optionals = \ 1505 container._has_negative_number_optionals 1506 1507 def _add_action(self, action): 1508 action = super(_ArgumentGroup, self)._add_action(action) 1509 self._group_actions.append(action) 1510 return action 1511 1512 def _remove_action(self, action): 1513 super(_ArgumentGroup, self)._remove_action(action) 1514 self._group_actions.remove(action) 1515 1516 1517class _MutuallyExclusiveGroup(_ArgumentGroup): 1518 1519 def __init__(self, container, required=False): 1520 super(_MutuallyExclusiveGroup, self).__init__(container) 1521 self.required = required 1522 self._container = container 1523 1524 def _add_action(self, action): 1525 if action.required: 1526 msg = _('mutually exclusive arguments must be optional') 1527 raise ValueError(msg) 1528 action = self._container._add_action(action) 1529 self._group_actions.append(action) 1530 return action 1531 1532 def _remove_action(self, action): 1533 self._container._remove_action(action) 1534 self._group_actions.remove(action) 1535 1536 1537class ArgumentParser(_AttributeHolder, _ActionsContainer): 1538 """Object for parsing command line strings into Python objects. 1539 1540 Keyword Arguments: 1541 - prog -- The name of the program (default: sys.argv[0]) 1542 - usage -- A usage message (default: auto-generated from arguments) 1543 - description -- A description of what the program does 1544 - epilog -- Text following the argument descriptions 1545 - parents -- Parsers whose arguments should be copied into this one 1546 - formatter_class -- HelpFormatter class for printing help messages 1547 - prefix_chars -- Characters that prefix optional arguments 1548 - fromfile_prefix_chars -- Characters that prefix files containing 1549 additional arguments 1550 - argument_default -- The default value for all arguments 1551 - conflict_handler -- String indicating how to handle conflicts 1552 - add_help -- Add a -h/-help option 1553 """ 1554 1555 def __init__(self, 1556 prog=None, 1557 usage=None, 1558 description=None, 1559 epilog=None, 1560 version=None, 1561 parents=[], 1562 formatter_class=HelpFormatter, 1563 prefix_chars='-', 1564 fromfile_prefix_chars=None, 1565 argument_default=None, 1566 conflict_handler='error', 1567 add_help=True): 1568 1569 if version is not None: 1570 import warnings 1571 warnings.warn( 1572 """The "version" argument to ArgumentParser is deprecated. """ 1573 """Please use """ 1574 """"add_argument(..., action='version', version="N", ...)" """ 1575 """instead""", DeprecationWarning) 1576 1577 superinit = super(ArgumentParser, self).__init__ 1578 superinit(description=description, 1579 prefix_chars=prefix_chars, 1580 argument_default=argument_default, 1581 conflict_handler=conflict_handler) 1582 1583 # default setting for prog 1584 if prog is None: 1585 prog = _os.path.basename(_sys.argv[0]) 1586 1587 self.prog = prog 1588 self.usage = usage 1589 self.epilog = epilog 1590 self.version = version 1591 self.formatter_class = formatter_class 1592 self.fromfile_prefix_chars = fromfile_prefix_chars 1593 self.add_help = add_help 1594 1595 add_group = self.add_argument_group 1596 self._positionals = add_group(_('positional arguments')) 1597 self._optionals = add_group(_('optional arguments')) 1598 self._subparsers = None 1599 1600 # register types 1601 def identity(string): 1602 return string 1603 self.register('type', None, identity) 1604 1605 # add help and version arguments if necessary 1606 # (using explicit default to override global argument_default) 1607 if '-' in prefix_chars: 1608 default_prefix = '-' 1609 else: 1610 default_prefix = prefix_chars[0] 1611 if self.add_help: 1612 self.add_argument( 1613 default_prefix+'h', default_prefix*2+'help', 1614 action='help', default=SUPPRESS, 1615 help=_('show this help message and exit')) 1616 if self.version: 1617 self.add_argument( 1618 default_prefix+'v', default_prefix*2+'version', 1619 action='version', default=SUPPRESS, 1620 version=self.version, 1621 help=_("show program's version number and exit")) 1622 1623 # add parent arguments and defaults 1624 for parent in parents: 1625 self._add_container_actions(parent) 1626 try: 1627 defaults = parent._defaults 1628 except AttributeError: 1629 pass 1630 else: 1631 self._defaults.update(defaults) 1632 1633 # ======================= 1634 # Pretty __repr__ methods 1635 # ======================= 1636 def _get_kwargs(self): 1637 names = [ 1638 'prog', 1639 'usage', 1640 'description', 1641 'version', 1642 'formatter_class', 1643 'conflict_handler', 1644 'add_help', 1645 ] 1646 return [(name, getattr(self, name)) for name in names] 1647 1648 # ================================== 1649 # Optional/Positional adding methods 1650 # ================================== 1651 def add_subparsers(self, **kwargs): 1652 if self._subparsers is not None: 1653 self.error(_('cannot have multiple subparser arguments')) 1654 1655 # add the parser class to the arguments if it's not present 1656 kwargs.setdefault('parser_class', type(self)) 1657 1658 if 'title' in kwargs or 'description' in kwargs: 1659 title = _(kwargs.pop('title', 'subcommands')) 1660 description = _(kwargs.pop('description', None)) 1661 self._subparsers = self.add_argument_group(title, description) 1662 else: 1663 self._subparsers = self._positionals 1664 1665 # prog defaults to the usage message of this parser, skipping 1666 # optional arguments and with no "usage:" prefix 1667 if kwargs.get('prog') is None: 1668 formatter = self._get_formatter() 1669 positionals = self._get_positional_actions() 1670 groups = self._mutually_exclusive_groups 1671 formatter.add_usage(self.usage, positionals, groups, '') 1672 kwargs['prog'] = formatter.format_help().strip() 1673 1674 # create the parsers action and add it to the positionals list 1675 parsers_class = self._pop_action_class(kwargs, 'parsers') 1676 action = parsers_class(option_strings=[], **kwargs) 1677 self._subparsers._add_action(action) 1678 1679 # return the created parsers action 1680 return action 1681 1682 def _add_action(self, action): 1683 if action.option_strings: 1684 self._optionals._add_action(action) 1685 else: 1686 self._positionals._add_action(action) 1687 return action 1688 1689 def _get_optional_actions(self): 1690 return [action 1691 for action in self._actions 1692 if action.option_strings] 1693 1694 def _get_positional_actions(self): 1695 return [action 1696 for action in self._actions 1697 if not action.option_strings] 1698 1699 # ===================================== 1700 # Command line argument parsing methods 1701 # ===================================== 1702 def parse_args(self, args=None, namespace=None): 1703 args, argv = self.parse_known_args(args, namespace) 1704 if argv: 1705 msg = _('unrecognized arguments: %s') 1706 self.error(msg % ' '.join(argv)) 1707 return args 1708 1709 def parse_known_args(self, args=None, namespace=None): 1710 # args default to the system args 1711 if args is None: 1712 args = _sys.argv[1:] 1713 1714 # default Namespace built from parser defaults 1715 if namespace is None: 1716 namespace = Namespace() 1717 1718 # add any action defaults that aren't present 1719 for action in self._actions: 1720 if action.dest is not SUPPRESS: 1721 if not hasattr(namespace, action.dest): 1722 if action.default is not SUPPRESS: 1723 default = action.default 1724 if isinstance(action.default, basestring): 1725 default = self._get_value(action, default) 1726 setattr(namespace, action.dest, default) 1727 1728 # add any parser defaults that aren't present 1729 for dest in self._defaults: 1730 if not hasattr(namespace, dest): 1731 setattr(namespace, dest, self._defaults[dest]) 1732 1733 # parse the arguments and exit if there are any errors 1734 try: 1735 namespace, args = self._parse_known_args(args, namespace) 1736 if hasattr(namespace, _UNRECOGNIZED_ARGS_ATTR): 1737 args.extend(getattr(namespace, _UNRECOGNIZED_ARGS_ATTR)) 1738 delattr(namespace, _UNRECOGNIZED_ARGS_ATTR) 1739 return namespace, args 1740 except ArgumentError: 1741 err = _sys.exc_info()[1] 1742 self.error(str(err)) 1743 1744 def _parse_known_args(self, arg_strings, namespace): 1745 # replace arg strings that are file references 1746 if self.fromfile_prefix_chars is not None: 1747 arg_strings = self._read_args_from_files(arg_strings) 1748 1749 # map all mutually exclusive arguments to the other arguments 1750 # they can't occur with 1751 action_conflicts = {} 1752 for mutex_group in self._mutually_exclusive_groups: 1753 group_actions = mutex_group._group_actions 1754 for i, mutex_action in enumerate(mutex_group._group_actions): 1755 conflicts = action_conflicts.setdefault(mutex_action, []) 1756 conflicts.extend(group_actions[:i]) 1757 conflicts.extend(group_actions[i + 1:]) 1758 1759 # find all option indices, and determine the arg_string_pattern 1760 # which has an 'O' if there is an option at an index, 1761 # an 'A' if there is an argument, or a '-' if there is a '--' 1762 option_string_indices = {} 1763 arg_string_pattern_parts = [] 1764 arg_strings_iter = iter(arg_strings) 1765 for i, arg_string in enumerate(arg_strings_iter): 1766 1767 # all args after -- are non-options 1768 if arg_string == '--': 1769 arg_string_pattern_parts.append('-') 1770 for arg_string in arg_strings_iter: 1771 arg_string_pattern_parts.append('A') 1772 1773 # otherwise, add the arg to the arg strings 1774 # and note the index if it was an option 1775 else: 1776 option_tuple = self._parse_optional(arg_string) 1777 if option_tuple is None: 1778 pattern = 'A' 1779 else: 1780 option_string_indices[i] = option_tuple 1781 pattern = 'O' 1782 arg_string_pattern_parts.append(pattern) 1783 1784 # join the pieces together to form the pattern 1785 arg_strings_pattern = ''.join(arg_string_pattern_parts) 1786 1787 # converts arg strings to the appropriate and then takes the action 1788 seen_actions = set() 1789 seen_non_default_actions = set() 1790 1791 def take_action(action, argument_strings, option_string=None): 1792 seen_actions.add(action) 1793 argument_values = self._get_values(action, argument_strings) 1794 1795 # error if this argument is not allowed with other previously 1796 # seen arguments, assuming that actions that use the default 1797 # value don't really count as "present" 1798 if argument_values is not action.default: 1799 seen_non_default_actions.add(action) 1800 for conflict_action in action_conflicts.get(action, []): 1801 if conflict_action in seen_non_default_actions: 1802 msg = _('not allowed with argument %s') 1803 action_name = _get_action_name(conflict_action) 1804 raise ArgumentError(action, msg % action_name) 1805 1806 # take the action if we didn't receive a SUPPRESS value 1807 # (e.g. from a default) 1808 if argument_values is not SUPPRESS: 1809 action(self, namespace, argument_values, option_string) 1810 1811 # function to convert arg_strings into an optional action 1812 def consume_optional(start_index): 1813 1814 # get the optional identified at this index 1815 option_tuple = option_string_indices[start_index] 1816 action, option_string, explicit_arg = option_tuple 1817 1818 # identify additional optionals in the same arg string 1819 # (e.g. -xyz is the same as -x -y -z if no args are required) 1820 match_argument = self._match_argument 1821 action_tuples = [] 1822 while True: 1823 1824 # if we found no optional action, skip it 1825 if action is None: 1826 extras.append(arg_strings[start_index]) 1827 return start_index + 1 1828 1829 # if there is an explicit argument, try to match the 1830 # optional's string arguments to only this 1831 if explicit_arg is not None: 1832 arg_count = match_argument(action, 'A') 1833 1834 # if the action is a single-dash option and takes no 1835 # arguments, try to parse more single-dash options out 1836 # of the tail of the option string 1837 chars = self.prefix_chars 1838 if arg_count == 0 and option_string[1] not in chars: 1839 action_tuples.append((action, [], option_string)) 1840 char = option_string[0] 1841 option_string = char + explicit_arg[0] 1842 new_explicit_arg = explicit_arg[1:] or None 1843 optionals_map = self._option_string_actions 1844 if option_string in optionals_map: 1845 action = optionals_map[option_string] 1846 explicit_arg = new_explicit_arg 1847 else: 1848 msg = _('ignored explicit argument %r') 1849 raise ArgumentError(action, msg % explicit_arg) 1850 1851 # if the action expect exactly one argument, we've 1852 # successfully matched the option; exit the loop 1853 elif arg_count == 1: 1854 stop = start_index + 1 1855 args = [explicit_arg] 1856 action_tuples.append((action, args, option_string)) 1857 break 1858 1859 # error if a double-dash option did not use the 1860 # explicit argument 1861 else: 1862 msg = _('ignored explicit argument %r') 1863 raise ArgumentError(action, msg % explicit_arg) 1864 1865 # if there is no explicit argument, try to match the 1866 # optional's string arguments with the following strings 1867 # if successful, exit the loop 1868 else: 1869 start = start_index + 1 1870 selected_patterns = arg_strings_pattern[start:] 1871 arg_count = match_argument(action, selected_patterns) 1872 stop = start + arg_count 1873 args = arg_strings[start:stop] 1874 action_tuples.append((action, args, option_string)) 1875 break 1876 1877 # add the Optional to the list and return the index at which 1878 # the Optional's string args stopped 1879 assert action_tuples 1880 for action, args, option_string in action_tuples: 1881 take_action(action, args, option_string) 1882 return stop 1883 1884 # the list of Positionals left to be parsed; this is modified 1885 # by consume_positionals() 1886 positionals = self._get_positional_actions() 1887 1888 # function to convert arg_strings into positional actions 1889 def consume_positionals(start_index): 1890 # match as many Positionals as possible 1891 match_partial = self._match_arguments_partial 1892 selected_pattern = arg_strings_pattern[start_index:] 1893 arg_counts = match_partial(positionals, selected_pattern) 1894 1895 # slice off the appropriate arg strings for each Positional 1896 # and add the Positional and its args to the list 1897 for action, arg_count in zip(positionals, arg_counts): 1898 args = arg_strings[start_index: start_index + arg_count] 1899 start_index += arg_count 1900 take_action(action, args) 1901 1902 # slice off the Positionals that we just parsed and return the 1903 # index at which the Positionals' string args stopped 1904 positionals[:] = positionals[len(arg_counts):] 1905 return start_index 1906 1907 # consume Positionals and Optionals alternately, until we have 1908 # passed the last option string 1909 extras = [] 1910 start_index = 0 1911 if option_string_indices: 1912 max_option_string_index = max(option_string_indices) 1913 else: 1914 max_option_string_index = -1 1915 while start_index <= max_option_string_index: 1916 1917 # consume any Positionals preceding the next option 1918 next_option_string_index = min([ 1919 index 1920 for index in option_string_indices 1921 if index >= start_index]) 1922 if start_index != next_option_string_index: 1923 positionals_end_index = consume_positionals(start_index) 1924 1925 # only try to parse the next optional if we didn't consume 1926 # the option string during the positionals parsing 1927 if positionals_end_index > start_index: 1928 start_index = positionals_end_index 1929 continue 1930 else: 1931 start_index = positionals_end_index 1932 1933 # if we consumed all the positionals we could and we're not 1934 # at the index of an option string, there were extra arguments 1935 if start_index not in option_string_indices: 1936 strings = arg_strings[start_index:next_option_string_index] 1937 extras.extend(strings) 1938 start_index = next_option_string_index 1939 1940 # consume the next optional and any arguments for it 1941 start_index = consume_optional(start_index) 1942 1943 # consume any positionals following the last Optional 1944 stop_index = consume_positionals(start_index) 1945 1946 # if we didn't consume all the argument strings, there were extras 1947 extras.extend(arg_strings[stop_index:]) 1948 1949 # if we didn't use all the Positional objects, there were too few 1950 # arg strings supplied. 1951 if positionals: 1952 self.error(_('too few arguments')) 1953 1954 # make sure all required actions were present 1955 for action in self._actions: 1956 if action.required: 1957 if action not in seen_actions: 1958 name = _get_action_name(action) 1959 self.error(_('argument %s is required') % name) 1960 1961 # make sure all required groups had one option present 1962 for group in self._mutually_exclusive_groups: 1963 if group.required: 1964 for action in group._group_actions: 1965 if action in seen_non_default_actions: 1966 break 1967 1968 # if no actions were used, report the error 1969 else: 1970 names = [_get_action_name(action) 1971 for action in group._group_actions 1972 if action.help is not SUPPRESS] 1973 msg = _('one of the arguments %s is required') 1974 self.error(msg % ' '.join(names)) 1975 1976 # return the updated namespace and the extra arguments 1977 return namespace, extras 1978 1979 def _read_args_from_files(self, arg_strings): 1980 # expand arguments referencing files 1981 new_arg_strings = [] 1982 for arg_string in arg_strings: 1983 1984 # for regular arguments, just add them back into the list 1985 if arg_string[0] not in self.fromfile_prefix_chars: 1986 new_arg_strings.append(arg_string) 1987 1988 # replace arguments referencing files with the file content 1989 else: 1990 try: 1991 args_file = open(arg_string[1:]) 1992 try: 1993 arg_strings = [] 1994 for arg_line in args_file.read().splitlines(): 1995 for arg in self.convert_arg_line_to_args(arg_line): 1996 arg_strings.append(arg) 1997 arg_strings = self._read_args_from_files(arg_strings) 1998 new_arg_strings.extend(arg_strings) 1999 finally: 2000 args_file.close() 2001 except IOError: 2002 err = _sys.exc_info()[1] 2003 self.error(str(err)) 2004 2005 # return the modified argument list 2006 return new_arg_strings 2007 2008 def convert_arg_line_to_args(self, arg_line): 2009 return [arg_line] 2010 2011 def _match_argument(self, action, arg_strings_pattern): 2012 # match the pattern for this action to the arg strings 2013 nargs_pattern = self._get_nargs_pattern(action) 2014 match = _re.match(nargs_pattern, arg_strings_pattern) 2015 2016 # raise an exception if we weren't able to find a match 2017 if match is None: 2018 nargs_errors = { 2019 None: _('expected one argument'), 2020 OPTIONAL: _('expected at most one argument'), 2021 ONE_OR_MORE: _('expected at least one argument'), 2022 } 2023 default = _('expected %s argument(s)') % action.nargs 2024 msg = nargs_errors.get(action.nargs, default) 2025 raise ArgumentError(action, msg) 2026 2027 # return the number of arguments matched 2028 return len(match.group(1)) 2029 2030 def _match_arguments_partial(self, actions, arg_strings_pattern): 2031 # progressively shorten the actions list by slicing off the 2032 # final actions until we find a match 2033 result = [] 2034 for i in range(len(actions), 0, -1): 2035 actions_slice = actions[:i] 2036 pattern = ''.join([self._get_nargs_pattern(action) 2037 for action in actions_slice]) 2038 match = _re.match(pattern, arg_strings_pattern) 2039 if match is not None: 2040 result.extend([len(string) for string in match.groups()]) 2041 break 2042 2043 # return the list of arg string counts 2044 return result 2045 2046 def _parse_optional(self, arg_string): 2047 # if it's an empty string, it was meant to be a positional 2048 if not arg_string: 2049 return None 2050 2051 # if it doesn't start with a prefix, it was meant to be positional 2052 if not arg_string[0] in self.prefix_chars: 2053 return None 2054 2055 # if the option string is present in the parser, return the action 2056 if arg_string in self._option_string_actions: 2057 action = self._option_string_actions[arg_string] 2058 return action, arg_string, None 2059 2060 # if it's just a single character, it was meant to be positional 2061 if len(arg_string) == 1: 2062 return None 2063 2064 # if the option string before the "=" is present, return the action 2065 if '=' in arg_string: 2066 option_string, explicit_arg = arg_string.split('=', 1) 2067 if option_string in self._option_string_actions: 2068 action = self._option_string_actions[option_string] 2069 return action, option_string, explicit_arg 2070 2071 # search through all possible prefixes of the option string 2072 # and all actions in the parser for possible interpretations 2073 option_tuples = self._get_option_tuples(arg_string) 2074 2075 # if multiple actions match, the option string was ambiguous 2076 if len(option_tuples) > 1: 2077 options = ', '.join([option_string 2078 for action, option_string, explicit_arg in option_tuples]) 2079 tup = arg_string, options 2080 self.error(_('ambiguous option: %s could match %s') % tup) 2081 2082 # if exactly one action matched, this segmentation is good, 2083 # so return the parsed action 2084 elif len(option_tuples) == 1: 2085 option_tuple, = option_tuples 2086 return option_tuple 2087 2088 # if it was not found as an option, but it looks like a negative 2089 # number, it was meant to be positional 2090 # unless there are negative-number-like options 2091 if self._negative_number_matcher.match(arg_string): 2092 if not self._has_negative_number_optionals: 2093 return None 2094 2095 # if it contains a space, it was meant to be a positional 2096 if ' ' in arg_string: 2097 return None 2098 2099 # it was meant to be an optional but there is no such option 2100 # in this parser (though it might be a valid option in a subparser) 2101 return None, arg_string, None 2102 2103 def _get_option_tuples(self, option_string): 2104 result = [] 2105 2106 # option strings starting with two prefix characters are only 2107 # split at the '=' 2108 chars = self.prefix_chars 2109 if option_string[0] in chars and option_string[1] in chars: 2110 if '=' in option_string: 2111 option_prefix, explicit_arg = option_string.split('=', 1) 2112 else: 2113 option_prefix = option_string 2114 explicit_arg = None 2115 for option_string in self._option_string_actions: 2116 if option_string.startswith(option_prefix): 2117 action = self._option_string_actions[option_string] 2118 tup = action, option_string, explicit_arg 2119 result.append(tup) 2120 2121 # single character options can be concatenated with their arguments 2122 # but multiple character options always have to have their argument 2123 # separate 2124 elif option_string[0] in chars and option_string[1] not in chars: 2125 option_prefix = option_string 2126 explicit_arg = None 2127 short_option_prefix = option_string[:2] 2128 short_explicit_arg = option_string[2:] 2129 2130 for option_string in self._option_string_actions: 2131 if option_string == short_option_prefix: 2132 action = self._option_string_actions[option_string] 2133 tup = action, option_string, short_explicit_arg 2134 result.append(tup) 2135 elif option_string.startswith(option_prefix): 2136 action = self._option_string_actions[option_string] 2137 tup = action, option_string, explicit_arg 2138 result.append(tup) 2139 2140 # shouldn't ever get here 2141 else: 2142 self.error(_('unexpected option string: %s') % option_string) 2143 2144 # return the collected option tuples 2145 return result 2146 2147 def _get_nargs_pattern(self, action): 2148 # in all examples below, we have to allow for '--' args 2149 # which are represented as '-' in the pattern 2150 nargs = action.nargs 2151 2152 # the default (None) is assumed to be a single argument 2153 if nargs is None: 2154 nargs_pattern = '(-*A-*)' 2155 2156 # allow zero or one arguments 2157 elif nargs == OPTIONAL: 2158 nargs_pattern = '(-*A?-*)' 2159 2160 # allow zero or more arguments 2161 elif nargs == ZERO_OR_MORE: 2162 nargs_pattern = '(-*[A-]*)' 2163 2164 # allow one or more arguments 2165 elif nargs == ONE_OR_MORE: 2166 nargs_pattern = '(-*A[A-]*)' 2167 2168 # allow any number of options or arguments 2169 elif nargs == REMAINDER: 2170 nargs_pattern = '([-AO]*)' 2171 2172 # allow one argument followed by any number of options or arguments 2173 elif nargs == PARSER: 2174 nargs_pattern = '(-*A[-AO]*)' 2175 2176 # all others should be integers 2177 else: 2178 nargs_pattern = '(-*%s-*)' % '-*'.join('A' * nargs) 2179 2180 # if this is an optional action, -- is not allowed 2181 if action.option_strings: 2182 nargs_pattern = nargs_pattern.replace('-*', '') 2183 nargs_pattern = nargs_pattern.replace('-', '') 2184 2185 # return the pattern 2186 return nargs_pattern 2187 2188 # ======================== 2189 # Value conversion methods 2190 # ======================== 2191 def _get_values(self, action, arg_strings): 2192 # for everything but PARSER args, strip out '--' 2193 if action.nargs not in [PARSER, REMAINDER]: 2194 arg_strings = [s for s in arg_strings if s != '--'] 2195 2196 # optional argument produces a default when not present 2197 if not arg_strings and action.nargs == OPTIONAL: 2198 if action.option_strings: 2199 value = action.const 2200 else: 2201 value = action.default 2202 if isinstance(value, basestring): 2203 value = self._get_value(action, value) 2204 self._check_value(action, value) 2205 2206 # when nargs='*' on a positional, if there were no command-line 2207 # args, use the default if it is anything other than None 2208 elif (not arg_strings and action.nargs == ZERO_OR_MORE and 2209 not action.option_strings): 2210 if action.default is not None: 2211 value = action.default 2212 else: 2213 value = arg_strings 2214 self._check_value(action, value) 2215 2216 # single argument or optional argument produces a single value 2217 elif len(arg_strings) == 1 and action.nargs in [None, OPTIONAL]: 2218 arg_string, = arg_strings 2219 value = self._get_value(action, arg_string) 2220 self._check_value(action, value) 2221 2222 # REMAINDER arguments convert all values, checking none 2223 elif action.nargs == REMAINDER: 2224 value = [self._get_value(action, v) for v in arg_strings] 2225 2226 # PARSER arguments convert all values, but check only the first 2227 elif action.nargs == PARSER: 2228 value = [self._get_value(action, v) for v in arg_strings] 2229 self._check_value(action, value[0]) 2230 2231 # all other types of nargs produce a list 2232 else: 2233 value = [self._get_value(action, v) for v in arg_strings] 2234 for v in value: 2235 self._check_value(action, v) 2236 2237 # return the converted value 2238 return value 2239 2240 def _get_value(self, action, arg_string): 2241 type_func = self._registry_get('type', action.type, action.type) 2242 if not _callable(type_func): 2243 msg = _('%r is not callable') 2244 raise ArgumentError(action, msg % type_func) 2245 2246 # convert the value to the appropriate type 2247 try: 2248 result = type_func(arg_string) 2249 2250 # ArgumentTypeErrors indicate errors 2251 except ArgumentTypeError: 2252 name = getattr(action.type, '__name__', repr(action.type)) 2253 msg = str(_sys.exc_info()[1]) 2254 raise ArgumentError(action, msg) 2255 2256 # TypeErrors or ValueErrors also indicate errors 2257 except (TypeError, ValueError): 2258 name = getattr(action.type, '__name__', repr(action.type)) 2259 msg = _('invalid %s value: %r') 2260 raise ArgumentError(action, msg % (name, arg_string)) 2261 2262 # return the converted value 2263 return result 2264 2265 def _check_value(self, action, value): 2266 # converted value must be one of the choices (if specified) 2267 if action.choices is not None and value not in action.choices: 2268 tup = value, ', '.join(map(repr, action.choices)) 2269 msg = _('invalid choice: %r (choose from %s)') % tup 2270 raise ArgumentError(action, msg) 2271 2272 # ======================= 2273 # Help-formatting methods 2274 # ======================= 2275 def format_usage(self): 2276 formatter = self._get_formatter() 2277 formatter.add_usage(self.usage, self._actions, 2278 self._mutually_exclusive_groups) 2279 return formatter.format_help() 2280 2281 def format_help(self): 2282 formatter = self._get_formatter() 2283 2284 # usage 2285 formatter.add_usage(self.usage, self._actions, 2286 self._mutually_exclusive_groups) 2287 2288 # description 2289 formatter.add_text(self.description) 2290 2291 # positionals, optionals and user-defined groups 2292 for action_group in self._action_groups: 2293 formatter.start_section(action_group.title) 2294 formatter.add_text(action_group.description) 2295 formatter.add_arguments(action_group._group_actions) 2296 formatter.end_section() 2297 2298 # epilog 2299 formatter.add_text(self.epilog) 2300 2301 # determine help from format above 2302 return formatter.format_help() 2303 2304 def format_version(self): 2305 import warnings 2306 warnings.warn( 2307 'The format_version method is deprecated -- the "version" ' 2308 'argument to ArgumentParser is no longer supported.', 2309 DeprecationWarning) 2310 formatter = self._get_formatter() 2311 formatter.add_text(self.version) 2312 return formatter.format_help() 2313 2314 def _get_formatter(self): 2315 return self.formatter_class(prog=self.prog) 2316 2317 # ===================== 2318 # Help-printing methods 2319 # ===================== 2320 def print_usage(self, file=None): 2321 if file is None: 2322 file = _sys.stdout 2323 self._print_message(self.format_usage(), file) 2324 2325 def print_help(self, file=None): 2326 if file is None: 2327 file = _sys.stdout 2328 self._print_message(self.format_help(), file) 2329 2330 def print_version(self, file=None): 2331 import warnings 2332 warnings.warn( 2333 'The print_version method is deprecated -- the "version" ' 2334 'argument to ArgumentParser is no longer supported.', 2335 DeprecationWarning) 2336 self._print_message(self.format_version(), file) 2337 2338 def _print_message(self, message, file=None): 2339 if message: 2340 if file is None: 2341 file = _sys.stderr 2342 file.write(message) 2343 2344 # =============== 2345 # Exiting methods 2346 # =============== 2347 def exit(self, status=0, message=None): 2348 if message: 2349 self._print_message(message, _sys.stderr) 2350 _sys.exit(status) 2351 2352 def error(self, message): 2353 """error(message: string) 2354 2355 Prints a usage message incorporating the message to stderr and 2356 exits. 2357 2358 If you override this in a subclass, it should not return -- it 2359 should either exit or raise an exception. 2360 """ 2361 self.print_usage(_sys.stderr) 2362 self.exit(2, _('%s: error: %s\n') % (self.prog, message)) 2363