polly/utils/argparse.py

   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
  19 This 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
  25 The following is a simple usage example that sums integers from the
  26 command-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
  40 The 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
  72 All other classes in this module are considered implementation details.
  73 (Also note that HelpFormatter and RawDescriptionHelpFormatter are only
  74 considered public as object names -- the API of the formatter objects is
  75 still 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
  92 import copy as _copy
  93 import os as _os
  94 import re as _re
  95 import sys as _sys
  96 import textwrap as _textwrap
  97
  98 from gettext import gettext as _
  99
 100 try:
 101     _set = set
 102 except NameError:
 103     from sets import Set as _set
 104
 105 try:
 106     _basestring = basestring
 107 except NameError:
 108     _basestring = str
 109
 110 try:
 111     _sorted = sorted
 112 except 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
 122 def _callable(obj):
 123     return hasattr(obj, "__call__") or hasattr(obj, "__bases__")
 124
 125
 126 # silence Python 2.6 buggy warnings about Exception.message
 127 if _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
 138 SUPPRESS = "==SUPPRESS=="
 139
 140 OPTIONAL = "?"
 141 ZERO_OR_MORE = "*"
 142 ONE_OR_MORE = "+"
 143 PARSER = "A..."
 144 REMAINDER = "..."
 145
 146 # =============================
 147 # Utility functions and classes
 148 # =============================
 149
 150
 151 class _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
 176 def _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
 187 class 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
 654 class 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
 665 class 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
 676 class 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
 698 def _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
 711 class 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
 730 class 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
 741 class 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
 834 class _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
 873 class _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
 898 class _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
 910 class _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
 922 class _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
 963 class _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
 991 class _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
1007 class _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
1022 class _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
1044 class _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
1112 class 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
1157 class 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
1178 class _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
1468 class _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
1499 class _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
1518 class 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))