AppPkg/Applications/Python/Python-2.7.2/Lib/argparse.py

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