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