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