Lib/argparse.py

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