argparse.py revision f8583acb534432097671e79eb4110b9861dd2e17
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 tup = parser_name, ', '.join(self._name_parser_map) 1083 msg = _('unknown parser %r (choices: %s)') % tup 1084 raise ArgumentError(self, msg) 1085 1086 # parse all the remaining options into the namespace 1087 # store any unrecognized options on the object, so that the top 1088 # level parser can decide what to do with them 1089 namespace, arg_strings = parser.parse_known_args(arg_strings, namespace) 1090 if arg_strings: 1091 vars(namespace).setdefault(_UNRECOGNIZED_ARGS_ATTR, []) 1092 getattr(namespace, _UNRECOGNIZED_ARGS_ATTR).extend(arg_strings) 1093 1094 1095# ============== 1096# Type classes 1097# ============== 1098 1099class FileType(object): 1100 """Factory for creating file object types 1101 1102 Instances of FileType are typically passed as type= arguments to the 1103 ArgumentParser add_argument() method. 1104 1105 Keyword Arguments: 1106 - mode -- A string indicating how the file is to be opened. Accepts the 1107 same values as the builtin open() function. 1108 - bufsize -- The file's desired buffer size. Accepts the same values as 1109 the builtin open() function. 1110 """ 1111 1112 def __init__(self, mode='r', bufsize=-1): 1113 self._mode = mode 1114 self._bufsize = bufsize 1115 1116 def __call__(self, string): 1117 # the special argument "-" means sys.std{in,out} 1118 if string == '-': 1119 if 'r' in self._mode: 1120 return _sys.stdin 1121 elif 'w' in self._mode: 1122 return _sys.stdout 1123 else: 1124 msg = _('argument "-" with mode %r') % self._mode 1125 raise ValueError(msg) 1126 1127 # all other arguments are used as file names 1128 try: 1129 return open(string, self._mode, self._bufsize) 1130 except IOError as e: 1131 message = _("can't open '%s': %s") 1132 raise ArgumentTypeError(message % (string, e)) 1133 1134 def __repr__(self): 1135 args = self._mode, self._bufsize 1136 args_str = ', '.join(repr(arg) for arg in args if arg != -1) 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 __hash__ = None 1155 1156 def __eq__(self, other): 1157 return vars(self) == vars(other) 1158 1159 def __ne__(self, other): 1160 return not (self == other) 1161 1162 def __contains__(self, key): 1163 return key in self.__dict__ 1164 1165 1166class _ActionsContainer(object): 1167 1168 def __init__(self, 1169 description, 1170 prefix_chars, 1171 argument_default, 1172 conflict_handler): 1173 super(_ActionsContainer, self).__init__() 1174 1175 self.description = description 1176 self.argument_default = argument_default 1177 self.prefix_chars = prefix_chars 1178 self.conflict_handler = conflict_handler 1179 1180 # set up registries 1181 self._registries = {} 1182 1183 # register actions 1184 self.register('action', None, _StoreAction) 1185 self.register('action', 'store', _StoreAction) 1186 self.register('action', 'store_const', _StoreConstAction) 1187 self.register('action', 'store_true', _StoreTrueAction) 1188 self.register('action', 'store_false', _StoreFalseAction) 1189 self.register('action', 'append', _AppendAction) 1190 self.register('action', 'append_const', _AppendConstAction) 1191 self.register('action', 'count', _CountAction) 1192 self.register('action', 'help', _HelpAction) 1193 self.register('action', 'version', _VersionAction) 1194 self.register('action', 'parsers', _SubParsersAction) 1195 1196 # raise an exception if the conflict handler is invalid 1197 self._get_handler() 1198 1199 # action storage 1200 self._actions = [] 1201 self._option_string_actions = {} 1202 1203 # groups 1204 self._action_groups = [] 1205 self._mutually_exclusive_groups = [] 1206 1207 # defaults storage 1208 self._defaults = {} 1209 1210 # determines whether an "option" looks like a negative number 1211 self._negative_number_matcher = _re.compile(r'^-\d+$|^-\d*\.\d+$') 1212 1213 # whether or not there are any optionals that look like negative 1214 # numbers -- uses a list so it can be shared and edited 1215 self._has_negative_number_optionals = [] 1216 1217 # ==================== 1218 # Registration methods 1219 # ==================== 1220 def register(self, registry_name, value, object): 1221 registry = self._registries.setdefault(registry_name, {}) 1222 registry[value] = object 1223 1224 def _registry_get(self, registry_name, value, default=None): 1225 return self._registries[registry_name].get(value, default) 1226 1227 # ================================== 1228 # Namespace default accessor methods 1229 # ================================== 1230 def set_defaults(self, **kwargs): 1231 self._defaults.update(kwargs) 1232 1233 # if these defaults match any existing arguments, replace 1234 # the previous default on the object with the new one 1235 for action in self._actions: 1236 if action.dest in kwargs: 1237 action.default = kwargs[action.dest] 1238 1239 def get_default(self, dest): 1240 for action in self._actions: 1241 if action.dest == dest and action.default is not None: 1242 return action.default 1243 return self._defaults.get(dest, None) 1244 1245 1246 # ======================= 1247 # Adding argument actions 1248 # ======================= 1249 def add_argument(self, *args, **kwargs): 1250 """ 1251 add_argument(dest, ..., name=value, ...) 1252 add_argument(option_string, option_string, ..., name=value, ...) 1253 """ 1254 1255 # if no positional args are supplied or only one is supplied and 1256 # it doesn't look like an option string, parse a positional 1257 # argument 1258 chars = self.prefix_chars 1259 if not args or len(args) == 1 and args[0][0] not in chars: 1260 if args and 'dest' in kwargs: 1261 raise ValueError('dest supplied twice for positional argument') 1262 kwargs = self._get_positional_kwargs(*args, **kwargs) 1263 1264 # otherwise, we're adding an optional argument 1265 else: 1266 kwargs = self._get_optional_kwargs(*args, **kwargs) 1267 1268 # if no default was supplied, use the parser-level default 1269 if 'default' not in kwargs: 1270 dest = kwargs['dest'] 1271 if dest in self._defaults: 1272 kwargs['default'] = self._defaults[dest] 1273 elif self.argument_default is not None: 1274 kwargs['default'] = self.argument_default 1275 1276 # create the action object, and add it to the parser 1277 action_class = self._pop_action_class(kwargs) 1278 if not _callable(action_class): 1279 raise ValueError('unknown action "%s"' % action_class) 1280 action = action_class(**kwargs) 1281 1282 # raise an error if the action type is not callable 1283 type_func = self._registry_get('type', action.type, action.type) 1284 if not _callable(type_func): 1285 raise ValueError('%r is not callable' % type_func) 1286 1287 return self._add_action(action) 1288 1289 def add_argument_group(self, *args, **kwargs): 1290 group = _ArgumentGroup(self, *args, **kwargs) 1291 self._action_groups.append(group) 1292 return group 1293 1294 def add_mutually_exclusive_group(self, **kwargs): 1295 group = _MutuallyExclusiveGroup(self, **kwargs) 1296 self._mutually_exclusive_groups.append(group) 1297 return group 1298 1299 def _add_action(self, action): 1300 # resolve any conflicts 1301 self._check_conflict(action) 1302 1303 # add to actions list 1304 self._actions.append(action) 1305 action.container = self 1306 1307 # index the action by any option strings it has 1308 for option_string in action.option_strings: 1309 self._option_string_actions[option_string] = action 1310 1311 # set the flag if any option strings look like negative numbers 1312 for option_string in action.option_strings: 1313 if self._negative_number_matcher.match(option_string): 1314 if not self._has_negative_number_optionals: 1315 self._has_negative_number_optionals.append(True) 1316 1317 # return the created action 1318 return action 1319 1320 def _remove_action(self, action): 1321 self._actions.remove(action) 1322 1323 def _add_container_actions(self, container): 1324 # collect groups by titles 1325 title_group_map = {} 1326 for group in self._action_groups: 1327 if group.title in title_group_map: 1328 msg = _('cannot merge actions - two groups are named %r') 1329 raise ValueError(msg % (group.title)) 1330 title_group_map[group.title] = group 1331 1332 # map each action to its group 1333 group_map = {} 1334 for group in container._action_groups: 1335 1336 # if a group with the title exists, use that, otherwise 1337 # create a new group matching the container's group 1338 if group.title not in title_group_map: 1339 title_group_map[group.title] = self.add_argument_group( 1340 title=group.title, 1341 description=group.description, 1342 conflict_handler=group.conflict_handler) 1343 1344 # map the actions to their new group 1345 for action in group._group_actions: 1346 group_map[action] = title_group_map[group.title] 1347 1348 # add container's mutually exclusive groups 1349 # NOTE: if add_mutually_exclusive_group ever gains title= and 1350 # description= then this code will need to be expanded as above 1351 for group in container._mutually_exclusive_groups: 1352 mutex_group = self.add_mutually_exclusive_group( 1353 required=group.required) 1354 1355 # map the actions to their new mutex group 1356 for action in group._group_actions: 1357 group_map[action] = mutex_group 1358 1359 # add all actions to this container or their group 1360 for action in container._actions: 1361 group_map.get(action, self)._add_action(action) 1362 1363 def _get_positional_kwargs(self, dest, **kwargs): 1364 # make sure required is not specified 1365 if 'required' in kwargs: 1366 msg = _("'required' is an invalid argument for positionals") 1367 raise TypeError(msg) 1368 1369 # mark positional arguments as required if at least one is 1370 # always required 1371 if kwargs.get('nargs') not in [OPTIONAL, ZERO_OR_MORE]: 1372 kwargs['required'] = True 1373 if kwargs.get('nargs') == ZERO_OR_MORE and 'default' not in kwargs: 1374 kwargs['required'] = True 1375 1376 # return the keyword arguments with no option strings 1377 return dict(kwargs, dest=dest, option_strings=[]) 1378 1379 def _get_optional_kwargs(self, *args, **kwargs): 1380 # determine short and long option strings 1381 option_strings = [] 1382 long_option_strings = [] 1383 for option_string in args: 1384 # error on strings that don't start with an appropriate prefix 1385 if not option_string[0] in self.prefix_chars: 1386 msg = _('invalid option string %r: ' 1387 'must start with a character %r') 1388 tup = option_string, self.prefix_chars 1389 raise ValueError(msg % tup) 1390 1391 # strings starting with two prefix characters are long options 1392 option_strings.append(option_string) 1393 if option_string[0] in self.prefix_chars: 1394 if len(option_string) > 1: 1395 if option_string[1] in self.prefix_chars: 1396 long_option_strings.append(option_string) 1397 1398 # infer destination, '--foo-bar' -> 'foo_bar' and '-x' -> 'x' 1399 dest = kwargs.pop('dest', None) 1400 if dest is None: 1401 if long_option_strings: 1402 dest_option_string = long_option_strings[0] 1403 else: 1404 dest_option_string = option_strings[0] 1405 dest = dest_option_string.lstrip(self.prefix_chars) 1406 if not dest: 1407 msg = _('dest= is required for options like %r') 1408 raise ValueError(msg % option_string) 1409 dest = dest.replace('-', '_') 1410 1411 # return the updated keyword arguments 1412 return dict(kwargs, dest=dest, option_strings=option_strings) 1413 1414 def _pop_action_class(self, kwargs, default=None): 1415 action = kwargs.pop('action', default) 1416 return self._registry_get('action', action, action) 1417 1418 def _get_handler(self): 1419 # determine function from conflict handler string 1420 handler_func_name = '_handle_conflict_%s' % self.conflict_handler 1421 try: 1422 return getattr(self, handler_func_name) 1423 except AttributeError: 1424 msg = _('invalid conflict_resolution value: %r') 1425 raise ValueError(msg % self.conflict_handler) 1426 1427 def _check_conflict(self, action): 1428 1429 # find all options that conflict with this option 1430 confl_optionals = [] 1431 for option_string in action.option_strings: 1432 if option_string in self._option_string_actions: 1433 confl_optional = self._option_string_actions[option_string] 1434 confl_optionals.append((option_string, confl_optional)) 1435 1436 # resolve any conflicts 1437 if confl_optionals: 1438 conflict_handler = self._get_handler() 1439 conflict_handler(action, confl_optionals) 1440 1441 def _handle_conflict_error(self, action, conflicting_actions): 1442 message = _('conflicting option string(s): %s') 1443 conflict_string = ', '.join([option_string 1444 for option_string, action 1445 in conflicting_actions]) 1446 raise ArgumentError(action, message % conflict_string) 1447 1448 def _handle_conflict_resolve(self, action, conflicting_actions): 1449 1450 # remove all conflicting options 1451 for option_string, action in conflicting_actions: 1452 1453 # remove the conflicting option 1454 action.option_strings.remove(option_string) 1455 self._option_string_actions.pop(option_string, None) 1456 1457 # if the option now has no option string, remove it from the 1458 # container holding it 1459 if not action.option_strings: 1460 action.container._remove_action(action) 1461 1462 1463class _ArgumentGroup(_ActionsContainer): 1464 1465 def __init__(self, container, title=None, description=None, **kwargs): 1466 # add any missing keyword arguments by checking the container 1467 update = kwargs.setdefault 1468 update('conflict_handler', container.conflict_handler) 1469 update('prefix_chars', container.prefix_chars) 1470 update('argument_default', container.argument_default) 1471 super_init = super(_ArgumentGroup, self).__init__ 1472 super_init(description=description, **kwargs) 1473 1474 # group attributes 1475 self.title = title 1476 self._group_actions = [] 1477 1478 # share most attributes with the container 1479 self._registries = container._registries 1480 self._actions = container._actions 1481 self._option_string_actions = container._option_string_actions 1482 self._defaults = container._defaults 1483 self._has_negative_number_optionals = \ 1484 container._has_negative_number_optionals 1485 1486 def _add_action(self, action): 1487 action = super(_ArgumentGroup, self)._add_action(action) 1488 self._group_actions.append(action) 1489 return action 1490 1491 def _remove_action(self, action): 1492 super(_ArgumentGroup, self)._remove_action(action) 1493 self._group_actions.remove(action) 1494 1495 1496class _MutuallyExclusiveGroup(_ArgumentGroup): 1497 1498 def __init__(self, container, required=False): 1499 super(_MutuallyExclusiveGroup, self).__init__(container) 1500 self.required = required 1501 self._container = container 1502 1503 def _add_action(self, action): 1504 if action.required: 1505 msg = _('mutually exclusive arguments must be optional') 1506 raise ValueError(msg) 1507 action = self._container._add_action(action) 1508 self._group_actions.append(action) 1509 return action 1510 1511 def _remove_action(self, action): 1512 self._container._remove_action(action) 1513 self._group_actions.remove(action) 1514 1515 1516class ArgumentParser(_AttributeHolder, _ActionsContainer): 1517 """Object for parsing command line strings into Python objects. 1518 1519 Keyword Arguments: 1520 - prog -- The name of the program (default: sys.argv[0]) 1521 - usage -- A usage message (default: auto-generated from arguments) 1522 - description -- A description of what the program does 1523 - epilog -- Text following the argument descriptions 1524 - parents -- Parsers whose arguments should be copied into this one 1525 - formatter_class -- HelpFormatter class for printing help messages 1526 - prefix_chars -- Characters that prefix optional arguments 1527 - fromfile_prefix_chars -- Characters that prefix files containing 1528 additional arguments 1529 - argument_default -- The default value for all arguments 1530 - conflict_handler -- String indicating how to handle conflicts 1531 - add_help -- Add a -h/-help option 1532 """ 1533 1534 def __init__(self, 1535 prog=None, 1536 usage=None, 1537 description=None, 1538 epilog=None, 1539 version=None, 1540 parents=[], 1541 formatter_class=HelpFormatter, 1542 prefix_chars='-', 1543 fromfile_prefix_chars=None, 1544 argument_default=None, 1545 conflict_handler='error', 1546 add_help=True): 1547 1548 if version is not None: 1549 import warnings 1550 warnings.warn( 1551 """The "version" argument to ArgumentParser is deprecated. """ 1552 """Please use """ 1553 """"add_argument(..., action='version', version="N", ...)" """ 1554 """instead""", DeprecationWarning) 1555 1556 superinit = super(ArgumentParser, self).__init__ 1557 superinit(description=description, 1558 prefix_chars=prefix_chars, 1559 argument_default=argument_default, 1560 conflict_handler=conflict_handler) 1561 1562 # default setting for prog 1563 if prog is None: 1564 prog = _os.path.basename(_sys.argv[0]) 1565 1566 self.prog = prog 1567 self.usage = usage 1568 self.epilog = epilog 1569 self.version = version 1570 self.formatter_class = formatter_class 1571 self.fromfile_prefix_chars = fromfile_prefix_chars 1572 self.add_help = add_help 1573 1574 add_group = self.add_argument_group 1575 self._positionals = add_group(_('positional arguments')) 1576 self._optionals = add_group(_('optional arguments')) 1577 self._subparsers = None 1578 1579 # register types 1580 def identity(string): 1581 return string 1582 self.register('type', None, identity) 1583 1584 # add help and version arguments if necessary 1585 # (using explicit default to override global argument_default) 1586 default_prefix = '-' if '-' in prefix_chars else prefix_chars[0] 1587 if self.add_help: 1588 self.add_argument( 1589 default_prefix+'h', default_prefix*2+'help', 1590 action='help', default=SUPPRESS, 1591 help=_('show this help message and exit')) 1592 if self.version: 1593 self.add_argument( 1594 default_prefix+'v', default_prefix*2+'version', 1595 action='version', default=SUPPRESS, 1596 version=self.version, 1597 help=_("show program's version number and exit")) 1598 1599 # add parent arguments and defaults 1600 for parent in parents: 1601 self._add_container_actions(parent) 1602 try: 1603 defaults = parent._defaults 1604 except AttributeError: 1605 pass 1606 else: 1607 self._defaults.update(defaults) 1608 1609 # ======================= 1610 # Pretty __repr__ methods 1611 # ======================= 1612 def _get_kwargs(self): 1613 names = [ 1614 'prog', 1615 'usage', 1616 'description', 1617 'version', 1618 'formatter_class', 1619 'conflict_handler', 1620 'add_help', 1621 ] 1622 return [(name, getattr(self, name)) for name in names] 1623 1624 # ================================== 1625 # Optional/Positional adding methods 1626 # ================================== 1627 def add_subparsers(self, **kwargs): 1628 if self._subparsers is not None: 1629 self.error(_('cannot have multiple subparser arguments')) 1630 1631 # add the parser class to the arguments if it's not present 1632 kwargs.setdefault('parser_class', type(self)) 1633 1634 if 'title' in kwargs or 'description' in kwargs: 1635 title = _(kwargs.pop('title', 'subcommands')) 1636 description = _(kwargs.pop('description', None)) 1637 self._subparsers = self.add_argument_group(title, description) 1638 else: 1639 self._subparsers = self._positionals 1640 1641 # prog defaults to the usage message of this parser, skipping 1642 # optional arguments and with no "usage:" prefix 1643 if kwargs.get('prog') is None: 1644 formatter = self._get_formatter() 1645 positionals = self._get_positional_actions() 1646 groups = self._mutually_exclusive_groups 1647 formatter.add_usage(self.usage, positionals, groups, '') 1648 kwargs['prog'] = formatter.format_help().strip() 1649 1650 # create the parsers action and add it to the positionals list 1651 parsers_class = self._pop_action_class(kwargs, 'parsers') 1652 action = parsers_class(option_strings=[], **kwargs) 1653 self._subparsers._add_action(action) 1654 1655 # return the created parsers action 1656 return action 1657 1658 def _add_action(self, action): 1659 if action.option_strings: 1660 self._optionals._add_action(action) 1661 else: 1662 self._positionals._add_action(action) 1663 return action 1664 1665 def _get_optional_actions(self): 1666 return [action 1667 for action in self._actions 1668 if action.option_strings] 1669 1670 def _get_positional_actions(self): 1671 return [action 1672 for action in self._actions 1673 if not action.option_strings] 1674 1675 # ===================================== 1676 # Command line argument parsing methods 1677 # ===================================== 1678 def parse_args(self, args=None, namespace=None): 1679 args, argv = self.parse_known_args(args, namespace) 1680 if argv: 1681 msg = _('unrecognized arguments: %s') 1682 self.error(msg % ' '.join(argv)) 1683 return args 1684 1685 def parse_known_args(self, args=None, namespace=None): 1686 # args default to the system args 1687 if args is None: 1688 args = _sys.argv[1:] 1689 1690 # default Namespace built from parser defaults 1691 if namespace is None: 1692 namespace = Namespace() 1693 1694 # add any action defaults that aren't present 1695 for action in self._actions: 1696 if action.dest is not SUPPRESS: 1697 if not hasattr(namespace, action.dest): 1698 if action.default is not SUPPRESS: 1699 default = action.default 1700 if isinstance(action.default, basestring): 1701 default = self._get_value(action, default) 1702 setattr(namespace, action.dest, default) 1703 1704 # add any parser defaults that aren't present 1705 for dest in self._defaults: 1706 if not hasattr(namespace, dest): 1707 setattr(namespace, dest, self._defaults[dest]) 1708 1709 # parse the arguments and exit if there are any errors 1710 try: 1711 namespace, args = self._parse_known_args(args, namespace) 1712 if hasattr(namespace, _UNRECOGNIZED_ARGS_ATTR): 1713 args.extend(getattr(namespace, _UNRECOGNIZED_ARGS_ATTR)) 1714 delattr(namespace, _UNRECOGNIZED_ARGS_ATTR) 1715 return namespace, args 1716 except ArgumentError: 1717 err = _sys.exc_info()[1] 1718 self.error(str(err)) 1719 1720 def _parse_known_args(self, arg_strings, namespace): 1721 # replace arg strings that are file references 1722 if self.fromfile_prefix_chars is not None: 1723 arg_strings = self._read_args_from_files(arg_strings) 1724 1725 # map all mutually exclusive arguments to the other arguments 1726 # they can't occur with 1727 action_conflicts = {} 1728 for mutex_group in self._mutually_exclusive_groups: 1729 group_actions = mutex_group._group_actions 1730 for i, mutex_action in enumerate(mutex_group._group_actions): 1731 conflicts = action_conflicts.setdefault(mutex_action, []) 1732 conflicts.extend(group_actions[:i]) 1733 conflicts.extend(group_actions[i + 1:]) 1734 1735 # find all option indices, and determine the arg_string_pattern 1736 # which has an 'O' if there is an option at an index, 1737 # an 'A' if there is an argument, or a '-' if there is a '--' 1738 option_string_indices = {} 1739 arg_string_pattern_parts = [] 1740 arg_strings_iter = iter(arg_strings) 1741 for i, arg_string in enumerate(arg_strings_iter): 1742 1743 # all args after -- are non-options 1744 if arg_string == '--': 1745 arg_string_pattern_parts.append('-') 1746 for arg_string in arg_strings_iter: 1747 arg_string_pattern_parts.append('A') 1748 1749 # otherwise, add the arg to the arg strings 1750 # and note the index if it was an option 1751 else: 1752 option_tuple = self._parse_optional(arg_string) 1753 if option_tuple is None: 1754 pattern = 'A' 1755 else: 1756 option_string_indices[i] = option_tuple 1757 pattern = 'O' 1758 arg_string_pattern_parts.append(pattern) 1759 1760 # join the pieces together to form the pattern 1761 arg_strings_pattern = ''.join(arg_string_pattern_parts) 1762 1763 # converts arg strings to the appropriate and then takes the action 1764 seen_actions = set() 1765 seen_non_default_actions = set() 1766 1767 def take_action(action, argument_strings, option_string=None): 1768 seen_actions.add(action) 1769 argument_values = self._get_values(action, argument_strings) 1770 1771 # error if this argument is not allowed with other previously 1772 # seen arguments, assuming that actions that use the default 1773 # value don't really count as "present" 1774 if argument_values is not action.default: 1775 seen_non_default_actions.add(action) 1776 for conflict_action in action_conflicts.get(action, []): 1777 if conflict_action in seen_non_default_actions: 1778 msg = _('not allowed with argument %s') 1779 action_name = _get_action_name(conflict_action) 1780 raise ArgumentError(action, msg % action_name) 1781 1782 # take the action if we didn't receive a SUPPRESS value 1783 # (e.g. from a default) 1784 if argument_values is not SUPPRESS: 1785 action(self, namespace, argument_values, option_string) 1786 1787 # function to convert arg_strings into an optional action 1788 def consume_optional(start_index): 1789 1790 # get the optional identified at this index 1791 option_tuple = option_string_indices[start_index] 1792 action, option_string, explicit_arg = option_tuple 1793 1794 # identify additional optionals in the same arg string 1795 # (e.g. -xyz is the same as -x -y -z if no args are required) 1796 match_argument = self._match_argument 1797 action_tuples = [] 1798 while True: 1799 1800 # if we found no optional action, skip it 1801 if action is None: 1802 extras.append(arg_strings[start_index]) 1803 return start_index + 1 1804 1805 # if there is an explicit argument, try to match the 1806 # optional's string arguments to only this 1807 if explicit_arg is not None: 1808 arg_count = match_argument(action, 'A') 1809 1810 # if the action is a single-dash option and takes no 1811 # arguments, try to parse more single-dash options out 1812 # of the tail of the option string 1813 chars = self.prefix_chars 1814 if arg_count == 0 and option_string[1] not in chars: 1815 action_tuples.append((action, [], option_string)) 1816 char = option_string[0] 1817 option_string = char + explicit_arg[0] 1818 new_explicit_arg = explicit_arg[1:] or None 1819 optionals_map = self._option_string_actions 1820 if option_string in optionals_map: 1821 action = optionals_map[option_string] 1822 explicit_arg = new_explicit_arg 1823 else: 1824 msg = _('ignored explicit argument %r') 1825 raise ArgumentError(action, msg % explicit_arg) 1826 1827 # if the action expect exactly one argument, we've 1828 # successfully matched the option; exit the loop 1829 elif arg_count == 1: 1830 stop = start_index + 1 1831 args = [explicit_arg] 1832 action_tuples.append((action, args, option_string)) 1833 break 1834 1835 # error if a double-dash option did not use the 1836 # explicit argument 1837 else: 1838 msg = _('ignored explicit argument %r') 1839 raise ArgumentError(action, msg % explicit_arg) 1840 1841 # if there is no explicit argument, try to match the 1842 # optional's string arguments with the following strings 1843 # if successful, exit the loop 1844 else: 1845 start = start_index + 1 1846 selected_patterns = arg_strings_pattern[start:] 1847 arg_count = match_argument(action, selected_patterns) 1848 stop = start + arg_count 1849 args = arg_strings[start:stop] 1850 action_tuples.append((action, args, option_string)) 1851 break 1852 1853 # add the Optional to the list and return the index at which 1854 # the Optional's string args stopped 1855 assert action_tuples 1856 for action, args, option_string in action_tuples: 1857 take_action(action, args, option_string) 1858 return stop 1859 1860 # the list of Positionals left to be parsed; this is modified 1861 # by consume_positionals() 1862 positionals = self._get_positional_actions() 1863 1864 # function to convert arg_strings into positional actions 1865 def consume_positionals(start_index): 1866 # match as many Positionals as possible 1867 match_partial = self._match_arguments_partial 1868 selected_pattern = arg_strings_pattern[start_index:] 1869 arg_counts = match_partial(positionals, selected_pattern) 1870 1871 # slice off the appropriate arg strings for each Positional 1872 # and add the Positional and its args to the list 1873 for action, arg_count in zip(positionals, arg_counts): 1874 args = arg_strings[start_index: start_index + arg_count] 1875 start_index += arg_count 1876 take_action(action, args) 1877 1878 # slice off the Positionals that we just parsed and return the 1879 # index at which the Positionals' string args stopped 1880 positionals[:] = positionals[len(arg_counts):] 1881 return start_index 1882 1883 # consume Positionals and Optionals alternately, until we have 1884 # passed the last option string 1885 extras = [] 1886 start_index = 0 1887 if option_string_indices: 1888 max_option_string_index = max(option_string_indices) 1889 else: 1890 max_option_string_index = -1 1891 while start_index <= max_option_string_index: 1892 1893 # consume any Positionals preceding the next option 1894 next_option_string_index = min([ 1895 index 1896 for index in option_string_indices 1897 if index >= start_index]) 1898 if start_index != next_option_string_index: 1899 positionals_end_index = consume_positionals(start_index) 1900 1901 # only try to parse the next optional if we didn't consume 1902 # the option string during the positionals parsing 1903 if positionals_end_index > start_index: 1904 start_index = positionals_end_index 1905 continue 1906 else: 1907 start_index = positionals_end_index 1908 1909 # if we consumed all the positionals we could and we're not 1910 # at the index of an option string, there were extra arguments 1911 if start_index not in option_string_indices: 1912 strings = arg_strings[start_index:next_option_string_index] 1913 extras.extend(strings) 1914 start_index = next_option_string_index 1915 1916 # consume the next optional and any arguments for it 1917 start_index = consume_optional(start_index) 1918 1919 # consume any positionals following the last Optional 1920 stop_index = consume_positionals(start_index) 1921 1922 # if we didn't consume all the argument strings, there were extras 1923 extras.extend(arg_strings[stop_index:]) 1924 1925 # if we didn't use all the Positional objects, there were too few 1926 # arg strings supplied. 1927 if positionals: 1928 self.error(_('too few arguments')) 1929 1930 # make sure all required actions were present 1931 for action in self._actions: 1932 if action.required: 1933 if action not in seen_actions: 1934 name = _get_action_name(action) 1935 self.error(_('argument %s is required') % name) 1936 1937 # make sure all required groups had one option present 1938 for group in self._mutually_exclusive_groups: 1939 if group.required: 1940 for action in group._group_actions: 1941 if action in seen_non_default_actions: 1942 break 1943 1944 # if no actions were used, report the error 1945 else: 1946 names = [_get_action_name(action) 1947 for action in group._group_actions 1948 if action.help is not SUPPRESS] 1949 msg = _('one of the arguments %s is required') 1950 self.error(msg % ' '.join(names)) 1951 1952 # return the updated namespace and the extra arguments 1953 return namespace, extras 1954 1955 def _read_args_from_files(self, arg_strings): 1956 # expand arguments referencing files 1957 new_arg_strings = [] 1958 for arg_string in arg_strings: 1959 1960 # for regular arguments, just add them back into the list 1961 if arg_string[0] not in self.fromfile_prefix_chars: 1962 new_arg_strings.append(arg_string) 1963 1964 # replace arguments referencing files with the file content 1965 else: 1966 try: 1967 args_file = open(arg_string[1:]) 1968 try: 1969 arg_strings = [] 1970 for arg_line in args_file.read().splitlines(): 1971 for arg in self.convert_arg_line_to_args(arg_line): 1972 arg_strings.append(arg) 1973 arg_strings = self._read_args_from_files(arg_strings) 1974 new_arg_strings.extend(arg_strings) 1975 finally: 1976 args_file.close() 1977 except IOError: 1978 err = _sys.exc_info()[1] 1979 self.error(str(err)) 1980 1981 # return the modified argument list 1982 return new_arg_strings 1983 1984 def convert_arg_line_to_args(self, arg_line): 1985 return [arg_line] 1986 1987 def _match_argument(self, action, arg_strings_pattern): 1988 # match the pattern for this action to the arg strings 1989 nargs_pattern = self._get_nargs_pattern(action) 1990 match = _re.match(nargs_pattern, arg_strings_pattern) 1991 1992 # raise an exception if we weren't able to find a match 1993 if match is None: 1994 nargs_errors = { 1995 None: _('expected one argument'), 1996 OPTIONAL: _('expected at most one argument'), 1997 ONE_OR_MORE: _('expected at least one argument'), 1998 } 1999 default = _('expected %s argument(s)') % action.nargs 2000 msg = nargs_errors.get(action.nargs, default) 2001 raise ArgumentError(action, msg) 2002 2003 # return the number of arguments matched 2004 return len(match.group(1)) 2005 2006 def _match_arguments_partial(self, actions, arg_strings_pattern): 2007 # progressively shorten the actions list by slicing off the 2008 # final actions until we find a match 2009 result = [] 2010 for i in range(len(actions), 0, -1): 2011 actions_slice = actions[:i] 2012 pattern = ''.join([self._get_nargs_pattern(action) 2013 for action in actions_slice]) 2014 match = _re.match(pattern, arg_strings_pattern) 2015 if match is not None: 2016 result.extend([len(string) for string in match.groups()]) 2017 break 2018 2019 # return the list of arg string counts 2020 return result 2021 2022 def _parse_optional(self, arg_string): 2023 # if it's an empty string, it was meant to be a positional 2024 if not arg_string: 2025 return None 2026 2027 # if it doesn't start with a prefix, it was meant to be positional 2028 if not arg_string[0] in self.prefix_chars: 2029 return None 2030 2031 # if the option string is present in the parser, return the action 2032 if arg_string in self._option_string_actions: 2033 action = self._option_string_actions[arg_string] 2034 return action, arg_string, None 2035 2036 # if it's just a single character, it was meant to be positional 2037 if len(arg_string) == 1: 2038 return None 2039 2040 # if the option string before the "=" is present, return the action 2041 if '=' in arg_string: 2042 option_string, explicit_arg = arg_string.split('=', 1) 2043 if option_string in self._option_string_actions: 2044 action = self._option_string_actions[option_string] 2045 return action, option_string, explicit_arg 2046 2047 # search through all possible prefixes of the option string 2048 # and all actions in the parser for possible interpretations 2049 option_tuples = self._get_option_tuples(arg_string) 2050 2051 # if multiple actions match, the option string was ambiguous 2052 if len(option_tuples) > 1: 2053 options = ', '.join([option_string 2054 for action, option_string, explicit_arg in option_tuples]) 2055 tup = arg_string, options 2056 self.error(_('ambiguous option: %s could match %s') % tup) 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, basestring): 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 msg = _('invalid %s value: %r') 2236 raise ArgumentError(action, msg % (name, arg_string)) 2237 2238 # return the converted value 2239 return result 2240 2241 def _check_value(self, action, value): 2242 # converted value must be one of the choices (if specified) 2243 if action.choices is not None and value not in action.choices: 2244 tup = value, ', '.join(map(repr, action.choices)) 2245 msg = _('invalid choice: %r (choose from %s)') % tup 2246 raise ArgumentError(action, msg) 2247 2248 # ======================= 2249 # Help-formatting methods 2250 # ======================= 2251 def format_usage(self): 2252 formatter = self._get_formatter() 2253 formatter.add_usage(self.usage, self._actions, 2254 self._mutually_exclusive_groups) 2255 return formatter.format_help() 2256 2257 def format_help(self): 2258 formatter = self._get_formatter() 2259 2260 # usage 2261 formatter.add_usage(self.usage, self._actions, 2262 self._mutually_exclusive_groups) 2263 2264 # description 2265 formatter.add_text(self.description) 2266 2267 # positionals, optionals and user-defined groups 2268 for action_group in self._action_groups: 2269 formatter.start_section(action_group.title) 2270 formatter.add_text(action_group.description) 2271 formatter.add_arguments(action_group._group_actions) 2272 formatter.end_section() 2273 2274 # epilog 2275 formatter.add_text(self.epilog) 2276 2277 # determine help from format above 2278 return formatter.format_help() 2279 2280 def format_version(self): 2281 import warnings 2282 warnings.warn( 2283 'The format_version method is deprecated -- the "version" ' 2284 'argument to ArgumentParser is no longer supported.', 2285 DeprecationWarning) 2286 formatter = self._get_formatter() 2287 formatter.add_text(self.version) 2288 return formatter.format_help() 2289 2290 def _get_formatter(self): 2291 return self.formatter_class(prog=self.prog) 2292 2293 # ===================== 2294 # Help-printing methods 2295 # ===================== 2296 def print_usage(self, file=None): 2297 if file is None: 2298 file = _sys.stdout 2299 self._print_message(self.format_usage(), file) 2300 2301 def print_help(self, file=None): 2302 if file is None: 2303 file = _sys.stdout 2304 self._print_message(self.format_help(), file) 2305 2306 def print_version(self, file=None): 2307 import warnings 2308 warnings.warn( 2309 'The print_version method is deprecated -- the "version" ' 2310 'argument to ArgumentParser is no longer supported.', 2311 DeprecationWarning) 2312 self._print_message(self.format_version(), file) 2313 2314 def _print_message(self, message, file=None): 2315 if message: 2316 if file is None: 2317 file = _sys.stderr 2318 file.write(message) 2319 2320 # =============== 2321 # Exiting methods 2322 # =============== 2323 def exit(self, status=0, message=None): 2324 if message: 2325 self._print_message(message, _sys.stderr) 2326 _sys.exit(status) 2327 2328 def error(self, message): 2329 """error(message: string) 2330 2331 Prints a usage message incorporating the message to stderr and 2332 exits. 2333 2334 If you override this in a subclass, it should not return -- it 2335 should either exit or raise an exception. 2336 """ 2337 self.print_usage(_sys.stderr) 2338 self.exit(2, _('%s: error: %s\n') % (self.prog, message)) 2339