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