python/compat/argparse.py

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