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