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

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