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