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