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