2354 lines · python
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 not6# use this file except in compliance with the License. You may obtain a copy7# of the License at8#9# http://www.apache.org/licenses/LICENSE-2.010#11# Unless required by applicable law or agreed to in writing, software12# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT13# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the14# License for the specific language governing permissions and limitations15# under the License.16 17"""Command-line parsing library18 19This module is an optparse-inspired command-line parsing library that:20 21 - handles both optional and positional arguments22 - produces highly informative usage messages23 - supports parsers that dispatch to sub-parsers24 25The following is a simple usage example that sums integers from the26command-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 the43 example above shows, the add_argument() method is used to populate44 the parser with actions for optional and positional arguments. Then45 the parse_args() method is invoked to convert the args at the46 command-line into an object with attributes.47 48 - ArgumentError -- The exception raised by ArgumentParser objects when49 there are errors with the parser's actions. Errors raised while50 parsing the command-line are caught by ArgumentParser and emitted51 as command-line messages.52 53 - FileType -- A factory for defining types of files to be created. As the54 example above shows, instances of FileType are typically passed as55 the type= argument of add_argument() calls.56 57 - Action -- The base class for parser actions. Typically actions are58 selected by passing strings like 'store_true' or 'append_const' to59 the action= argument of add_argument(). However, for greater60 customization of ArgumentParser actions, subclasses of Action may61 be defined and passed as the action= argument.62 63 - HelpFormatter, RawDescriptionHelpFormatter, RawTextHelpFormatter,64 ArgumentDefaultsHelpFormatter -- Formatter classes which65 may be passed as the formatter_class= argument to the66 ArgumentParser constructor. HelpFormatter is the default,67 RawDescriptionHelpFormatter and RawTextHelpFormatter tell the parser68 not to change the formatting for help text, and69 ArgumentDefaultsHelpFormatter adds information about argument defaults70 to the help.71 72All other classes in this module are considered implementation details.73(Also note that HelpFormatter and RawDescriptionHelpFormatter are only74considered public as object names -- the API of the formatter objects is75still 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 _copy93import os as _os94import re as _re95import sys as _sys96import textwrap as _textwrap97 98from gettext import gettext as _99 100try:101 _set = set102except NameError:103 from sets import Set as _set104 105try:106 _basestring = basestring107except NameError:108 _basestring = str109 110try:111 _sorted = sorted112except NameError:113 114 def _sorted(iterable, reverse=False):115 result = list(iterable)116 result.sort()117 if reverse:118 result.reverse()119 return result120 121 122def _callable(obj):123 return hasattr(obj, "__call__") or hasattr(obj, "__bases__")124 125 126# silence Python 2.6 buggy warnings about Exception.message127if _sys.version_info[:2] == (2, 6):128 import warnings129 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 classes148# =============================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 Help184# ===============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 methods191 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 width197 if width is None:198 try:199 width = int(_os.environ["COLUMNS"])200 except (KeyError, ValueError):201 width = 80202 width -= 2203 204 self._prog = prog205 self._indent_increment = indent_increment206 self._max_help_position = max_help_position207 self._width = width208 209 self._current_indent = 0210 self._level = 0211 self._action_max_length = 0212 213 self._root_section = self._Section(self, None)214 self._current_section = self._root_section215 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 methods221 # ===============================222 def _indent(self):223 self._current_indent += self._indent_increment224 self._level += 1225 226 def _dedent(self):227 self._current_indent -= self._indent_increment228 assert self._current_indent >= 0, "Indent decreased below 0."229 self._level -= 1230 231 class _Section(object):232 def __init__(self, formatter, parent, heading=None):233 self.formatter = formatter234 self.parent = parent235 self.heading = heading236 self.items = []237 238 def format_help(self):239 # format the indented section240 if self.parent is not None:241 self.formatter._indent()242 join = self.formatter._join_parts243 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 empty250 if not item_help:251 return ""252 253 # add the heading if the section was non-empty254 if self.heading is not SUPPRESS and self.heading is not None:255 current_indent = self.formatter._current_indent256 heading = "%*s%s:\n" % (current_indent, "", self.heading)257 else:258 heading = ""259 260 # join the section-initial newline, the heading and the help261 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 methods268 # ========================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 = section274 275 def end_section(self):276 self._current_section = self._current_section.parent277 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, prefix286 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 invocations292 get_invocation = self._format_action_invocation293 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 length298 invocation_length = max([len(s) for s in invocations])299 action_length = invocation_length + self._current_indent300 self._action_max_length = max(self._action_max_length, action_length)301 302 # add the item to the list303 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 methods311 # =======================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 help318 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 that327 if usage is not None:328 usage = usage % dict(prog=self._prog)329 330 # if no optionals or positionals are available, usage is just prog331 elif usage is None and not actions:332 usage = "%(prog)s" % dict(prog=self._prog)333 334 # if optionals and positionals are available, calculate usage335 elif usage is None:336 prog = "%(prog)s" % dict(prog=self._prog)337 338 # split optionals from positionals339 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 string348 format = self._format_actions_usage349 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 long353 text_width = self._width - self._current_indent354 if len(prefix) + len(usage) > text_width:355 356 # break usage into wrappable parts357 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_usage363 assert " ".join(pos_parts) == pos_usage364 365 # helper for wrapping lines366 def get_lines(parts, indent, prefix=None):367 lines = []368 line = []369 if prefix is not None:370 line_len = len(prefix) - 1371 else:372 line_len = len(indent) - 1373 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) - 1378 line.append(part)379 line_len += len(part) + 1380 if line:381 lines.append(indent + " ".join(line))382 if prefix is not None:383 lines[0] = lines[0][len(indent) :]384 return lines385 386 # if prog is short, follow it with optionals or positionals387 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 line398 else:399 indent = " " * len(prefix)400 parts = opt_parts + pos_parts401 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] + lines407 408 # join lines into usage409 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 groups416 group_actions = _set()417 inserts = {}418 for group in groups:419 try:420 start = actions.index(group._group_actions[0])421 except ValueError:422 continue423 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 strings438 parts = []439 for i, action in enumerate(actions):440 441 # suppressed arguments are marked with None442 # remove | separators for suppressed arguments443 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 strings451 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 list460 parts.append(part)461 462 # produce the first way to invoke the option in brackets463 else:464 option_string = action.option_strings[0]465 466 # if the Optional doesn't take a value, format is:467 # -s or --long468 if action.nargs == 0:469 part = "%s" % option_string470 471 # if the Optional takes a value, format is:472 # -s ARGS or --long ARGS473 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 group479 if not action.required and action not in group_actions:480 part = "[%s]" % part481 482 # add the action string to the list483 parts.append(part)484 485 # insert things at the necessary indices486 for i in _sorted(inserts, reverse=True):487 parts[i:i] = [inserts[i]]488 489 # join all the action items with spaces490 text = " ".join([item for item in parts if item is not None])491 492 # clean up separators for mutually exclusive groups493 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 text502 return text503 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_indent508 indent = " " * self._current_indent509 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 label513 help_position = min(self._action_max_length + 2, self._max_help_position)514 help_width = self._width - help_position515 action_width = help_position - self._current_indent - 2516 action_header = self._format_action_invocation(action)517 518 # ho nelp; start on same line and add a final newline519 if not action.help:520 tup = self._current_indent, "", action_header521 action_header = "%*s%s\n" % tup522 523 # short action name; start on the same line and pad two spaces524 elif len(action_header) <= action_width:525 tup = self._current_indent, "", action_width, action_header526 action_header = "%*s%-*s " % tup527 indent_first = 0528 529 # long action name; start on the next line530 else:531 tup = self._current_indent, "", action_header532 action_header = "%*s%s\n" % tup533 indent_first = help_position534 535 # collect the pieces of the action help536 parts = [action_header]537 538 # if there was help for the action, add lines of help text539 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 one547 elif not action_header.endswith("\n"):548 parts.append("\n")549 550 # if there are any sub-actions, add their help as well551 for subaction in self._iter_indented_subactions(action):552 parts.append(self._format_action(subaction))553 554 # return a single string555 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 metavar561 562 else:563 parts = []564 565 # if the Optional doesn't take a value, format is:566 # -s, --long567 if action.nargs == 0:568 parts.extend(action.option_strings)569 570 # if the Optional takes a value, format is:571 # -s ARGS, --long ARGS572 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.metavar583 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_metavar588 589 def format(tuple_size):590 if isinstance(result, tuple):591 return result592 else:593 return (result,) * tuple_size594 595 return format596 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 result615 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_str627 return self._get_help_string(action) % params628 629 def _iter_indented_subactions(self, action):630 try:631 get_subactions = action._get_subactions632 except AttributeError:633 pass634 else:635 self._indent()636 for subaction in get_subactions():637 yield subaction638 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=indent648 )649 650 def _get_help_string(self, action):651 return action.help652 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 methods658 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 methods669 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 methods680 provided by the class are considered an implementation detail.681 """682 683 def _get_help_string(self, action):684 help = action.help685 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 help691 692 693# =====================694# Options and Arguments695# =====================696 697 698def _get_action_name(argument):699 if argument is None:700 return None701 elif argument.option_strings:702 return "/".join(argument.option_strings)703 elif argument.metavar not in (None, SUPPRESS):704 return argument.metavar705 elif argument.dest not in (None, SUPPRESS):706 return argument.dest707 else:708 return None709 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 with715 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 = message721 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 pass734 735 736# ==============737# Action classes738# ==============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 information745 needed to parse a single argument from one or more strings from the746 command line. The keyword arguments to the Action constructor are also747 all attributes of Action instances.748 749 Keyword Arguments:750 751 - option_strings -- A list of command-line option strings which752 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 be757 consumed. By default, one argument will be consumed and a single758 value will be produced. Other values include:759 - N (an integer) consumes N arguments (and produces a list)760 - '?' consumes zero or one arguments761 - '*' 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 that764 with the default, a single value will be produced, while with765 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 the768 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 converted773 to, should be one of 'string', 'int', 'float', 'complex' or a774 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 appropriate779 type, an exception will be raised if it is not a member of this780 collection.781 782 - required -- True if the action must always be specified at the783 command line. This is only meaningful for optional command-line784 arguments.785 786 - help -- The help string describing the argument.787 788 - metavar -- The name to be used for the option's argument with the789 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_strings806 self.dest = dest807 self.nargs = nargs808 self.const = const809 self.default = default810 self.type = type811 self.choices = choices812 self.required = required813 self.help = help814 self.metavar = metavar815 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) + 11004 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=None1025 ):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 = version1034 1035 def __call__(self, parser, namespace, values, option_string=None):1036 version = self.version1037 if version is None:1038 version = parser.version1039 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=None1052 ):1053 1054 self._prog_prefix = prog1055 self._parser_class = parser_class1056 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 prefix1070 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 help1074 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 map1080 parser = self._parser_class(**kwargs)1081 self._name_parser_map[name] = parser1082 return parser1083 1084 def _get_subactions(self):1085 return self._choices_actions1086 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 requested1092 if self.dest is not SUPPRESS:1093 setattr(namespace, self.dest, parser_name)1094 1095 # select the parser1096 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 namespace1104 parser.parse_args(arg_strings, namespace)1105 1106 1107# ==============1108# Type classes1109# ==============1110 1111 1112class FileType(object):1113 """Factory for creating file object types1114 1115 Instances of FileType are typically passed as type= arguments to the1116 ArgumentParser add_argument() method.1117 1118 Keyword Arguments:1119 - mode -- A string indicating how the file is to be opened. Accepts the1120 same values as the builtin open() function.1121 - bufsize -- The file's desired buffer size. Accepts the same values as1122 the builtin open() function.1123 """1124 1125 def __init__(self, mode="r", bufsize=None):1126 self._mode = mode1127 self._bufsize = bufsize1128 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.stdin1134 elif "w" in self._mode:1135 return _sys.stdout1136 else:1137 msg = _('argument "-" with mode %r' % self._mode)1138 raise ValueError(msg)1139 1140 # all other arguments are used as file names1141 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 Parsing1154# ===========================1155 1156 1157class Namespace(_AttributeHolder):1158 """Simple object for storing attributes.1159 1160 Implements equality by attribute names and values, and provides a simple1161 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 = description1183 self.argument_default = argument_default1184 self.prefix_chars = prefix_chars1185 self.conflict_handler = conflict_handler1186 1187 # set up registries1188 self._registries = {}1189 1190 # register actions1191 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 invalid1204 self._get_handler()1205 1206 # action storage1207 self._actions = []1208 self._option_string_actions = {}1209 1210 # groups1211 self._action_groups = []1212 self._mutually_exclusive_groups = []1213 1214 # defaults storage1215 self._defaults = {}1216 1217 # determines whether an "option" looks like a negative number1218 self._negative_number_matcher = _re.compile(r"^-\d+$|^-\d*\.\d+$")1219 1220 # whether or not there are any optionals that look like negative1221 # numbers -- uses a list so it can be shared and edited1222 self._has_negative_number_optionals = []1223 1224 # ====================1225 # Registration methods1226 # ====================1227 def register(self, registry_name, value, object):1228 registry = self._registries.setdefault(registry_name, {})1229 registry[value] = object1230 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 methods1236 # ==================================1237 def set_defaults(self, **kwargs):1238 self._defaults.update(kwargs)1239 1240 # if these defaults match any existing arguments, replace1241 # the previous default on the object with the new one1242 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.default1250 return self._defaults.get(dest, None)1251 1252 # =======================1253 # Adding argument actions1254 # =======================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 and1262 # it doesn't look like an option string, parse a positional1263 # argument1264 chars = self.prefix_chars1265 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 argument1271 else:1272 kwargs = self._get_optional_kwargs(*args, **kwargs)1273 1274 # if no default was supplied, use the parser-level default1275 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_default1281 1282 # create the action object, and add it to the parser1283 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 callable1289 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 group1299 1300 def add_mutually_exclusive_group(self, **kwargs):1301 group = _MutuallyExclusiveGroup(self, **kwargs)1302 self._mutually_exclusive_groups.append(group)1303 return group1304 1305 def _add_action(self, action):1306 # resolve any conflicts1307 self._check_conflict(action)1308 1309 # add to actions list1310 self._actions.append(action)1311 action.container = self1312 1313 # index the action by any option strings it has1314 for option_string in action.option_strings:1315 self._option_string_actions[option_string] = action1316 1317 # set the flag if any option strings look like negative numbers1318 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 action1324 return action1325 1326 def _remove_action(self, action):1327 self._actions.remove(action)1328 1329 def _add_container_actions(self, container):1330 # collect groups by titles1331 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] = group1337 1338 # map each action to its group1339 group_map = {}1340 for group in container._action_groups:1341 1342 # if a group with the title exists, use that, otherwise1343 # create a new group matching the container's group1344 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 group1352 for action in group._group_actions:1353 group_map[action] = title_group_map[group.title]1354 1355 # add container's mutually exclusive groups1356 # NOTE: if add_mutually_exclusive_group ever gains title= and1357 # description= then this code will need to be expanded as above1358 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 group1362 for action in group._group_actions:1363 group_map[action] = mutex_group1364 1365 # add all actions to this container or their group1366 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 specified1371 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 is1376 # always required1377 if kwargs.get("nargs") not in [OPTIONAL, ZERO_OR_MORE]:1378 kwargs["required"] = True1379 if kwargs.get("nargs") == ZERO_OR_MORE and "default" not in kwargs:1380 kwargs["required"] = True1381 1382 # return the keyword arguments with no option strings1383 return dict(kwargs, dest=dest, option_strings=[])1384 1385 def _get_optional_kwargs(self, *args, **kwargs):1386 # determine short and long option strings1387 option_strings = []1388 long_option_strings = []1389 for option_string in args:1390 # error on strings that don't start with an appropriate prefix1391 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_chars1394 raise ValueError(msg % tup)1395 1396 # strings starting with two prefix characters are long options1397 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 arguments1417 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 string1425 handler_func_name = "_handle_conflict_%s" % self.conflict_handler1426 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 option1435 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 conflicts1442 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 options1456 for option_string, action in conflicting_actions:1457 1458 # remove the conflicting option1459 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 the1463 # container holding it1464 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 container1471 update = kwargs.setdefault1472 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 attributes1479 self.title = title1480 self._group_actions = []1481 1482 # share most attributes with the container1483 self._registries = container._registries1484 self._actions = container._actions1485 self._option_string_actions = container._option_string_actions1486 self._defaults = container._defaults1487 self._has_negative_number_optionals = container._has_negative_number_optionals1488 1489 def _add_action(self, action):1490 action = super(_ArgumentGroup, self)._add_action(action)1491 self._group_actions.append(action)1492 return action1493 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 = required1503 self._container = container1504 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 action1512 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 does1525 - epilog -- Text following the argument descriptions1526 - parents -- Parsers whose arguments should be copied into this one1527 - formatter_class -- HelpFormatter class for printing help messages1528 - prefix_chars -- Characters that prefix optional arguments1529 - fromfile_prefix_chars -- Characters that prefix files containing1530 additional arguments1531 - argument_default -- The default value for all arguments1532 - conflict_handler -- String indicating how to handle conflicts1533 - add_help -- Add a -h/-help option1534 """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 warnings1554 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 prog1572 if prog is None:1573 prog = _os.path.basename(_sys.argv[0])1574 1575 self.prog = prog1576 self.usage = usage1577 self.epilog = epilog1578 self.version = version1579 self.formatter_class = formatter_class1580 self.fromfile_prefix_chars = fromfile_prefix_chars1581 self.add_help = add_help1582 1583 add_group = self.add_argument_group1584 self._positionals = add_group(_("positional arguments"))1585 self._optionals = add_group(_("optional arguments"))1586 self._subparsers = None1587 1588 # register types1589 def identity(string):1590 return string1591 1592 self.register("type", None, identity)1593 1594 # add help and version arguments if necessary1595 # (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 defaults1615 for parent in parents:1616 self._add_container_actions(parent)1617 try:1618 defaults = parent._defaults1619 except AttributeError:1620 pass1621 else:1622 self._defaults.update(defaults)1623 1624 # =======================1625 # Pretty __repr__ methods1626 # =======================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 methods1641 # ==================================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 present1647 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._positionals1655 1656 # prog defaults to the usage message of this parser, skipping1657 # optional arguments and with no "usage:" prefix1658 if kwargs.get("prog") is None:1659 formatter = self._get_formatter()1660 positionals = self._get_positional_actions()1661 groups = self._mutually_exclusive_groups1662 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 list1666 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 action1671 return action1672 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 action1679 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 methods1688 # =====================================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 args1695 1696 def parse_known_args(self, args=None, namespace=None):1697 # args default to the system args1698 if args is None:1699 args = _sys.argv[1:]1700 1701 # default Namespace built from parser defaults1702 if namespace is None:1703 namespace = Namespace()1704 1705 # add any action defaults that aren't present1706 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.default1711 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 present1716 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 errors1721 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 references1729 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 arguments1733 # they can't occur with1734 action_conflicts = {}1735 for mutex_group in self._mutually_exclusive_groups:1736 group_actions = mutex_group._group_actions1737 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_pattern1743 # 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-options1751 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 strings1757 # and note the index if it was an option1758 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_tuple1764 pattern = "O"1765 arg_string_pattern_parts.append(pattern)1766 1767 # join the pieces together to form the pattern1768 arg_strings_pattern = "".join(arg_string_pattern_parts)1769 1770 # converts arg strings to the appropriate and then takes the action1771 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 previously1779 # seen arguments, assuming that actions that use the default1780 # 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 value1790 # (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 action1795 def consume_optional(start_index):1796 1797 # get the optional identified at this index1798 option_tuple = option_string_indices[start_index]1799 action, option_string, explicit_arg = option_tuple1800 1801 # identify additional optionals in the same arg string1802 # (e.g. -xyz is the same as -x -y -z if no args are required)1803 match_argument = self._match_argument1804 action_tuples = []1805 while True:1806 1807 # if we found no optional action, skip it1808 if action is None:1809 extras.append(arg_strings[start_index])1810 return start_index + 11811 1812 # if there is an explicit argument, try to match the1813 # optional's string arguments to only this1814 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 no1818 # arguments, try to parse more single-dash options out1819 # of the tail of the option string1820 chars = self.prefix_chars1821 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 None1826 optionals_map = self._option_string_actions1827 if option_string in optionals_map:1828 action = optionals_map[option_string]1829 break1830 else:1831 msg = _("ignored explicit argument %r")1832 raise ArgumentError(action, msg % explicit_arg)1833 1834 # if the action expect exactly one argument, we've1835 # successfully matched the option; exit the loop1836 elif arg_count == 1:1837 stop = start_index + 11838 args = [explicit_arg]1839 action_tuples.append((action, args, option_string))1840 break1841 1842 # error if a double-dash option did not use the1843 # explicit argument1844 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 the1849 # optional's string arguments with the following strings1850 # if successful, exit the loop1851 else:1852 start = start_index + 11853 selected_patterns = arg_strings_pattern[start:]1854 arg_count = match_argument(action, selected_patterns)1855 stop = start + arg_count1856 args = arg_strings[start:stop]1857 action_tuples.append((action, args, option_string))1858 break1859 1860 # add the Optional to the list and return the index at which1861 # the Optional's string args stopped1862 assert action_tuples1863 for action, args, option_string in action_tuples:1864 take_action(action, args, option_string)1865 return stop1866 1867 # the list of Positionals left to be parsed; this is modified1868 # by consume_positionals()1869 positionals = self._get_positional_actions()1870 1871 # function to convert arg_strings into positional actions1872 def consume_positionals(start_index):1873 # match as many Positionals as possible1874 match_partial = self._match_arguments_partial1875 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 Positional1879 # and add the Positional and its args to the list1880 for action, arg_count in zip(positionals, arg_counts):1881 args = arg_strings[start_index : start_index + arg_count]1882 start_index += arg_count1883 take_action(action, args)1884 1885 # slice off the Positionals that we just parsed and return the1886 # index at which the Positionals' string args stopped1887 positionals[:] = positionals[len(arg_counts) :]1888 return start_index1889 1890 # consume Positionals and Optionals alternately, until we have1891 # passed the last option string1892 extras = []1893 start_index = 01894 if option_string_indices:1895 max_option_string_index = max(option_string_indices)1896 else:1897 max_option_string_index = -11898 while start_index <= max_option_string_index:1899 1900 # consume any Positionals preceding the next option1901 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 consume1908 # the option string during the positionals parsing1909 if positionals_end_index > start_index:1910 start_index = positionals_end_index1911 continue1912 else:1913 start_index = positionals_end_index1914 1915 # if we consumed all the positionals we could and we're not1916 # at the index of an option string, there were extra arguments1917 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_index1921 1922 # consume the next optional and any arguments for it1923 start_index = consume_optional(start_index)1924 1925 # consume any positionals following the last Optional1926 stop_index = consume_positionals(start_index)1927 1928 # if we didn't consume all the argument strings, there were extras1929 extras.extend(arg_strings[stop_index:])1930 1931 # if we didn't use all the Positional objects, there were too few1932 # arg strings supplied.1933 if positionals:1934 self.error(_("too few arguments"))1935 1936 # make sure all required actions were present1937 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 present1944 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 break1949 1950 # if no actions were used, report the error1951 else:1952 names = [1953 _get_action_name(action)1954 for action in group._group_actions1955 if action.help is not SUPPRESS1956 ]1957 msg = _("one of the arguments %s is required")1958 self.error(msg % " ".join(names))1959 1960 # return the updated namespace and the extra arguments1961 return namespace, extras1962 1963 def _read_args_from_files(self, arg_strings):1964 # expand arguments referencing files1965 new_arg_strings = []1966 for arg_string in arg_strings:1967 1968 # for regular arguments, just add them back into the list1969 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 content1973 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 list1990 return new_arg_strings1991 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 strings1997 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 match2001 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.nargs2008 msg = nargs_errors.get(action.nargs, default)2009 raise ArgumentError(action, msg)2010 2011 # return the number of arguments matched2012 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 the2016 # final actions until we find a match2017 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 break2027 2028 # return the list of arg string counts2029 return result2030 2031 def _parse_optional(self, arg_string):2032 # if it's an empty string, it was meant to be a positional2033 if not arg_string:2034 return None2035 2036 # if it doesn't start with a prefix, it was meant to be positional2037 if not arg_string[0] in self.prefix_chars:2038 return None2039 2040 # if the option string is present in the parser, return the action2041 if arg_string in self._option_string_actions:2042 action = self._option_string_actions[arg_string]2043 return action, arg_string, None2044 2045 # if it's just a single character, it was meant to be positional2046 if len(arg_string) == 1:2047 return None2048 2049 # if the option string before the "=" is present, return the action2050 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_arg2055 2056 # search through all possible prefixes of the option string2057 # and all actions in the parser for possible interpretations2058 option_tuples = self._get_option_tuples(arg_string)2059 2060 # if multiple actions match, the option string was ambiguous2061 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, options2066 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 action2070 elif len(option_tuples) == 1:2071 (option_tuple,) = option_tuples2072 return option_tuple2073 2074 # if it was not found as an option, but it looks like a negative2075 # number, it was meant to be positional2076 # unless there are negative-number-like options2077 if self._negative_number_matcher.match(arg_string):2078 if not self._has_negative_number_optionals:2079 return None2080 2081 # if it contains a space, it was meant to be a positional2082 if " " in arg_string:2083 return None2084 2085 # it was meant to be an optional but there is no such option2086 # in this parser (though it might be a valid option in a subparser)2087 return None, arg_string, None2088 2089 def _get_option_tuples(self, option_string):2090 result = []2091 2092 # option strings starting with two prefix characters are only2093 # split at the '='2094 chars = self.prefix_chars2095 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_string2100 explicit_arg = None2101 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_arg2105 result.append(tup)2106 2107 # single character options can be concatenated with their arguments2108 # but multiple character options always have to have their argument2109 # separate2110 elif option_string[0] in chars and option_string[1] not in chars:2111 option_prefix = option_string2112 explicit_arg = None2113 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_arg2120 result.append(tup)2121 elif option_string.startswith(option_prefix):2122 action = self._option_string_actions[option_string]2123 tup = action, option_string, explicit_arg2124 result.append(tup)2125 2126 # shouldn't ever get here2127 else:2128 self.error(_("unexpected option string: %s") % option_string)2129 2130 # return the collected option tuples2131 return result2132 2133 def _get_nargs_pattern(self, action):2134 # in all examples below, we have to allow for '--' args2135 # which are represented as '-' in the pattern2136 nargs = action.nargs2137 2138 # the default (None) is assumed to be a single argument2139 if nargs is None:2140 nargs_pattern = "(-*A-*)"2141 2142 # allow zero or one arguments2143 elif nargs == OPTIONAL:2144 nargs_pattern = "(-*A?-*)"2145 2146 # allow zero or more arguments2147 elif nargs == ZERO_OR_MORE:2148 nargs_pattern = "(-*[A-]*)"2149 2150 # allow one or more arguments2151 elif nargs == ONE_OR_MORE:2152 nargs_pattern = "(-*A[A-]*)"2153 2154 # allow any number of options or arguments2155 elif nargs == REMAINDER:2156 nargs_pattern = "([-AO]*)"2157 2158 # allow one argument followed by any number of options or arguments2159 elif nargs == PARSER:2160 nargs_pattern = "(-*A[-AO]*)"2161 2162 # all others should be integers2163 else:2164 nargs_pattern = "(-*%s-*)" % "-*".join("A" * nargs)2165 2166 # if this is an optional action, -- is not allowed2167 if action.option_strings:2168 nargs_pattern = nargs_pattern.replace("-*", "")2169 nargs_pattern = nargs_pattern.replace("-", "")2170 2171 # return the pattern2172 return nargs_pattern2173 2174 # ========================2175 # Value conversion methods2176 # ========================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 present2183 if not arg_strings and action.nargs == OPTIONAL:2184 if action.option_strings:2185 value = action.const2186 else:2187 value = action.default2188 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-line2193 # args, use the default if it is anything other than None2194 elif (2195 not arg_strings2196 and action.nargs == ZERO_OR_MORE2197 and not action.option_strings2198 ):2199 if action.default is not None:2200 value = action.default2201 else:2202 value = arg_strings2203 self._check_value(action, value)2204 2205 # single argument or optional argument produces a single value2206 elif len(arg_strings) == 1 and action.nargs in [None, OPTIONAL]:2207 (arg_string,) = arg_strings2208 value = self._get_value(action, arg_string)2209 self._check_value(action, value)2210 2211 # REMAINDER arguments convert all values, checking none2212 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 first2216 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 list2221 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 value2227 return value2228 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 type2236 try:2237 result = type_func(arg_string)2238 2239 # ArgumentTypeErrors indicate errors2240 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 errors2246 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 value2252 return result2253 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)") % tup2259 raise ArgumentError(action, msg)2260 2261 # =======================2262 # Help-formatting methods2263 # =======================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 # usage2273 formatter.add_usage(self.usage, self._actions, self._mutually_exclusive_groups)2274 2275 # description2276 formatter.add_text(self.description)2277 2278 # positionals, optionals and user-defined groups2279 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 # epilog2286 formatter.add_text(self.epilog)2287 2288 # determine help from format above2289 return formatter.format_help()2290 2291 def format_version(self):2292 import warnings2293 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 methods2308 # =====================2309 def print_usage(self, file=None):2310 if file is None:2311 file = _sys.stdout2312 self._print_message(self.format_usage(), file)2313 2314 def print_help(self, file=None):2315 if file is None:2316 file = _sys.stdout2317 self._print_message(self.format_help(), file)2318 2319 def print_version(self, file=None):2320 import warnings2321 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.stderr2333 file.write(message)2334 2335 # ===============2336 # Exiting methods2337 # ===============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 and2347 exits.2348 2349 If you override this in a subclass, it should not return -- it2350 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