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