source: trunk/GDE/SATIVA/sativa/epac/argparse/argparse.py

Last change on this file was 12906, checked in by akozlov, 10 years ago

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