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