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