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