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