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