argparse.py revision fb224e303435c9b98fd1a24dbd3cf119d7b90b6b
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=None): 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 __hash__ = None 1135 1136 def __eq__(self, other): 1137 return vars(self) == vars(other) 1138 1139 def __ne__(self, other): 1140 return not (self == other) 1141 1142 def __contains__(self, key): 1143 return key in self.__dict__ 1144 1145 1146class _ActionsContainer(object): 1147 1148 def __init__(self, 1149 description, 1150 prefix_chars, 1151 argument_default, 1152 conflict_handler): 1153 super(_ActionsContainer, self).__init__() 1154 1155 self.description = description 1156 self.argument_default = argument_default 1157 self.prefix_chars = prefix_chars 1158 self.conflict_handler = conflict_handler 1159 1160 # set up registries 1161 self._registries = {} 1162 1163 # register actions 1164 self.register('action', None, _StoreAction) 1165 self.register('action', 'store', _StoreAction) 1166 self.register('action', 'store_const', _StoreConstAction) 1167 self.register('action', 'store_true', _StoreTrueAction) 1168 self.register('action', 'store_false', _StoreFalseAction) 1169 self.register('action', 'append', _AppendAction) 1170 self.register('action', 'append_const', _AppendConstAction) 1171 self.register('action', 'count', _CountAction) 1172 self.register('action', 'help', _HelpAction) 1173 self.register('action', 'version', _VersionAction) 1174 self.register('action', 'parsers', _SubParsersAction) 1175 1176 # raise an exception if the conflict handler is invalid 1177 self._get_handler() 1178 1179 # action storage 1180 self._actions = [] 1181 self._option_string_actions = {} 1182 1183 # groups 1184 self._action_groups = [] 1185 self._mutually_exclusive_groups = [] 1186 1187 # defaults storage 1188 self._defaults = {} 1189 1190 # determines whether an "option" looks like a negative number 1191 self._negative_number_matcher = _re.compile(r'^-\d+$|^-\d*\.\d+$') 1192 1193 # whether or not there are any optionals that look like negative 1194 # numbers -- uses a list so it can be shared and edited 1195 self._has_negative_number_optionals = [] 1196 1197 # ==================== 1198 # Registration methods 1199 # ==================== 1200 def register(self, registry_name, value, object): 1201 registry = self._registries.setdefault(registry_name, {}) 1202 registry[value] = object 1203 1204 def _registry_get(self, registry_name, value, default=None): 1205 return self._registries[registry_name].get(value, default) 1206 1207 # ================================== 1208 # Namespace default accessor methods 1209 # ================================== 1210 def set_defaults(self, **kwargs): 1211 self._defaults.update(kwargs) 1212 1213 # if these defaults match any existing arguments, replace 1214 # the previous default on the object with the new one 1215 for action in self._actions: 1216 if action.dest in kwargs: 1217 action.default = kwargs[action.dest] 1218 1219 def get_default(self, dest): 1220 for action in self._actions: 1221 if action.dest == dest and action.default is not None: 1222 return action.default 1223 return self._defaults.get(dest, None) 1224 1225 1226 # ======================= 1227 # Adding argument actions 1228 # ======================= 1229 def add_argument(self, *args, **kwargs): 1230 """ 1231 add_argument(dest, ..., name=value, ...) 1232 add_argument(option_string, option_string, ..., name=value, ...) 1233 """ 1234 1235 # if no positional args are supplied or only one is supplied and 1236 # it doesn't look like an option string, parse a positional 1237 # argument 1238 chars = self.prefix_chars 1239 if not args or len(args) == 1 and args[0][0] not in chars: 1240 if args and 'dest' in kwargs: 1241 raise ValueError('dest supplied twice for positional argument') 1242 kwargs = self._get_positional_kwargs(*args, **kwargs) 1243 1244 # otherwise, we're adding an optional argument 1245 else: 1246 kwargs = self._get_optional_kwargs(*args, **kwargs) 1247 1248 # if no default was supplied, use the parser-level default 1249 if 'default' not in kwargs: 1250 dest = kwargs['dest'] 1251 if dest in self._defaults: 1252 kwargs['default'] = self._defaults[dest] 1253 elif self.argument_default is not None: 1254 kwargs['default'] = self.argument_default 1255 1256 # create the action object, and add it to the parser 1257 action_class = self._pop_action_class(kwargs) 1258 if not _callable(action_class): 1259 raise ValueError('unknown action "%s"' % action_class) 1260 action = action_class(**kwargs) 1261 1262 # raise an error if the action type is not callable 1263 type_func = self._registry_get('type', action.type, action.type) 1264 if not _callable(type_func): 1265 raise ValueError('%r is not callable' % type_func) 1266 1267 return self._add_action(action) 1268 1269 def add_argument_group(self, *args, **kwargs): 1270 group = _ArgumentGroup(self, *args, **kwargs) 1271 self._action_groups.append(group) 1272 return group 1273 1274 def add_mutually_exclusive_group(self, **kwargs): 1275 group = _MutuallyExclusiveGroup(self, **kwargs) 1276 self._mutually_exclusive_groups.append(group) 1277 return group 1278 1279 def _add_action(self, action): 1280 # resolve any conflicts 1281 self._check_conflict(action) 1282 1283 # add to actions list 1284 self._actions.append(action) 1285 action.container = self 1286 1287 # index the action by any option strings it has 1288 for option_string in action.option_strings: 1289 self._option_string_actions[option_string] = action 1290 1291 # set the flag if any option strings look like negative numbers 1292 for option_string in action.option_strings: 1293 if self._negative_number_matcher.match(option_string): 1294 if not self._has_negative_number_optionals: 1295 self._has_negative_number_optionals.append(True) 1296 1297 # return the created action 1298 return action 1299 1300 def _remove_action(self, action): 1301 self._actions.remove(action) 1302 1303 def _add_container_actions(self, container): 1304 # collect groups by titles 1305 title_group_map = {} 1306 for group in self._action_groups: 1307 if group.title in title_group_map: 1308 msg = _('cannot merge actions - two groups are named %r') 1309 raise ValueError(msg % (group.title)) 1310 title_group_map[group.title] = group 1311 1312 # map each action to its group 1313 group_map = {} 1314 for group in container._action_groups: 1315 1316 # if a group with the title exists, use that, otherwise 1317 # create a new group matching the container's group 1318 if group.title not in title_group_map: 1319 title_group_map[group.title] = self.add_argument_group( 1320 title=group.title, 1321 description=group.description, 1322 conflict_handler=group.conflict_handler) 1323 1324 # map the actions to their new group 1325 for action in group._group_actions: 1326 group_map[action] = title_group_map[group.title] 1327 1328 # add container's mutually exclusive groups 1329 # NOTE: if add_mutually_exclusive_group ever gains title= and 1330 # description= then this code will need to be expanded as above 1331 for group in container._mutually_exclusive_groups: 1332 mutex_group = self.add_mutually_exclusive_group( 1333 required=group.required) 1334 1335 # map the actions to their new mutex group 1336 for action in group._group_actions: 1337 group_map[action] = mutex_group 1338 1339 # add all actions to this container or their group 1340 for action in container._actions: 1341 group_map.get(action, self)._add_action(action) 1342 1343 def _get_positional_kwargs(self, dest, **kwargs): 1344 # make sure required is not specified 1345 if 'required' in kwargs: 1346 msg = _("'required' is an invalid argument for positionals") 1347 raise TypeError(msg) 1348 1349 # mark positional arguments as required if at least one is 1350 # always required 1351 if kwargs.get('nargs') not in [OPTIONAL, ZERO_OR_MORE]: 1352 kwargs['required'] = True 1353 if kwargs.get('nargs') == ZERO_OR_MORE and 'default' not in kwargs: 1354 kwargs['required'] = True 1355 1356 # return the keyword arguments with no option strings 1357 return dict(kwargs, dest=dest, option_strings=[]) 1358 1359 def _get_optional_kwargs(self, *args, **kwargs): 1360 # determine short and long option strings 1361 option_strings = [] 1362 long_option_strings = [] 1363 for option_string in args: 1364 # error on strings that don't start with an appropriate prefix 1365 if not option_string[0] in self.prefix_chars: 1366 msg = _('invalid option string %r: ' 1367 'must start with a character %r') 1368 tup = option_string, self.prefix_chars 1369 raise ValueError(msg % tup) 1370 1371 # strings starting with two prefix characters are long options 1372 option_strings.append(option_string) 1373 if option_string[0] in self.prefix_chars: 1374 if len(option_string) > 1: 1375 if option_string[1] in self.prefix_chars: 1376 long_option_strings.append(option_string) 1377 1378 # infer destination, '--foo-bar' -> 'foo_bar' and '-x' -> 'x' 1379 dest = kwargs.pop('dest', None) 1380 if dest is None: 1381 if long_option_strings: 1382 dest_option_string = long_option_strings[0] 1383 else: 1384 dest_option_string = option_strings[0] 1385 dest = dest_option_string.lstrip(self.prefix_chars) 1386 if not dest: 1387 msg = _('dest= is required for options like %r') 1388 raise ValueError(msg % option_string) 1389 dest = dest.replace('-', '_') 1390 1391 # return the updated keyword arguments 1392 return dict(kwargs, dest=dest, option_strings=option_strings) 1393 1394 def _pop_action_class(self, kwargs, default=None): 1395 action = kwargs.pop('action', default) 1396 return self._registry_get('action', action, action) 1397 1398 def _get_handler(self): 1399 # determine function from conflict handler string 1400 handler_func_name = '_handle_conflict_%s' % self.conflict_handler 1401 try: 1402 return getattr(self, handler_func_name) 1403 except AttributeError: 1404 msg = _('invalid conflict_resolution value: %r') 1405 raise ValueError(msg % self.conflict_handler) 1406 1407 def _check_conflict(self, action): 1408 1409 # find all options that conflict with this option 1410 confl_optionals = [] 1411 for option_string in action.option_strings: 1412 if option_string in self._option_string_actions: 1413 confl_optional = self._option_string_actions[option_string] 1414 confl_optionals.append((option_string, confl_optional)) 1415 1416 # resolve any conflicts 1417 if confl_optionals: 1418 conflict_handler = self._get_handler() 1419 conflict_handler(action, confl_optionals) 1420 1421 def _handle_conflict_error(self, action, conflicting_actions): 1422 message = _('conflicting option string(s): %s') 1423 conflict_string = ', '.join([option_string 1424 for option_string, action 1425 in conflicting_actions]) 1426 raise ArgumentError(action, message % conflict_string) 1427 1428 def _handle_conflict_resolve(self, action, conflicting_actions): 1429 1430 # remove all conflicting options 1431 for option_string, action in conflicting_actions: 1432 1433 # remove the conflicting option 1434 action.option_strings.remove(option_string) 1435 self._option_string_actions.pop(option_string, None) 1436 1437 # if the option now has no option string, remove it from the 1438 # container holding it 1439 if not action.option_strings: 1440 action.container._remove_action(action) 1441 1442 1443class _ArgumentGroup(_ActionsContainer): 1444 1445 def __init__(self, container, title=None, description=None, **kwargs): 1446 # add any missing keyword arguments by checking the container 1447 update = kwargs.setdefault 1448 update('conflict_handler', container.conflict_handler) 1449 update('prefix_chars', container.prefix_chars) 1450 update('argument_default', container.argument_default) 1451 super_init = super(_ArgumentGroup, self).__init__ 1452 super_init(description=description, **kwargs) 1453 1454 # group attributes 1455 self.title = title 1456 self._group_actions = [] 1457 1458 # share most attributes with the container 1459 self._registries = container._registries 1460 self._actions = container._actions 1461 self._option_string_actions = container._option_string_actions 1462 self._defaults = container._defaults 1463 self._has_negative_number_optionals = \ 1464 container._has_negative_number_optionals 1465 1466 def _add_action(self, action): 1467 action = super(_ArgumentGroup, self)._add_action(action) 1468 self._group_actions.append(action) 1469 return action 1470 1471 def _remove_action(self, action): 1472 super(_ArgumentGroup, self)._remove_action(action) 1473 self._group_actions.remove(action) 1474 1475 1476class _MutuallyExclusiveGroup(_ArgumentGroup): 1477 1478 def __init__(self, container, required=False): 1479 super(_MutuallyExclusiveGroup, self).__init__(container) 1480 self.required = required 1481 self._container = container 1482 1483 def _add_action(self, action): 1484 if action.required: 1485 msg = _('mutually exclusive arguments must be optional') 1486 raise ValueError(msg) 1487 action = self._container._add_action(action) 1488 self._group_actions.append(action) 1489 return action 1490 1491 def _remove_action(self, action): 1492 self._container._remove_action(action) 1493 self._group_actions.remove(action) 1494 1495 1496class ArgumentParser(_AttributeHolder, _ActionsContainer): 1497 """Object for parsing command line strings into Python objects. 1498 1499 Keyword Arguments: 1500 - prog -- The name of the program (default: sys.argv[0]) 1501 - usage -- A usage message (default: auto-generated from arguments) 1502 - description -- A description of what the program does 1503 - epilog -- Text following the argument descriptions 1504 - parents -- Parsers whose arguments should be copied into this one 1505 - formatter_class -- HelpFormatter class for printing help messages 1506 - prefix_chars -- Characters that prefix optional arguments 1507 - fromfile_prefix_chars -- Characters that prefix files containing 1508 additional arguments 1509 - argument_default -- The default value for all arguments 1510 - conflict_handler -- String indicating how to handle conflicts 1511 - add_help -- Add a -h/-help option 1512 """ 1513 1514 def __init__(self, 1515 prog=None, 1516 usage=None, 1517 description=None, 1518 epilog=None, 1519 version=None, 1520 parents=[], 1521 formatter_class=HelpFormatter, 1522 prefix_chars='-', 1523 fromfile_prefix_chars=None, 1524 argument_default=None, 1525 conflict_handler='error', 1526 add_help=True): 1527 1528 if version is not None: 1529 import warnings 1530 warnings.warn( 1531 """The "version" argument to ArgumentParser is deprecated. """ 1532 """Please use """ 1533 """"add_argument(..., action='version', version="N", ...)" """ 1534 """instead""", DeprecationWarning) 1535 1536 superinit = super(ArgumentParser, self).__init__ 1537 superinit(description=description, 1538 prefix_chars=prefix_chars, 1539 argument_default=argument_default, 1540 conflict_handler=conflict_handler) 1541 1542 # default setting for prog 1543 if prog is None: 1544 prog = _os.path.basename(_sys.argv[0]) 1545 1546 self.prog = prog 1547 self.usage = usage 1548 self.epilog = epilog 1549 self.version = version 1550 self.formatter_class = formatter_class 1551 self.fromfile_prefix_chars = fromfile_prefix_chars 1552 self.add_help = add_help 1553 1554 add_group = self.add_argument_group 1555 self._positionals = add_group(_('positional arguments')) 1556 self._optionals = add_group(_('optional arguments')) 1557 self._subparsers = None 1558 1559 # register types 1560 def identity(string): 1561 return string 1562 self.register('type', None, identity) 1563 1564 # add help and version arguments if necessary 1565 # (using explicit default to override global argument_default) 1566 if self.add_help: 1567 self.add_argument( 1568 '-h', '--help', action='help', default=SUPPRESS, 1569 help=_('show this help message and exit')) 1570 if self.version: 1571 self.add_argument( 1572 '-v', '--version', action='version', default=SUPPRESS, 1573 version=self.version, 1574 help=_("show program's version number and exit")) 1575 1576 # add parent arguments and defaults 1577 for parent in parents: 1578 self._add_container_actions(parent) 1579 try: 1580 defaults = parent._defaults 1581 except AttributeError: 1582 pass 1583 else: 1584 self._defaults.update(defaults) 1585 1586 # ======================= 1587 # Pretty __repr__ methods 1588 # ======================= 1589 def _get_kwargs(self): 1590 names = [ 1591 'prog', 1592 'usage', 1593 'description', 1594 'version', 1595 'formatter_class', 1596 'conflict_handler', 1597 'add_help', 1598 ] 1599 return [(name, getattr(self, name)) for name in names] 1600 1601 # ================================== 1602 # Optional/Positional adding methods 1603 # ================================== 1604 def add_subparsers(self, **kwargs): 1605 if self._subparsers is not None: 1606 self.error(_('cannot have multiple subparser arguments')) 1607 1608 # add the parser class to the arguments if it's not present 1609 kwargs.setdefault('parser_class', type(self)) 1610 1611 if 'title' in kwargs or 'description' in kwargs: 1612 title = _(kwargs.pop('title', 'subcommands')) 1613 description = _(kwargs.pop('description', None)) 1614 self._subparsers = self.add_argument_group(title, description) 1615 else: 1616 self._subparsers = self._positionals 1617 1618 # prog defaults to the usage message of this parser, skipping 1619 # optional arguments and with no "usage:" prefix 1620 if kwargs.get('prog') is None: 1621 formatter = self._get_formatter() 1622 positionals = self._get_positional_actions() 1623 groups = self._mutually_exclusive_groups 1624 formatter.add_usage(self.usage, positionals, groups, '') 1625 kwargs['prog'] = formatter.format_help().strip() 1626 1627 # create the parsers action and add it to the positionals list 1628 parsers_class = self._pop_action_class(kwargs, 'parsers') 1629 action = parsers_class(option_strings=[], **kwargs) 1630 self._subparsers._add_action(action) 1631 1632 # return the created parsers action 1633 return action 1634 1635 def _add_action(self, action): 1636 if action.option_strings: 1637 self._optionals._add_action(action) 1638 else: 1639 self._positionals._add_action(action) 1640 return action 1641 1642 def _get_optional_actions(self): 1643 return [action 1644 for action in self._actions 1645 if action.option_strings] 1646 1647 def _get_positional_actions(self): 1648 return [action 1649 for action in self._actions 1650 if not action.option_strings] 1651 1652 # ===================================== 1653 # Command line argument parsing methods 1654 # ===================================== 1655 def parse_args(self, args=None, namespace=None): 1656 args, argv = self.parse_known_args(args, namespace) 1657 if argv: 1658 msg = _('unrecognized arguments: %s') 1659 self.error(msg % ' '.join(argv)) 1660 return args 1661 1662 def parse_known_args(self, args=None, namespace=None): 1663 # args default to the system args 1664 if args is None: 1665 args = _sys.argv[1:] 1666 1667 # default Namespace built from parser defaults 1668 if namespace is None: 1669 namespace = Namespace() 1670 1671 # add any action defaults that aren't present 1672 for action in self._actions: 1673 if action.dest is not SUPPRESS: 1674 if not hasattr(namespace, action.dest): 1675 if action.default is not SUPPRESS: 1676 default = action.default 1677 if isinstance(action.default, basestring): 1678 default = self._get_value(action, default) 1679 setattr(namespace, action.dest, default) 1680 1681 # add any parser defaults that aren't present 1682 for dest in self._defaults: 1683 if not hasattr(namespace, dest): 1684 setattr(namespace, dest, self._defaults[dest]) 1685 1686 # parse the arguments and exit if there are any errors 1687 try: 1688 return self._parse_known_args(args, namespace) 1689 except ArgumentError: 1690 err = _sys.exc_info()[1] 1691 self.error(str(err)) 1692 1693 def _parse_known_args(self, arg_strings, namespace): 1694 # replace arg strings that are file references 1695 if self.fromfile_prefix_chars is not None: 1696 arg_strings = self._read_args_from_files(arg_strings) 1697 1698 # map all mutually exclusive arguments to the other arguments 1699 # they can't occur with 1700 action_conflicts = {} 1701 for mutex_group in self._mutually_exclusive_groups: 1702 group_actions = mutex_group._group_actions 1703 for i, mutex_action in enumerate(mutex_group._group_actions): 1704 conflicts = action_conflicts.setdefault(mutex_action, []) 1705 conflicts.extend(group_actions[:i]) 1706 conflicts.extend(group_actions[i + 1:]) 1707 1708 # find all option indices, and determine the arg_string_pattern 1709 # which has an 'O' if there is an option at an index, 1710 # an 'A' if there is an argument, or a '-' if there is a '--' 1711 option_string_indices = {} 1712 arg_string_pattern_parts = [] 1713 arg_strings_iter = iter(arg_strings) 1714 for i, arg_string in enumerate(arg_strings_iter): 1715 1716 # all args after -- are non-options 1717 if arg_string == '--': 1718 arg_string_pattern_parts.append('-') 1719 for arg_string in arg_strings_iter: 1720 arg_string_pattern_parts.append('A') 1721 1722 # otherwise, add the arg to the arg strings 1723 # and note the index if it was an option 1724 else: 1725 option_tuple = self._parse_optional(arg_string) 1726 if option_tuple is None: 1727 pattern = 'A' 1728 else: 1729 option_string_indices[i] = option_tuple 1730 pattern = 'O' 1731 arg_string_pattern_parts.append(pattern) 1732 1733 # join the pieces together to form the pattern 1734 arg_strings_pattern = ''.join(arg_string_pattern_parts) 1735 1736 # converts arg strings to the appropriate and then takes the action 1737 seen_actions = set() 1738 seen_non_default_actions = set() 1739 1740 def take_action(action, argument_strings, option_string=None): 1741 seen_actions.add(action) 1742 argument_values = self._get_values(action, argument_strings) 1743 1744 # error if this argument is not allowed with other previously 1745 # seen arguments, assuming that actions that use the default 1746 # value don't really count as "present" 1747 if argument_values is not action.default: 1748 seen_non_default_actions.add(action) 1749 for conflict_action in action_conflicts.get(action, []): 1750 if conflict_action in seen_non_default_actions: 1751 msg = _('not allowed with argument %s') 1752 action_name = _get_action_name(conflict_action) 1753 raise ArgumentError(action, msg % action_name) 1754 1755 # take the action if we didn't receive a SUPPRESS value 1756 # (e.g. from a default) 1757 if argument_values is not SUPPRESS: 1758 action(self, namespace, argument_values, option_string) 1759 1760 # function to convert arg_strings into an optional action 1761 def consume_optional(start_index): 1762 1763 # get the optional identified at this index 1764 option_tuple = option_string_indices[start_index] 1765 action, option_string, explicit_arg = option_tuple 1766 1767 # identify additional optionals in the same arg string 1768 # (e.g. -xyz is the same as -x -y -z if no args are required) 1769 match_argument = self._match_argument 1770 action_tuples = [] 1771 while True: 1772 1773 # if we found no optional action, skip it 1774 if action is None: 1775 extras.append(arg_strings[start_index]) 1776 return start_index + 1 1777 1778 # if there is an explicit argument, try to match the 1779 # optional's string arguments to only this 1780 if explicit_arg is not None: 1781 arg_count = match_argument(action, 'A') 1782 1783 # if the action is a single-dash option and takes no 1784 # arguments, try to parse more single-dash options out 1785 # of the tail of the option string 1786 chars = self.prefix_chars 1787 if arg_count == 0 and option_string[1] not in chars: 1788 action_tuples.append((action, [], option_string)) 1789 for char in self.prefix_chars: 1790 option_string = char + explicit_arg[0] 1791 explicit_arg = explicit_arg[1:] or None 1792 optionals_map = self._option_string_actions 1793 if option_string in optionals_map: 1794 action = optionals_map[option_string] 1795 break 1796 else: 1797 msg = _('ignored explicit argument %r') 1798 raise ArgumentError(action, msg % explicit_arg) 1799 1800 # if the action expect exactly one argument, we've 1801 # successfully matched the option; exit the loop 1802 elif arg_count == 1: 1803 stop = start_index + 1 1804 args = [explicit_arg] 1805 action_tuples.append((action, args, option_string)) 1806 break 1807 1808 # error if a double-dash option did not use the 1809 # explicit argument 1810 else: 1811 msg = _('ignored explicit argument %r') 1812 raise ArgumentError(action, msg % explicit_arg) 1813 1814 # if there is no explicit argument, try to match the 1815 # optional's string arguments with the following strings 1816 # if successful, exit the loop 1817 else: 1818 start = start_index + 1 1819 selected_patterns = arg_strings_pattern[start:] 1820 arg_count = match_argument(action, selected_patterns) 1821 stop = start + arg_count 1822 args = arg_strings[start:stop] 1823 action_tuples.append((action, args, option_string)) 1824 break 1825 1826 # add the Optional to the list and return the index at which 1827 # the Optional's string args stopped 1828 assert action_tuples 1829 for action, args, option_string in action_tuples: 1830 take_action(action, args, option_string) 1831 return stop 1832 1833 # the list of Positionals left to be parsed; this is modified 1834 # by consume_positionals() 1835 positionals = self._get_positional_actions() 1836 1837 # function to convert arg_strings into positional actions 1838 def consume_positionals(start_index): 1839 # match as many Positionals as possible 1840 match_partial = self._match_arguments_partial 1841 selected_pattern = arg_strings_pattern[start_index:] 1842 arg_counts = match_partial(positionals, selected_pattern) 1843 1844 # slice off the appropriate arg strings for each Positional 1845 # and add the Positional and its args to the list 1846 for action, arg_count in zip(positionals, arg_counts): 1847 args = arg_strings[start_index: start_index + arg_count] 1848 start_index += arg_count 1849 take_action(action, args) 1850 1851 # slice off the Positionals that we just parsed and return the 1852 # index at which the Positionals' string args stopped 1853 positionals[:] = positionals[len(arg_counts):] 1854 return start_index 1855 1856 # consume Positionals and Optionals alternately, until we have 1857 # passed the last option string 1858 extras = [] 1859 start_index = 0 1860 if option_string_indices: 1861 max_option_string_index = max(option_string_indices) 1862 else: 1863 max_option_string_index = -1 1864 while start_index <= max_option_string_index: 1865 1866 # consume any Positionals preceding the next option 1867 next_option_string_index = min([ 1868 index 1869 for index in option_string_indices 1870 if index >= start_index]) 1871 if start_index != next_option_string_index: 1872 positionals_end_index = consume_positionals(start_index) 1873 1874 # only try to parse the next optional if we didn't consume 1875 # the option string during the positionals parsing 1876 if positionals_end_index > start_index: 1877 start_index = positionals_end_index 1878 continue 1879 else: 1880 start_index = positionals_end_index 1881 1882 # if we consumed all the positionals we could and we're not 1883 # at the index of an option string, there were extra arguments 1884 if start_index not in option_string_indices: 1885 strings = arg_strings[start_index:next_option_string_index] 1886 extras.extend(strings) 1887 start_index = next_option_string_index 1888 1889 # consume the next optional and any arguments for it 1890 start_index = consume_optional(start_index) 1891 1892 # consume any positionals following the last Optional 1893 stop_index = consume_positionals(start_index) 1894 1895 # if we didn't consume all the argument strings, there were extras 1896 extras.extend(arg_strings[stop_index:]) 1897 1898 # if we didn't use all the Positional objects, there were too few 1899 # arg strings supplied. 1900 if positionals: 1901 self.error(_('too few arguments')) 1902 1903 # make sure all required actions were present 1904 for action in self._actions: 1905 if action.required: 1906 if action not in seen_actions: 1907 name = _get_action_name(action) 1908 self.error(_('argument %s is required') % name) 1909 1910 # make sure all required groups had one option present 1911 for group in self._mutually_exclusive_groups: 1912 if group.required: 1913 for action in group._group_actions: 1914 if action in seen_non_default_actions: 1915 break 1916 1917 # if no actions were used, report the error 1918 else: 1919 names = [_get_action_name(action) 1920 for action in group._group_actions 1921 if action.help is not SUPPRESS] 1922 msg = _('one of the arguments %s is required') 1923 self.error(msg % ' '.join(names)) 1924 1925 # return the updated namespace and the extra arguments 1926 return namespace, extras 1927 1928 def _read_args_from_files(self, arg_strings): 1929 # expand arguments referencing files 1930 new_arg_strings = [] 1931 for arg_string in arg_strings: 1932 1933 # for regular arguments, just add them back into the list 1934 if arg_string[0] not in self.fromfile_prefix_chars: 1935 new_arg_strings.append(arg_string) 1936 1937 # replace arguments referencing files with the file content 1938 else: 1939 try: 1940 args_file = open(arg_string[1:]) 1941 try: 1942 arg_strings = [] 1943 for arg_line in args_file.read().splitlines(): 1944 for arg in self.convert_arg_line_to_args(arg_line): 1945 arg_strings.append(arg) 1946 arg_strings = self._read_args_from_files(arg_strings) 1947 new_arg_strings.extend(arg_strings) 1948 finally: 1949 args_file.close() 1950 except IOError: 1951 err = _sys.exc_info()[1] 1952 self.error(str(err)) 1953 1954 # return the modified argument list 1955 return new_arg_strings 1956 1957 def convert_arg_line_to_args(self, arg_line): 1958 return [arg_line] 1959 1960 def _match_argument(self, action, arg_strings_pattern): 1961 # match the pattern for this action to the arg strings 1962 nargs_pattern = self._get_nargs_pattern(action) 1963 match = _re.match(nargs_pattern, arg_strings_pattern) 1964 1965 # raise an exception if we weren't able to find a match 1966 if match is None: 1967 nargs_errors = { 1968 None: _('expected one argument'), 1969 OPTIONAL: _('expected at most one argument'), 1970 ONE_OR_MORE: _('expected at least one argument'), 1971 } 1972 default = _('expected %s argument(s)') % action.nargs 1973 msg = nargs_errors.get(action.nargs, default) 1974 raise ArgumentError(action, msg) 1975 1976 # return the number of arguments matched 1977 return len(match.group(1)) 1978 1979 def _match_arguments_partial(self, actions, arg_strings_pattern): 1980 # progressively shorten the actions list by slicing off the 1981 # final actions until we find a match 1982 result = [] 1983 for i in range(len(actions), 0, -1): 1984 actions_slice = actions[:i] 1985 pattern = ''.join([self._get_nargs_pattern(action) 1986 for action in actions_slice]) 1987 match = _re.match(pattern, arg_strings_pattern) 1988 if match is not None: 1989 result.extend([len(string) for string in match.groups()]) 1990 break 1991 1992 # return the list of arg string counts 1993 return result 1994 1995 def _parse_optional(self, arg_string): 1996 # if it's an empty string, it was meant to be a positional 1997 if not arg_string: 1998 return None 1999 2000 # if it doesn't start with a prefix, it was meant to be positional 2001 if not arg_string[0] in self.prefix_chars: 2002 return None 2003 2004 # if the option string is present in the parser, return the action 2005 if arg_string in self._option_string_actions: 2006 action = self._option_string_actions[arg_string] 2007 return action, arg_string, None 2008 2009 # if it's just a single character, it was meant to be positional 2010 if len(arg_string) == 1: 2011 return None 2012 2013 # if the option string before the "=" is present, return the action 2014 if '=' in arg_string: 2015 option_string, explicit_arg = arg_string.split('=', 1) 2016 if option_string in self._option_string_actions: 2017 action = self._option_string_actions[option_string] 2018 return action, option_string, explicit_arg 2019 2020 # search through all possible prefixes of the option string 2021 # and all actions in the parser for possible interpretations 2022 option_tuples = self._get_option_tuples(arg_string) 2023 2024 # if multiple actions match, the option string was ambiguous 2025 if len(option_tuples) > 1: 2026 options = ', '.join([option_string 2027 for action, option_string, explicit_arg in option_tuples]) 2028 tup = arg_string, options 2029 self.error(_('ambiguous option: %s could match %s') % tup) 2030 2031 # if exactly one action matched, this segmentation is good, 2032 # so return the parsed action 2033 elif len(option_tuples) == 1: 2034 option_tuple, = option_tuples 2035 return option_tuple 2036 2037 # if it was not found as an option, but it looks like a negative 2038 # number, it was meant to be positional 2039 # unless there are negative-number-like options 2040 if self._negative_number_matcher.match(arg_string): 2041 if not self._has_negative_number_optionals: 2042 return None 2043 2044 # if it contains a space, it was meant to be a positional 2045 if ' ' in arg_string: 2046 return None 2047 2048 # it was meant to be an optional but there is no such option 2049 # in this parser (though it might be a valid option in a subparser) 2050 return None, arg_string, None 2051 2052 def _get_option_tuples(self, option_string): 2053 result = [] 2054 2055 # option strings starting with two prefix characters are only 2056 # split at the '=' 2057 chars = self.prefix_chars 2058 if option_string[0] in chars and option_string[1] in chars: 2059 if '=' in option_string: 2060 option_prefix, explicit_arg = option_string.split('=', 1) 2061 else: 2062 option_prefix = option_string 2063 explicit_arg = None 2064 for option_string in self._option_string_actions: 2065 if option_string.startswith(option_prefix): 2066 action = self._option_string_actions[option_string] 2067 tup = action, option_string, explicit_arg 2068 result.append(tup) 2069 2070 # single character options can be concatenated with their arguments 2071 # but multiple character options always have to have their argument 2072 # separate 2073 elif option_string[0] in chars and option_string[1] not in chars: 2074 option_prefix = option_string 2075 explicit_arg = None 2076 short_option_prefix = option_string[:2] 2077 short_explicit_arg = option_string[2:] 2078 2079 for option_string in self._option_string_actions: 2080 if option_string == short_option_prefix: 2081 action = self._option_string_actions[option_string] 2082 tup = action, option_string, short_explicit_arg 2083 result.append(tup) 2084 elif option_string.startswith(option_prefix): 2085 action = self._option_string_actions[option_string] 2086 tup = action, option_string, explicit_arg 2087 result.append(tup) 2088 2089 # shouldn't ever get here 2090 else: 2091 self.error(_('unexpected option string: %s') % option_string) 2092 2093 # return the collected option tuples 2094 return result 2095 2096 def _get_nargs_pattern(self, action): 2097 # in all examples below, we have to allow for '--' args 2098 # which are represented as '-' in the pattern 2099 nargs = action.nargs 2100 2101 # the default (None) is assumed to be a single argument 2102 if nargs is None: 2103 nargs_pattern = '(-*A-*)' 2104 2105 # allow zero or one arguments 2106 elif nargs == OPTIONAL: 2107 nargs_pattern = '(-*A?-*)' 2108 2109 # allow zero or more arguments 2110 elif nargs == ZERO_OR_MORE: 2111 nargs_pattern = '(-*[A-]*)' 2112 2113 # allow one or more arguments 2114 elif nargs == ONE_OR_MORE: 2115 nargs_pattern = '(-*A[A-]*)' 2116 2117 # allow any number of options or arguments 2118 elif nargs == REMAINDER: 2119 nargs_pattern = '([-AO]*)' 2120 2121 # allow one argument followed by any number of options or arguments 2122 elif nargs == PARSER: 2123 nargs_pattern = '(-*A[-AO]*)' 2124 2125 # all others should be integers 2126 else: 2127 nargs_pattern = '(-*%s-*)' % '-*'.join('A' * nargs) 2128 2129 # if this is an optional action, -- is not allowed 2130 if action.option_strings: 2131 nargs_pattern = nargs_pattern.replace('-*', '') 2132 nargs_pattern = nargs_pattern.replace('-', '') 2133 2134 # return the pattern 2135 return nargs_pattern 2136 2137 # ======================== 2138 # Value conversion methods 2139 # ======================== 2140 def _get_values(self, action, arg_strings): 2141 # for everything but PARSER args, strip out '--' 2142 if action.nargs not in [PARSER, REMAINDER]: 2143 arg_strings = [s for s in arg_strings if s != '--'] 2144 2145 # optional argument produces a default when not present 2146 if not arg_strings and action.nargs == OPTIONAL: 2147 if action.option_strings: 2148 value = action.const 2149 else: 2150 value = action.default 2151 if isinstance(value, basestring): 2152 value = self._get_value(action, value) 2153 self._check_value(action, value) 2154 2155 # when nargs='*' on a positional, if there were no command-line 2156 # args, use the default if it is anything other than None 2157 elif (not arg_strings and action.nargs == ZERO_OR_MORE and 2158 not action.option_strings): 2159 if action.default is not None: 2160 value = action.default 2161 else: 2162 value = arg_strings 2163 self._check_value(action, value) 2164 2165 # single argument or optional argument produces a single value 2166 elif len(arg_strings) == 1 and action.nargs in [None, OPTIONAL]: 2167 arg_string, = arg_strings 2168 value = self._get_value(action, arg_string) 2169 self._check_value(action, value) 2170 2171 # REMAINDER arguments convert all values, checking none 2172 elif action.nargs == REMAINDER: 2173 value = [self._get_value(action, v) for v in arg_strings] 2174 2175 # PARSER arguments convert all values, but check only the first 2176 elif action.nargs == PARSER: 2177 value = [self._get_value(action, v) for v in arg_strings] 2178 self._check_value(action, value[0]) 2179 2180 # all other types of nargs produce a list 2181 else: 2182 value = [self._get_value(action, v) for v in arg_strings] 2183 for v in value: 2184 self._check_value(action, v) 2185 2186 # return the converted value 2187 return value 2188 2189 def _get_value(self, action, arg_string): 2190 type_func = self._registry_get('type', action.type, action.type) 2191 if not _callable(type_func): 2192 msg = _('%r is not callable') 2193 raise ArgumentError(action, msg % type_func) 2194 2195 # convert the value to the appropriate type 2196 try: 2197 result = type_func(arg_string) 2198 2199 # ArgumentTypeErrors indicate errors 2200 except ArgumentTypeError: 2201 name = getattr(action.type, '__name__', repr(action.type)) 2202 msg = str(_sys.exc_info()[1]) 2203 raise ArgumentError(action, msg) 2204 2205 # TypeErrors or ValueErrors also indicate errors 2206 except (TypeError, ValueError): 2207 name = getattr(action.type, '__name__', repr(action.type)) 2208 msg = _('invalid %s value: %r') 2209 raise ArgumentError(action, msg % (name, arg_string)) 2210 2211 # return the converted value 2212 return result 2213 2214 def _check_value(self, action, value): 2215 # converted value must be one of the choices (if specified) 2216 if action.choices is not None and value not in action.choices: 2217 tup = value, ', '.join(map(repr, action.choices)) 2218 msg = _('invalid choice: %r (choose from %s)') % tup 2219 raise ArgumentError(action, msg) 2220 2221 # ======================= 2222 # Help-formatting methods 2223 # ======================= 2224 def format_usage(self): 2225 formatter = self._get_formatter() 2226 formatter.add_usage(self.usage, self._actions, 2227 self._mutually_exclusive_groups) 2228 return formatter.format_help() 2229 2230 def format_help(self): 2231 formatter = self._get_formatter() 2232 2233 # usage 2234 formatter.add_usage(self.usage, self._actions, 2235 self._mutually_exclusive_groups) 2236 2237 # description 2238 formatter.add_text(self.description) 2239 2240 # positionals, optionals and user-defined groups 2241 for action_group in self._action_groups: 2242 formatter.start_section(action_group.title) 2243 formatter.add_text(action_group.description) 2244 formatter.add_arguments(action_group._group_actions) 2245 formatter.end_section() 2246 2247 # epilog 2248 formatter.add_text(self.epilog) 2249 2250 # determine help from format above 2251 return formatter.format_help() 2252 2253 def format_version(self): 2254 import warnings 2255 warnings.warn( 2256 'The format_version method is deprecated -- the "version" ' 2257 'argument to ArgumentParser is no longer supported.', 2258 DeprecationWarning) 2259 formatter = self._get_formatter() 2260 formatter.add_text(self.version) 2261 return formatter.format_help() 2262 2263 def _get_formatter(self): 2264 return self.formatter_class(prog=self.prog) 2265 2266 # ===================== 2267 # Help-printing methods 2268 # ===================== 2269 def print_usage(self, file=None): 2270 if file is None: 2271 file = _sys.stdout 2272 self._print_message(self.format_usage(), file) 2273 2274 def print_help(self, file=None): 2275 if file is None: 2276 file = _sys.stdout 2277 self._print_message(self.format_help(), file) 2278 2279 def print_version(self, file=None): 2280 import warnings 2281 warnings.warn( 2282 'The print_version method is deprecated -- the "version" ' 2283 'argument to ArgumentParser is no longer supported.', 2284 DeprecationWarning) 2285 self._print_message(self.format_version(), file) 2286 2287 def _print_message(self, message, file=None): 2288 if message: 2289 if file is None: 2290 file = _sys.stderr 2291 file.write(message) 2292 2293 # =============== 2294 # Exiting methods 2295 # =============== 2296 def exit(self, status=0, message=None): 2297 if message: 2298 self._print_message(message, _sys.stderr) 2299 _sys.exit(status) 2300 2301 def error(self, message): 2302 """error(message: string) 2303 2304 Prints a usage message incorporating the message to stderr and 2305 exits. 2306 2307 If you override this in a subclass, it should not return -- it 2308 should either exit or raise an exception. 2309 """ 2310 self.print_usage(_sys.stderr) 2311 self.exit(2, _('%s: error: %s\n') % (self.prog, message)) 2312