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