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