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