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