PageRenderTime 417ms CodeModel.GetById 81ms app.highlight 235ms RepoModel.GetById 46ms app.codeStats 1ms

/lib-python/2/argparse.py

https://bitbucket.org/kcr/pypy
Python | 2347 lines | 1948 code | 168 blank | 231 comment | 309 complexity | cf662eb0ae9e5a0f53e15fd50cc9d19d MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1# Author: Steven J. Bethard <steven.bethard@gmail.com>.
   2
   3"""Command-line parsing library
   4
   5This 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
  11The following is a simple usage example that sums integers from the
  12command-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
  26The 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
  58All other classes in this module are considered implementation details.
  59(Also note that HelpFormatter and RawDescriptionHelpFormatter are only
  60considered public as object names -- the API of the formatter objects is
  61still 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
  85import collections as _collections
  86import copy as _copy
  87import os as _os
  88import re as _re
  89import sys as _sys
  90import textwrap as _textwrap
  91
  92from gettext import gettext as _
  93
  94
  95def _callable(obj):
  96    return hasattr(obj, '__call__') or hasattr(obj, '__bases__')
  97
  98
  99SUPPRESS = '==SUPPRESS=='
 100
 101OPTIONAL = '?'
 102ZERO_OR_MORE = '*'
 103ONE_OR_MORE = '+'
 104PARSER = 'A...'
 105REMAINDER = '...'
 106_UNRECOGNIZED_ARGS_ATTR = '_unrecognized_args'
 107
 108# =============================
 109# Utility functions and classes
 110# =============================
 111
 112class _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
 137def _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
 147class HelpFormatter(object):
 148    """Formatter for generating usage messages and argument help strings.
 149
 150    Only the name of this class is considered a public API. All the methods
 151    provided by the class are considered an implementation detail.
 152    """
 153
 154    def __init__(self,
 155                 prog,
 156                 indent_increment=2,
 157                 max_help_position=24,
 158                 width=None):
 159
 160        # default setting for width
 161        if width is None:
 162            try:
 163                width = int(_os.environ['COLUMNS'])
 164            except (KeyError, ValueError):
 165                width = 80
 166            width -= 2
 167
 168        self._prog = prog
 169        self._indent_increment = indent_increment
 170        self._max_help_position = max_help_position
 171        self._width = width
 172
 173        self._current_indent = 0
 174        self._level = 0
 175        self._action_max_length = 0
 176
 177        self._root_section = self._Section(self, None)
 178        self._current_section = self._root_section
 179
 180        self._whitespace_matcher = _re.compile(r'\s+')
 181        self._long_break_matcher = _re.compile(r'\n\n\n+')
 182
 183    # ===============================
 184    # Section and indentation methods
 185    # ===============================
 186    def _indent(self):
 187        self._current_indent += self._indent_increment
 188        self._level += 1
 189
 190    def _dedent(self):
 191        self._current_indent -= self._indent_increment
 192        assert self._current_indent >= 0, 'Indent decreased below 0.'
 193        self._level -= 1
 194
 195    class _Section(object):
 196
 197        def __init__(self, formatter, parent, heading=None):
 198            self.formatter = formatter
 199            self.parent = parent
 200            self.heading = heading
 201            self.items = []
 202
 203        def format_help(self):
 204            # format the indented section
 205            if self.parent is not None:
 206                self.formatter._indent()
 207            join = self.formatter._join_parts
 208            for func, args in self.items:
 209                func(*args)
 210            item_help = join([func(*args) for func, args in self.items])
 211            if self.parent is not None:
 212                self.formatter._dedent()
 213
 214            # return nothing if the section was empty
 215            if not item_help:
 216                return ''
 217
 218            # add the heading if the section was non-empty
 219            if self.heading is not SUPPRESS and self.heading is not None:
 220                current_indent = self.formatter._current_indent
 221                heading = '%*s%s:\n' % (current_indent, '', self.heading)
 222            else:
 223                heading = ''
 224
 225            # join the section-initial newline, the heading and the help
 226            return join(['\n', heading, item_help, '\n'])
 227
 228    def _add_item(self, func, args):
 229        self._current_section.items.append((func, args))
 230
 231    # ========================
 232    # Message building methods
 233    # ========================
 234    def start_section(self, heading):
 235        self._indent()
 236        section = self._Section(self, self._current_section, heading)
 237        self._add_item(section.format_help, [])
 238        self._current_section = section
 239
 240    def end_section(self):
 241        self._current_section = self._current_section.parent
 242        self._dedent()
 243
 244    def add_text(self, text):
 245        if text is not SUPPRESS and text is not None:
 246            self._add_item(self._format_text, [text])
 247
 248    def add_usage(self, usage, actions, groups, prefix=None):
 249        if usage is not SUPPRESS:
 250            args = usage, actions, groups, prefix
 251            self._add_item(self._format_usage, args)
 252
 253    def add_argument(self, action):
 254        if action.help is not SUPPRESS:
 255
 256            # find all invocations
 257            get_invocation = self._format_action_invocation
 258            invocations = [get_invocation(action)]
 259            for subaction in self._iter_indented_subactions(action):
 260                invocations.append(get_invocation(subaction))
 261
 262            # update the maximum item length
 263            invocation_length = max([len(s) for s in invocations])
 264            action_length = invocation_length + self._current_indent
 265            self._action_max_length = max(self._action_max_length,
 266                                          action_length)
 267
 268            # add the item to the list
 269            self._add_item(self._format_action, [action])
 270
 271    def add_arguments(self, actions):
 272        for action in actions:
 273            self.add_argument(action)
 274
 275    # =======================
 276    # Help-formatting methods
 277    # =======================
 278    def format_help(self):
 279        help = self._root_section.format_help()
 280        if help:
 281            help = self._long_break_matcher.sub('\n\n', help)
 282            help = help.strip('\n') + '\n'
 283        return help
 284
 285    def _join_parts(self, part_strings):
 286        return ''.join([part
 287                        for part in part_strings
 288                        if part and part is not SUPPRESS])
 289
 290    def _format_usage(self, usage, actions, groups, prefix):
 291        if prefix is None:
 292            prefix = _('usage: ')
 293
 294        # if usage is specified, use that
 295        if usage is not None:
 296            usage = usage % dict(prog=self._prog)
 297
 298        # if no optionals or positionals are available, usage is just prog
 299        elif usage is None and not actions:
 300            usage = '%(prog)s' % dict(prog=self._prog)
 301
 302        # if optionals and positionals are available, calculate usage
 303        elif usage is None:
 304            prog = '%(prog)s' % dict(prog=self._prog)
 305
 306            # split optionals from positionals
 307            optionals = []
 308            positionals = []
 309            for action in actions:
 310                if action.option_strings:
 311                    optionals.append(action)
 312                else:
 313                    positionals.append(action)
 314
 315            # build full usage string
 316            format = self._format_actions_usage
 317            action_usage = format(optionals + positionals, groups)
 318            usage = ' '.join([s for s in [prog, action_usage] if s])
 319
 320            # wrap the usage parts if it's too long
 321            text_width = self._width - self._current_indent
 322            if len(prefix) + len(usage) > text_width:
 323
 324                # break usage into wrappable parts
 325                part_regexp = r'\(.*?\)+|\[.*?\]+|\S+'
 326                opt_usage = format(optionals, groups)
 327                pos_usage = format(positionals, groups)
 328                opt_parts = _re.findall(part_regexp, opt_usage)
 329                pos_parts = _re.findall(part_regexp, pos_usage)
 330                assert ' '.join(opt_parts) == opt_usage
 331                assert ' '.join(pos_parts) == pos_usage
 332
 333                # helper for wrapping lines
 334                def get_lines(parts, indent, prefix=None):
 335                    lines = []
 336                    line = []
 337                    if prefix is not None:
 338                        line_len = len(prefix) - 1
 339                    else:
 340                        line_len = len(indent) - 1
 341                    for part in parts:
 342                        if line_len + 1 + len(part) > text_width:
 343                            lines.append(indent + ' '.join(line))
 344                            line = []
 345                            line_len = len(indent) - 1
 346                        line.append(part)
 347                        line_len += len(part) + 1
 348                    if line:
 349                        lines.append(indent + ' '.join(line))
 350                    if prefix is not None:
 351                        lines[0] = lines[0][len(indent):]
 352                    return lines
 353
 354                # if prog is short, follow it with optionals or positionals
 355                if len(prefix) + len(prog) <= 0.75 * text_width:
 356                    indent = ' ' * (len(prefix) + len(prog) + 1)
 357                    if opt_parts:
 358                        lines = get_lines([prog] + opt_parts, indent, prefix)
 359                        lines.extend(get_lines(pos_parts, indent))
 360                    elif pos_parts:
 361                        lines = get_lines([prog] + pos_parts, indent, prefix)
 362                    else:
 363                        lines = [prog]
 364
 365                # if prog is long, put it on its own line
 366                else:
 367                    indent = ' ' * len(prefix)
 368                    parts = opt_parts + pos_parts
 369                    lines = get_lines(parts, indent)
 370                    if len(lines) > 1:
 371                        lines = []
 372                        lines.extend(get_lines(opt_parts, indent))
 373                        lines.extend(get_lines(pos_parts, indent))
 374                    lines = [prog] + lines
 375
 376                # join lines into usage
 377                usage = '\n'.join(lines)
 378
 379        # prefix with 'usage:'
 380        return '%s%s\n\n' % (prefix, usage)
 381
 382    def _format_actions_usage(self, actions, groups):
 383        # find group indices and identify actions in groups
 384        group_actions = set()
 385        inserts = {}
 386        for group in groups:
 387            try:
 388                start = actions.index(group._group_actions[0])
 389            except ValueError:
 390                continue
 391            else:
 392                end = start + len(group._group_actions)
 393                if actions[start:end] == group._group_actions:
 394                    for action in group._group_actions:
 395                        group_actions.add(action)
 396                    if not group.required:
 397                        if start in inserts:
 398                            inserts[start] += ' ['
 399                        else:
 400                            inserts[start] = '['
 401                        inserts[end] = ']'
 402                    else:
 403                        if start in inserts:
 404                            inserts[start] += ' ('
 405                        else:
 406                            inserts[start] = '('
 407                        inserts[end] = ')'
 408                    for i in range(start + 1, end):
 409                        inserts[i] = '|'
 410
 411        # collect all actions format strings
 412        parts = []
 413        for i, action in enumerate(actions):
 414
 415            # suppressed arguments are marked with None
 416            # remove | separators for suppressed arguments
 417            if action.help is SUPPRESS:
 418                parts.append(None)
 419                if inserts.get(i) == '|':
 420                    inserts.pop(i)
 421                elif inserts.get(i + 1) == '|':
 422                    inserts.pop(i + 1)
 423
 424            # produce all arg strings
 425            elif not action.option_strings:
 426                part = self._format_args(action, action.dest)
 427
 428                # if it's in a group, strip the outer []
 429                if action in group_actions:
 430                    if part[0] == '[' and part[-1] == ']':
 431                        part = part[1:-1]
 432
 433                # add the action string to the list
 434                parts.append(part)
 435
 436            # produce the first way to invoke the option in brackets
 437            else:
 438                option_string = action.option_strings[0]
 439
 440                # if the Optional doesn't take a value, format is:
 441                #    -s or --long
 442                if action.nargs == 0:
 443                    part = '%s' % option_string
 444
 445                # if the Optional takes a value, format is:
 446                #    -s ARGS or --long ARGS
 447                else:
 448                    default = action.dest.upper()
 449                    args_string = self._format_args(action, default)
 450                    part = '%s %s' % (option_string, args_string)
 451
 452                # make it look optional if it's not required or in a group
 453                if not action.required and action not in group_actions:
 454                    part = '[%s]' % part
 455
 456                # add the action string to the list
 457                parts.append(part)
 458
 459        # insert things at the necessary indices
 460        for i in sorted(inserts, reverse=True):
 461            parts[i:i] = [inserts[i]]
 462
 463        # join all the action items with spaces
 464        text = ' '.join([item for item in parts if item is not None])
 465
 466        # clean up separators for mutually exclusive groups
 467        open = r'[\[(]'
 468        close = r'[\])]'
 469        text = _re.sub(r'(%s) ' % open, r'\1', text)
 470        text = _re.sub(r' (%s)' % close, r'\1', text)
 471        text = _re.sub(r'%s *%s' % (open, close), r'', text)
 472        text = _re.sub(r'\(([^|]*)\)', r'\1', text)
 473        text = text.strip()
 474
 475        # return the text
 476        return text
 477
 478    def _format_text(self, text):
 479        if '%(prog)' in text:
 480            text = text % dict(prog=self._prog)
 481        text_width = self._width - self._current_indent
 482        indent = ' ' * self._current_indent
 483        return self._fill_text(text, text_width, indent) + '\n\n'
 484
 485    def _format_action(self, action):
 486        # determine the required width and the entry label
 487        help_position = min(self._action_max_length + 2,
 488                            self._max_help_position)
 489        help_width = self._width - help_position
 490        action_width = help_position - self._current_indent - 2
 491        action_header = self._format_action_invocation(action)
 492
 493        # ho nelp; start on same line and add a final newline
 494        if not action.help:
 495            tup = self._current_indent, '', action_header
 496            action_header = '%*s%s\n' % tup
 497
 498        # short action name; start on the same line and pad two spaces
 499        elif len(action_header) <= action_width:
 500            tup = self._current_indent, '', action_width, action_header
 501            action_header = '%*s%-*s  ' % tup
 502            indent_first = 0
 503
 504        # long action name; start on the next line
 505        else:
 506            tup = self._current_indent, '', action_header
 507            action_header = '%*s%s\n' % tup
 508            indent_first = help_position
 509
 510        # collect the pieces of the action help
 511        parts = [action_header]
 512
 513        # if there was help for the action, add lines of help text
 514        if action.help:
 515            help_text = self._expand_help(action)
 516            help_lines = self._split_lines(help_text, help_width)
 517            parts.append('%*s%s\n' % (indent_first, '', help_lines[0]))
 518            for line in help_lines[1:]:
 519                parts.append('%*s%s\n' % (help_position, '', line))
 520
 521        # or add a newline if the description doesn't end with one
 522        elif not action_header.endswith('\n'):
 523            parts.append('\n')
 524
 525        # if there are any sub-actions, add their help as well
 526        for subaction in self._iter_indented_subactions(action):
 527            parts.append(self._format_action(subaction))
 528
 529        # return a single string
 530        return self._join_parts(parts)
 531
 532    def _format_action_invocation(self, action):
 533        if not action.option_strings:
 534            metavar, = self._metavar_formatter(action, action.dest)(1)
 535            return metavar
 536
 537        else:
 538            parts = []
 539
 540            # if the Optional doesn't take a value, format is:
 541            #    -s, --long
 542            if action.nargs == 0:
 543                parts.extend(action.option_strings)
 544
 545            # if the Optional takes a value, format is:
 546            #    -s ARGS, --long ARGS
 547            else:
 548                default = action.dest.upper()
 549                args_string = self._format_args(action, default)
 550                for option_string in action.option_strings:
 551                    parts.append('%s %s' % (option_string, args_string))
 552
 553            return ', '.join(parts)
 554
 555    def _metavar_formatter(self, action, default_metavar):
 556        if action.metavar is not None:
 557            result = action.metavar
 558        elif action.choices is not None:
 559            choice_strs = [str(choice) for choice in action.choices]
 560            result = '{%s}' % ','.join(choice_strs)
 561        else:
 562            result = default_metavar
 563
 564        def format(tuple_size):
 565            if isinstance(result, tuple):
 566                return result
 567            else:
 568                return (result, ) * tuple_size
 569        return format
 570
 571    def _format_args(self, action, default_metavar):
 572        get_metavar = self._metavar_formatter(action, default_metavar)
 573        if action.nargs is None:
 574            result = '%s' % get_metavar(1)
 575        elif action.nargs == OPTIONAL:
 576            result = '[%s]' % get_metavar(1)
 577        elif action.nargs == ZERO_OR_MORE:
 578            result = '[%s [%s ...]]' % get_metavar(2)
 579        elif action.nargs == ONE_OR_MORE:
 580            result = '%s [%s ...]' % get_metavar(2)
 581        elif action.nargs == REMAINDER:
 582            result = '...'
 583        elif action.nargs == PARSER:
 584            result = '%s ...' % get_metavar(1)
 585        else:
 586            formats = ['%s' for _ in range(action.nargs)]
 587            result = ' '.join(formats) % get_metavar(action.nargs)
 588        return result
 589
 590    def _expand_help(self, action):
 591        params = dict(vars(action), prog=self._prog)
 592        for name in list(params):
 593            if params[name] is SUPPRESS:
 594                del params[name]
 595        for name in list(params):
 596            if hasattr(params[name], '__name__'):
 597                params[name] = params[name].__name__
 598        if params.get('choices') is not None:
 599            choices_str = ', '.join([str(c) for c in params['choices']])
 600            params['choices'] = choices_str
 601        return self._get_help_string(action) % params
 602
 603    def _iter_indented_subactions(self, action):
 604        try:
 605            get_subactions = action._get_subactions
 606        except AttributeError:
 607            pass
 608        else:
 609            self._indent()
 610            for subaction in get_subactions():
 611                yield subaction
 612            self._dedent()
 613
 614    def _split_lines(self, text, width):
 615        text = self._whitespace_matcher.sub(' ', text).strip()
 616        return _textwrap.wrap(text, width)
 617
 618    def _fill_text(self, text, width, indent):
 619        text = self._whitespace_matcher.sub(' ', text).strip()
 620        return _textwrap.fill(text, width, initial_indent=indent,
 621                                           subsequent_indent=indent)
 622
 623    def _get_help_string(self, action):
 624        return action.help
 625
 626
 627class RawDescriptionHelpFormatter(HelpFormatter):
 628    """Help message formatter which retains any formatting in descriptions.
 629
 630    Only the name of this class is considered a public API. All the methods
 631    provided by the class are considered an implementation detail.
 632    """
 633
 634    def _fill_text(self, text, width, indent):
 635        return ''.join([indent + line for line in text.splitlines(True)])
 636
 637
 638class RawTextHelpFormatter(RawDescriptionHelpFormatter):
 639    """Help message formatter which retains formatting of all help text.
 640
 641    Only the name of this class is considered a public API. All the methods
 642    provided by the class are considered an implementation detail.
 643    """
 644
 645    def _split_lines(self, text, width):
 646        return text.splitlines()
 647
 648
 649class ArgumentDefaultsHelpFormatter(HelpFormatter):
 650    """Help message formatter which adds default values to argument help.
 651
 652    Only the name of this class is considered a public API. All the methods
 653    provided by the class are considered an implementation detail.
 654    """
 655
 656    def _get_help_string(self, action):
 657        help = action.help
 658        if '%(default)' not in action.help:
 659            if action.default is not SUPPRESS:
 660                defaulting_nargs = [OPTIONAL, ZERO_OR_MORE]
 661                if action.option_strings or action.nargs in defaulting_nargs:
 662                    help += ' (default: %(default)s)'
 663        return help
 664
 665
 666# =====================
 667# Options and Arguments
 668# =====================
 669
 670def _get_action_name(argument):
 671    if argument is None:
 672        return None
 673    elif argument.option_strings:
 674        return  '/'.join(argument.option_strings)
 675    elif argument.metavar not in (None, SUPPRESS):
 676        return argument.metavar
 677    elif argument.dest not in (None, SUPPRESS):
 678        return argument.dest
 679    else:
 680        return None
 681
 682
 683class ArgumentError(Exception):
 684    """An error from creating or using an argument (optional or positional).
 685
 686    The string value of this exception is the message, augmented with
 687    information about the argument that caused it.
 688    """
 689
 690    def __init__(self, argument, message):
 691        self.argument_name = _get_action_name(argument)
 692        self.message = message
 693
 694    def __str__(self):
 695        if self.argument_name is None:
 696            format = '%(message)s'
 697        else:
 698            format = 'argument %(argument_name)s: %(message)s'
 699        return format % dict(message=self.message,
 700                             argument_name=self.argument_name)
 701
 702
 703class ArgumentTypeError(Exception):
 704    """An error from trying to convert a command line string to a type."""
 705    pass
 706
 707
 708# ==============
 709# Action classes
 710# ==============
 711
 712class Action(_AttributeHolder):
 713    """Information about how to convert command line strings to Python objects.
 714
 715    Action objects are used by an ArgumentParser to represent the information
 716    needed to parse a single argument from one or more strings from the
 717    command line. The keyword arguments to the Action constructor are also
 718    all attributes of Action instances.
 719
 720    Keyword Arguments:
 721
 722        - option_strings -- A list of command-line option strings which
 723            should be associated with this action.
 724
 725        - dest -- The name of the attribute to hold the created object(s)
 726
 727        - nargs -- The number of command-line arguments that should be
 728            consumed. By default, one argument will be consumed and a single
 729            value will be produced.  Other values include:
 730                - N (an integer) consumes N arguments (and produces a list)
 731                - '?' consumes zero or one arguments
 732                - '*' consumes zero or more arguments (and produces a list)
 733                - '+' consumes one or more arguments (and produces a list)
 734            Note that the difference between the default and nargs=1 is that
 735            with the default, a single value will be produced, while with
 736            nargs=1, a list containing a single value will be produced.
 737
 738        - const -- The value to be produced if the option is specified and the
 739            option uses an action that takes no values.
 740
 741        - default -- The value to be produced if the option is not specified.
 742
 743        - type -- The type which the command-line arguments should be converted
 744            to, should be one of 'string', 'int', 'float', 'complex' or a
 745            callable object that accepts a single string argument. If None,
 746            'string' is assumed.
 747
 748        - choices -- A container of values that should be allowed. If not None,
 749            after a command-line argument has been converted to the appropriate
 750            type, an exception will be raised if it is not a member of this
 751            collection.
 752
 753        - required -- True if the action must always be specified at the
 754            command line. This is only meaningful for optional command-line
 755            arguments.
 756
 757        - help -- The help string describing the argument.
 758
 759        - metavar -- The name to be used for the option's argument with the
 760            help string. If None, the 'dest' value will be used as the name.
 761    """
 762
 763    def __init__(self,
 764                 option_strings,
 765                 dest,
 766                 nargs=None,
 767                 const=None,
 768                 default=None,
 769                 type=None,
 770                 choices=None,
 771                 required=False,
 772                 help=None,
 773                 metavar=None):
 774        self.option_strings = option_strings
 775        self.dest = dest
 776        self.nargs = nargs
 777        self.const = const
 778        self.default = default
 779        self.type = type
 780        self.choices = choices
 781        self.required = required
 782        self.help = help
 783        self.metavar = metavar
 784
 785    def _get_kwargs(self):
 786        names = [
 787            'option_strings',
 788            'dest',
 789            'nargs',
 790            'const',
 791            'default',
 792            'type',
 793            'choices',
 794            'help',
 795            'metavar',
 796        ]
 797        return [(name, getattr(self, name)) for name in names]
 798
 799    def __call__(self, parser, namespace, values, option_string=None):
 800        raise NotImplementedError(_('.__call__() not defined'))
 801
 802
 803class _StoreAction(Action):
 804
 805    def __init__(self,
 806                 option_strings,
 807                 dest,
 808                 nargs=None,
 809                 const=None,
 810                 default=None,
 811                 type=None,
 812                 choices=None,
 813                 required=False,
 814                 help=None,
 815                 metavar=None):
 816        if nargs == 0:
 817            raise ValueError('nargs for store actions must be > 0; if you '
 818                             'have nothing to store, actions such as store '
 819                             'true or store const may be more appropriate')
 820        if const is not None and nargs != OPTIONAL:
 821            raise ValueError('nargs must be %r to supply const' % OPTIONAL)
 822        super(_StoreAction, self).__init__(
 823            option_strings=option_strings,
 824            dest=dest,
 825            nargs=nargs,
 826            const=const,
 827            default=default,
 828            type=type,
 829            choices=choices,
 830            required=required,
 831            help=help,
 832            metavar=metavar)
 833
 834    def __call__(self, parser, namespace, values, option_string=None):
 835        setattr(namespace, self.dest, values)
 836
 837
 838class _StoreConstAction(Action):
 839
 840    def __init__(self,
 841                 option_strings,
 842                 dest,
 843                 const,
 844                 default=None,
 845                 required=False,
 846                 help=None,
 847                 metavar=None):
 848        super(_StoreConstAction, self).__init__(
 849            option_strings=option_strings,
 850            dest=dest,
 851            nargs=0,
 852            const=const,
 853            default=default,
 854            required=required,
 855            help=help)
 856
 857    def __call__(self, parser, namespace, values, option_string=None):
 858        setattr(namespace, self.dest, self.const)
 859
 860
 861class _StoreTrueAction(_StoreConstAction):
 862
 863    def __init__(self,
 864                 option_strings,
 865                 dest,
 866                 default=False,
 867                 required=False,
 868                 help=None):
 869        super(_StoreTrueAction, self).__init__(
 870            option_strings=option_strings,
 871            dest=dest,
 872            const=True,
 873            default=default,
 874            required=required,
 875            help=help)
 876
 877
 878class _StoreFalseAction(_StoreConstAction):
 879
 880    def __init__(self,
 881                 option_strings,
 882                 dest,
 883                 default=True,
 884                 required=False,
 885                 help=None):
 886        super(_StoreFalseAction, self).__init__(
 887            option_strings=option_strings,
 888            dest=dest,
 889            const=False,
 890            default=default,
 891            required=required,
 892            help=help)
 893
 894
 895class _AppendAction(Action):
 896
 897    def __init__(self,
 898                 option_strings,
 899                 dest,
 900                 nargs=None,
 901                 const=None,
 902                 default=None,
 903                 type=None,
 904                 choices=None,
 905                 required=False,
 906                 help=None,
 907                 metavar=None):
 908        if nargs == 0:
 909            raise ValueError('nargs for append actions must be > 0; if arg '
 910                             'strings are not supplying the value to append, '
 911                             'the append const action may be more appropriate')
 912        if const is not None and nargs != OPTIONAL:
 913            raise ValueError('nargs must be %r to supply const' % OPTIONAL)
 914        super(_AppendAction, self).__init__(
 915            option_strings=option_strings,
 916            dest=dest,
 917            nargs=nargs,
 918            const=const,
 919            default=default,
 920            type=type,
 921            choices=choices,
 922            required=required,
 923            help=help,
 924            metavar=metavar)
 925
 926    def __call__(self, parser, namespace, values, option_string=None):
 927        items = _copy.copy(_ensure_value(namespace, self.dest, []))
 928        items.append(values)
 929        setattr(namespace, self.dest, items)
 930
 931
 932class _AppendConstAction(Action):
 933
 934    def __init__(self,
 935                 option_strings,
 936                 dest,
 937                 const,
 938                 default=None,
 939                 required=False,
 940                 help=None,
 941                 metavar=None):
 942        super(_AppendConstAction, self).__init__(
 943            option_strings=option_strings,
 944            dest=dest,
 945            nargs=0,
 946            const=const,
 947            default=default,
 948            required=required,
 949            help=help,
 950            metavar=metavar)
 951
 952    def __call__(self, parser, namespace, values, option_string=None):
 953        items = _copy.copy(_ensure_value(namespace, self.dest, []))
 954        items.append(self.const)
 955        setattr(namespace, self.dest, items)
 956
 957
 958class _CountAction(Action):
 959
 960    def __init__(self,
 961                 option_strings,
 962                 dest,
 963                 default=None,
 964                 required=False,
 965                 help=None):
 966        super(_CountAction, self).__init__(
 967            option_strings=option_strings,
 968            dest=dest,
 969            nargs=0,
 970            default=default,
 971            required=required,
 972            help=help)
 973
 974    def __call__(self, parser, namespace, values, option_string=None):
 975        new_count = _ensure_value(namespace, self.dest, 0) + 1
 976        setattr(namespace, self.dest, new_count)
 977
 978
 979class _HelpAction(Action):
 980
 981    def __init__(self,
 982                 option_strings,
 983                 dest=SUPPRESS,
 984                 default=SUPPRESS,
 985                 help=None):
 986        super(_HelpAction, self).__init__(
 987            option_strings=option_strings,
 988            dest=dest,
 989            default=default,
 990            nargs=0,
 991            help=help)
 992
 993    def __call__(self, parser, namespace, values, option_string=None):
 994        parser.print_help()
 995        parser.exit()
 996
 997
 998class _VersionAction(Action):
 999
1000    def __init__(self,
1001                 option_strings,
1002                 version=None,
1003                 dest=SUPPRESS,
1004                 default=SUPPRESS,
1005                 help="show program's version number and exit"):
1006        super(_VersionAction, self).__init__(
1007            option_strings=option_strings,
1008            dest=dest,
1009            default=default,
1010            nargs=0,
1011            help=help)
1012        self.version = version
1013
1014    def __call__(self, parser, namespace, values, option_string=None):
1015        version = self.version
1016        if version is None:
1017            version = parser.version
1018        formatter = parser._get_formatter()
1019        formatter.add_text(version)
1020        parser.exit(message=formatter.format_help())
1021
1022
1023class _SubParsersAction(Action):
1024
1025    class _ChoicesPseudoAction(Action):
1026
1027        def __init__(self, name, help):
1028            sup = super(_SubParsersAction._ChoicesPseudoAction, self)
1029            sup.__init__(option_strings=[], dest=name, help=help)
1030
1031    def __init__(self,
1032                 option_strings,
1033                 prog,
1034                 parser_class,
1035                 dest=SUPPRESS,
1036                 help=None,
1037                 metavar=None):
1038
1039        self._prog_prefix = prog
1040        self._parser_class = parser_class
1041        self._name_parser_map = _collections.OrderedDict()
1042        self._choices_actions = []
1043
1044        super(_SubParsersAction, self).__init__(
1045            option_strings=option_strings,
1046            dest=dest,
1047            nargs=PARSER,
1048            choices=self._name_parser_map,
1049            help=help,
1050            metavar=metavar)
1051
1052    def add_parser(self, name, **kwargs):
1053        # set prog from the existing prefix
1054        if kwargs.get('prog') is None:
1055            kwargs['prog'] = '%s %s' % (self._prog_prefix, name)
1056
1057        # create a pseudo-action to hold the choice help
1058        if 'help' in kwargs:
1059            help = kwargs.pop('help')
1060            choice_action = self._ChoicesPseudoAction(name, help)
1061            self._choices_actions.append(choice_action)
1062
1063        # create the parser and add it to the map
1064        parser = self._parser_class(**kwargs)
1065        self._name_parser_map[name] = parser
1066        return parser
1067
1068    def _get_subactions(self):
1069        return self._choices_actions
1070
1071    def __call__(self, parser, namespace, values, option_string=None):
1072        parser_name = values[0]
1073        arg_strings = values[1:]
1074
1075        # set the parser name if requested
1076        if self.dest is not SUPPRESS:
1077            setattr(namespace, self.dest, parser_name)
1078
1079        # select the parser
1080        try:
1081            parser = self._name_parser_map[parser_name]
1082        except KeyError:
1083            tup = parser_name, ', '.join(self._name_parser_map)
1084            msg = _('unknown parser %r (choices: %s)') % tup
1085            raise ArgumentError(self, msg)
1086
1087        # parse all the remaining options into the namespace
1088        # store any unrecognized options on the object, so that the top
1089        # level parser can decide what to do with them
1090        namespace, arg_strings = parser.parse_known_args(arg_strings, namespace)
1091        if arg_strings:
1092            vars(namespace).setdefault(_UNRECOGNIZED_ARGS_ATTR, [])
1093            getattr(namespace, _UNRECOGNIZED_ARGS_ATTR).extend(arg_strings)
1094
1095
1096# ==============
1097# Type classes
1098# ==============
1099
1100class FileType(object):
1101    """Factory for creating file object types
1102
1103    Instances of FileType are typically passed as type= arguments to the
1104    ArgumentParser add_argument() method.
1105
1106    Keyword Arguments:
1107        - mode -- A string indicating how the file is to be opened. Accepts the
1108            same values as the builtin open() function.
1109        - bufsize -- The file's desired buffer size. Accepts the same values as
1110            the builtin open() function.
1111    """
1112
1113    def __init__(self, mode='r', bufsize=-1):
1114        self._mode = mode
1115        self._bufsize = bufsize
1116
1117    def __call__(self, string):
1118        # the special argument "-" means sys.std{in,out}
1119        if string == '-':
1120            if 'r' in self._mode:
1121                return _sys.stdin
1122            elif 'w' in self._mode:
1123                return _sys.stdout
1124            else:
1125                msg = _('argument "-" with mode %r') % self._mode
1126                raise ValueError(msg)
1127
1128        # all other arguments are used as file names
1129        try:
1130            return open(string, self._mode, self._bufsize)
1131        except IOError as e:
1132            message = _("can't open '%s': %s")
1133            raise ArgumentTypeError(message % (string, e))
1134
1135    def __repr__(self):
1136        args = self._mode, self._bufsize
1137        args_str = ', '.join(repr(arg) for arg in args if arg != -1)
1138        return '%s(%s)' % (type(self).__name__, args_str)
1139
1140# ===========================
1141# Optional and Positional Parsing
1142# ===========================
1143
1144class Namespace(_AttributeHolder):
1145    """Simple object for storing attributes.
1146
1147    Implements equality by attribute names and values, and provides a simple
1148    string representation.
1149    """
1150
1151    def __init__(self, **kwargs):
1152        for name in kwargs:
1153            setattr(self, name, kwargs[name])
1154
1155    __hash__ = None
1156
1157    def __eq__(self, other):
1158        return vars(self) == vars(other)
1159
1160    def __ne__(self, other):
1161        return not (self == other)
1162
1163    def __contains__(self, key):
1164        return key in self.__dict__
1165
1166
1167class _ActionsContainer(object):
1168
1169    def __init__(self,
1170                 description,
1171                 prefix_chars,
1172                 argument_default,
1173                 conflict_handler):
1174        super(_ActionsContainer, self).__init__()
1175
1176        self.description = description
1177        self.argument_default = argument_default
1178        self.prefix_chars = prefix_chars
1179        self.conflict_handler = conflict_handler
1180
1181        # set up registries
1182        self._registries = {}
1183
1184        # register actions
1185        self.register('action', None, _StoreAction)
1186        self.register('action', 'store', _StoreAction)
1187        self.register('action', 'store_const', _StoreConstAction)
1188        self.register('action', 'store_true', _StoreTrueAction)
1189        self.register('action', 'store_false', _StoreFalseAction)
1190        self.register('action', 'append', _AppendAction)
1191        self.register('action', 'append_const', _AppendConstAction)
1192        self.register('action', 'count', _CountAction)
1193        self.register('action', 'help', _HelpAction)
1194        self.register('action', 'version', _VersionAction)
1195        self.register('action', 'parsers', _SubParsersAction)
1196
1197        # raise an exception if the conflict handler is invalid
1198        self._get_handler()
1199
1200        # action storage
1201        self._actions = []
1202        self._option_string_actions = {}
1203
1204        # groups
1205        self._action_groups = []
1206        self._mutually_exclusive_groups = []
1207
1208        # defaults storage
1209        self._defaults = {}
1210
1211        # determines whether an "option" looks like a negative number
1212        self._negative_number_matcher = _re.compile(r'^-\d+$|^-\d*\.\d+$')
1213
1214        # whether or not there are any optionals that look like negative
1215        # numbers -- uses a list so it can be shared and edited
1216        self._has_negative_number_optionals = []
1217
1218    # ====================
1219    # Registration methods
1220    # ====================
1221    def register(self, registry_name, value, object):
1222        registry = self._registries.setdefault(registry_name, {})
1223        registry[value] = object
1224
1225    def _registry_get(self, registry_name, value, default=None):
1226        return self._registries[registry_name].get(value, default)
1227
1228    # ==================================
1229    # Namespace default accessor methods
1230    # ==================================
1231    def set_defaults(self, **kwargs):
1232        self._defaults.update(kwargs)
1233
1234        # if these defaults match any existing arguments, replace
1235        # the previous default on the object with the new one
1236        for action in self._actions:
1237            if action.dest in kwargs:
1238                action.default = kwargs[action.dest]
1239
1240    def get_default(self, dest):
1241        for action in self._actions:
1242            if action.dest == dest and action.default is not None:
1243                return action.default
1244        return self._defaults.get(dest, None)
1245
1246
1247    # =======================
1248    # Adding argument actions
1249    # =======================
1250    def add_argument(self, *args, **kwargs):
1251        """
1252        add_argument(dest, ..., name=value, ...)
1253        add_argument(option_string, option_string, ..., name=value, ...)
1254        """
1255
1256        # if no positional args are supplied or only one is supplied and
1257        # it doesn't look like an option string, parse a positional
1258        # argument
1259        chars = self.prefix_chars
1260        if not args or len(args) == 1 and args[0][0] not in chars:
1261            if args and 'dest' in kwargs:
1262                raise ValueError('dest supplied twice for positional argument')
1263            kwargs = self._get_positional_kwargs(*args, **kwargs)
1264
1265        # otherwise, we're adding an optional argument
1266        else:
1267            kwargs = self._get_optional_kwargs(*args, **kwargs)
1268
1269        # if no default was supplied, use the parser-level default
1270        if 'default' not in kwargs:
1271            dest = kwargs['dest']
1272            if dest in self._defaults:
1273                kwargs['default'] = self._defaults[dest]
1274            elif self.argument_default is not None:
1275                kwargs['default'] = self.argument_default
1276
1277        # create the action object, and add it to the parser
1278        action_class = self._pop_action_class(kwargs)
1279        if not _callable(action_class):
1280            raise ValueError('unknown action "%s"' % (action_class,))
1281        action = action_class(**kwargs)
1282
1283        # raise an error if the action type is not callable
1284        type_func = self._registry_get('type', action.type, action.type)
1285        if not _callable(type_func):
1286            raise ValueError('%r is not callable' % (type_func,))
1287
1288        # raise an error if the metavar does not match the type
1289        if hasattr(self, "_get_formatter"):
1290            try:
1291                self._get_formatter()._format_args(action, None)
1292            except TypeError:
1293                raise ValueError("length of metavar tuple does not match nargs")
1294
1295        return self._add_action(action)
1296
1297    def add_argument_group(self, *args, **kwargs):
1298        group = _ArgumentGroup(self, *args, **kwargs)
1299        self._action_groups.append(group)
1300        return group
1301
1302    def add_mutually_exclusive_group(self, **kwargs):
1303        group = _MutuallyExclusiveGroup(self, **kwargs)
1304        self._mutually_exclusive_groups.append(group)
1305        return group
1306
1307    def _add_action(self, action):
1308        # resolve any conflicts
1309        self._check_conflict(action)
1310
1311        # add to actions list
1312        self._actions.append(action)
1313        action.container = self
1314
1315        # index the action by any option strings it has
1316        for option_string in action.option_strings:
1317            self._option_string_actions[option_string] = action
1318
1319        # set the flag if any option strings look like negative numbers
1320        for option_string in action.option_strings:
1321            if self._negative_number_matcher.match(option_string):
1322                if not self._has_negative_number_optionals:
1323                    self._has_negative_number_optionals.append(True)
1324
1325        # return the created action
1326        return action
1327
1328    def _remove_action(self, action):
1329        self._actions.remove(action)
1330
1331    def _add_container_actions(self, container):
1332        # collect groups by titles
1333        title_group_map = {}
1334        for group in self._action_groups:
1335            if group.title in title_group_map:
1336                msg = _('cannot merge actions - two groups are named %r')
1337                raise ValueError(msg % (group.title))
1338            title_group_map[group.title] = group
1339
1340        # map each action to its group
1341        group_map = {}
1342        for group in container._action_groups:
1343
1344            # if a group with the title exists, use that, otherwise
1345            # create a new group matching the container's group
1346            if group.title not in title_group_map:
1347                title_group_map[group.title] = self.add_argument_group(
1348                    title=group.title,
1349                    description=group.description,
1350                    conflict_handler=group.conflict_handler)
1351
1352            # map the actions to their new group
1353            for action in group._group_actions:
1354                group_map[action] = title_group_map[group.title]
1355
1356        # add container's mutually exclusive groups
1357        # NOTE: if add_mutually_exclusive_group ever gains title= and
1358        # description= then this code will need to be expanded as above
1359        for group in container._mutually_exclusive_groups:
1360            mutex_group = self.add_mutually_exclusive_group(
1361                required=group.required)
1362
1363            # map the actions to their new mutex group
1364            for action in group._group_actions:
1365                group_map[action] = mutex_group
1366
1367        # add all actions to this container or their group
1368        for action in container._actions:
1369            group_map.get(action, self)._add_action(action)
1370
1371    def _get_positional_kwargs(self, dest, **kwargs):
1372        # make sure required is not specified
1373        if 'required' in kwargs:
1374            msg = _("'required' is an invalid argument for positionals")
1375            raise TypeError(msg)
1376
1377        # mark positional arguments as required if at least one is
1378        # always required
1379        if kwargs.get('nargs') not in [OPTIONAL, ZERO_OR_MORE]:
1380            kwargs['required'] = True
1381        if kwargs.get('nargs') == ZERO_OR_MORE and 'default' not in kwargs:
1382            kwargs['required'] = True
1383
1384        # return the keyword arguments with no option strings
1385        return dict(kwargs, dest=dest, option_strings=[])
1386
1387    def _get_optional_kwargs(self, *args, **kwargs):
1388        # determine short and long option strings
1389        option_strings = []
1390        long_option_strings = []
1391        for option_string in args:
1392            # error on strings that don't start with an appropriate prefix
1393            if not option_string[0] in self.prefix_chars:
1394                msg = _('invalid option string %r: '
1395                        'must start with a character %r')
1396                tup = option_string, self.prefix_chars
1397                raise ValueError(msg % tup)
1398
1399            # strings starting with two prefix characters are long options
1400            option_strings.append(option_string)
1401            if option_string[0] in self.prefix_chars:
1402                if len(option_string) > 1:
1403                    if option_string[1] in self.prefix_chars:
1404                        long_option_strings.append(option_string)
1405
1406        # infer destination, '--foo-bar' -> 'foo_bar' and '-x' -> 'x'
1407        dest = kwargs.pop('dest', None)
1408        if dest is None:
1409            if long_option_strings:
1410                dest_option_string = long_option_strings[0]
1411            else:
1412                dest_option_string = option_strings[0]
1413            dest = dest_option_str

Large files files are truncated, but you can click here to view the full file