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