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