llvm-project

1
# -*- coding: utf-8 -*-
2

3
# Copyright © 2006-2009 Steven J. Bethard <steven.bethard@gmail.com>.
4
#
5
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
6
# use this file except in compliance with the License. You may obtain a copy
7
# of the License at
8
#
9
#     http://www.apache.org/licenses/LICENSE-2.0
10
#
11
# Unless required by applicable law or agreed to in writing, software
12
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
# License for the specific language governing permissions and limitations
15
# under the License.
16

17
"""Command-line parsing library
18

19
This module is an optparse-inspired command-line parsing library that:
20

21
    - handles both optional and positional arguments
22
    - produces highly informative usage messages
23
    - supports parsers that dispatch to sub-parsers
24

25
The following is a simple usage example that sums integers from the
26
command-line and writes the result to a file::
27

28
    parser = argparse.ArgumentParser(
29
        description='sum the integers at the command line')
30
    parser.add_argument(
31
        'integers', metavar='int', nargs='+', type=int,
32
        help='an integer to be summed')
33
    parser.add_argument(
34
        '--log', default=sys.stdout, type=argparse.FileType('w'),
35
        help='the file where the sum should be written')
36
    args = parser.parse_args()
37
    args.log.write('%s' % sum(args.integers))
38
    args.log.close()
39

40
The module contains the following public classes:
41

42
    - ArgumentParser -- The main entry point for command-line parsing. As the
43
        example above shows, the add_argument() method is used to populate
44
        the parser with actions for optional and positional arguments. Then
45
        the parse_args() method is invoked to convert the args at the
46
        command-line into an object with attributes.
47

48
    - ArgumentError -- The exception raised by ArgumentParser objects when
49
        there are errors with the parser's actions. Errors raised while
50
        parsing the command-line are caught by ArgumentParser and emitted
51
        as command-line messages.
52

53
    - FileType -- A factory for defining types of files to be created. As the
54
        example above shows, instances of FileType are typically passed as
55
        the type= argument of add_argument() calls.
56

57
    - Action -- The base class for parser actions. Typically actions are
58
        selected by passing strings like 'store_true' or 'append_const' to
59
        the action= argument of add_argument(). However, for greater
60
        customization of ArgumentParser actions, subclasses of Action may
61
        be defined and passed as the action= argument.
62

63
    - HelpFormatter, RawDescriptionHelpFormatter, RawTextHelpFormatter,
64
        ArgumentDefaultsHelpFormatter -- Formatter classes which
65
        may be passed as the formatter_class= argument to the
66
        ArgumentParser constructor. HelpFormatter is the default,
67
        RawDescriptionHelpFormatter and RawTextHelpFormatter tell the parser
68
        not to change the formatting for help text, and
69
        ArgumentDefaultsHelpFormatter adds information about argument defaults
70
        to the help.
71

72
All other classes in this module are considered implementation details.
73
(Also note that HelpFormatter and RawDescriptionHelpFormatter are only
74
considered public as object names -- the API of the formatter objects is
75
still considered an implementation detail.)
76
"""
77

78
__version__ = "1.1"
79
__all__ = [
80
    "ArgumentParser",
81
    "ArgumentError",
82
    "Namespace",
83
    "Action",
84
    "FileType",
85
    "HelpFormatter",
86
    "RawDescriptionHelpFormatter",
87
    "RawTextHelpFormatter",
88
    "ArgumentDefaultsHelpFormatter",
89
]
90

91

92
import copy as _copy
93
import os as _os
94
import re as _re
95
import sys as _sys
96
import textwrap as _textwrap
97

98
from gettext import gettext as _
99

100
try:
101
    _set = set
102
except NameError:
103
    from sets import Set as _set
104

105
try:
106
    _basestring = basestring
107
except NameError:
108
    _basestring = str
109

110
try:
111
    _sorted = sorted
112
except NameError:
113

114
    def _sorted(iterable, reverse=False):
115
        result = list(iterable)
116
        result.sort()
117
        if reverse:
118
            result.reverse()
119
        return result
120

121

122
def _callable(obj):
123
    return hasattr(obj, "__call__") or hasattr(obj, "__bases__")
124

125

126
# silence Python 2.6 buggy warnings about Exception.message
127
if _sys.version_info[:2] == (2, 6):
128
    import warnings
129

130
    warnings.filterwarnings(
131
        action="ignore",
132
        message="BaseException.message has been deprecated as of Python 2.6",
133
        category=DeprecationWarning,
134
        module="argparse",
135
    )
136

137

138
SUPPRESS = "==SUPPRESS=="
139

140
OPTIONAL = "?"
141
ZERO_OR_MORE = "*"
142
ONE_OR_MORE = "+"
143
PARSER = "A..."
144
REMAINDER = "..."
145

146
# =============================
147
# Utility functions and classes
148
# =============================
149

150

151
class _AttributeHolder(object):
152
    """Abstract base class that provides __repr__.
153

154
    The __repr__ method returns a string in the format::
155
        ClassName(attr=name, attr=name, ...)
156
    The attributes are determined either by a class-level attribute,
157
    '_kwarg_names', or by inspecting the instance __dict__.
158
    """
159

160
    def __repr__(self):
161
        type_name = type(self).__name__
162
        arg_strings = []
163
        for arg in self._get_args():
164
            arg_strings.append(repr(arg))
165
        for name, value in self._get_kwargs():
166
            arg_strings.append("%s=%r" % (name, value))
167
        return "%s(%s)" % (type_name, ", ".join(arg_strings))
168

169
    def _get_kwargs(self):
170
        return _sorted(self.__dict__.items())
171

172
    def _get_args(self):
173
        return []
174

175

176
def _ensure_value(namespace, name, value):
177
    if getattr(namespace, name, None) is None:
178
        setattr(namespace, name, value)
179
    return getattr(namespace, name)
180

181

182
# ===============
183
# Formatting Help
184
# ===============
185

186

187
class HelpFormatter(object):
188
    """Formatter for generating usage messages and argument help strings.
189

190
    Only the name of this class is considered a public API. All the methods
191
    provided by the class are considered an implementation detail.
192
    """
193

194
    def __init__(self, prog, indent_increment=2, max_help_position=24, width=None):
195

196
        # default setting for width
197
        if width is None:
198
            try:
199
                width = int(_os.environ["COLUMNS"])
200
            except (KeyError, ValueError):
201
                width = 80
202
            width -= 2
203

204
        self._prog = prog
205
        self._indent_increment = indent_increment
206
        self._max_help_position = max_help_position
207
        self._width = width
208

209
        self._current_indent = 0
210
        self._level = 0
211
        self._action_max_length = 0
212

213
        self._root_section = self._Section(self, None)
214
        self._current_section = self._root_section
215

216
        self._whitespace_matcher = _re.compile(r"\s+")
217
        self._long_break_matcher = _re.compile(r"\n\n\n+")
218

219
    # ===============================
220
    # Section and indentation methods
221
    # ===============================
222
    def _indent(self):
223
        self._current_indent += self._indent_increment
224
        self._level += 1
225

226
    def _dedent(self):
227
        self._current_indent -= self._indent_increment
228
        assert self._current_indent >= 0, "Indent decreased below 0."
229
        self._level -= 1
230

231
    class _Section(object):
232
        def __init__(self, formatter, parent, heading=None):
233
            self.formatter = formatter
234
            self.parent = parent
235
            self.heading = heading
236
            self.items = []
237

238
        def format_help(self):
239
            # format the indented section
240
            if self.parent is not None:
241
                self.formatter._indent()
242
            join = self.formatter._join_parts
243
            for func, args in self.items:
244
                func(*args)
245
            item_help = join([func(*args) for func, args in self.items])
246
            if self.parent is not None:
247
                self.formatter._dedent()
248

249
            # return nothing if the section was empty
250
            if not item_help:
251
                return ""
252

253
            # add the heading if the section was non-empty
254
            if self.heading is not SUPPRESS and self.heading is not None:
255
                current_indent = self.formatter._current_indent
256
                heading = "%*s%s:\n" % (current_indent, "", self.heading)
257
            else:
258
                heading = ""
259

260
            # join the section-initial newline, the heading and the help
261
            return join(["\n", heading, item_help, "\n"])
262

263
    def _add_item(self, func, args):
264
        self._current_section.items.append((func, args))
265

266
    # ========================
267
    # Message building methods
268
    # ========================
269
    def start_section(self, heading):
270
        self._indent()
271
        section = self._Section(self, self._current_section, heading)
272
        self._add_item(section.format_help, [])
273
        self._current_section = section
274

275
    def end_section(self):
276
        self._current_section = self._current_section.parent
277
        self._dedent()
278

279
    def add_text(self, text):
280
        if text is not SUPPRESS and text is not None:
281
            self._add_item(self._format_text, [text])
282

283
    def add_usage(self, usage, actions, groups, prefix=None):
284
        if usage is not SUPPRESS:
285
            args = usage, actions, groups, prefix
286
            self._add_item(self._format_usage, args)
287

288
    def add_argument(self, action):
289
        if action.help is not SUPPRESS:
290

291
            # find all invocations
292
            get_invocation = self._format_action_invocation
293
            invocations = [get_invocation(action)]
294
            for subaction in self._iter_indented_subactions(action):
295
                invocations.append(get_invocation(subaction))
296

297
            # update the maximum item length
298
            invocation_length = max([len(s) for s in invocations])
299
            action_length = invocation_length + self._current_indent
300
            self._action_max_length = max(self._action_max_length, action_length)
301

302
            # add the item to the list
303
            self._add_item(self._format_action, [action])
304

305
    def add_arguments(self, actions):
306
        for action in actions:
307
            self.add_argument(action)
308

309
    # =======================
310
    # Help-formatting methods
311
    # =======================
312
    def format_help(self):
313
        help = self._root_section.format_help()
314
        if help:
315
            help = self._long_break_matcher.sub("\n\n", help)
316
            help = help.strip("\n") + "\n"
317
        return help
318

319
    def _join_parts(self, part_strings):
320
        return "".join([part for part in part_strings if part and part is not SUPPRESS])
321

322
    def _format_usage(self, usage, actions, groups, prefix):
323
        if prefix is None:
324
            prefix = _("usage: ")
325

326
        # if usage is specified, use that
327
        if usage is not None:
328
            usage = usage % dict(prog=self._prog)
329

330
        # if no optionals or positionals are available, usage is just prog
331
        elif usage is None and not actions:
332
            usage = "%(prog)s" % dict(prog=self._prog)
333

334
        # if optionals and positionals are available, calculate usage
335
        elif usage is None:
336
            prog = "%(prog)s" % dict(prog=self._prog)
337

338
            # split optionals from positionals
339
            optionals = []
340
            positionals = []
341
            for action in actions:
342
                if action.option_strings:
343
                    optionals.append(action)
344
                else:
345
                    positionals.append(action)
346

347
            # build full usage string
348
            format = self._format_actions_usage
349
            action_usage = format(optionals + positionals, groups)
350
            usage = " ".join([s for s in [prog, action_usage] if s])
351

352
            # wrap the usage parts if it's too long
353
            text_width = self._width - self._current_indent
354
            if len(prefix) + len(usage) > text_width:
355

356
                # break usage into wrappable parts
357
                part_regexp = r"\(.*?\)+|\[.*?\]+|\S+"
358
                opt_usage = format(optionals, groups)
359
                pos_usage = format(positionals, groups)
360
                opt_parts = _re.findall(part_regexp, opt_usage)
361
                pos_parts = _re.findall(part_regexp, pos_usage)
362
                assert " ".join(opt_parts) == opt_usage
363
                assert " ".join(pos_parts) == pos_usage
364

365
                # helper for wrapping lines
366
                def get_lines(parts, indent, prefix=None):
367
                    lines = []
368
                    line = []
369
                    if prefix is not None:
370
                        line_len = len(prefix) - 1
371
                    else:
372
                        line_len = len(indent) - 1
373
                    for part in parts:
374
                        if line_len + 1 + len(part) > text_width:
375
                            lines.append(indent + " ".join(line))
376
                            line = []
377
                            line_len = len(indent) - 1
378
                        line.append(part)
379
                        line_len += len(part) + 1
380
                    if line:
381
                        lines.append(indent + " ".join(line))
382
                    if prefix is not None:
383
                        lines[0] = lines[0][len(indent) :]
384
                    return lines
385

386
                # if prog is short, follow it with optionals or positionals
387
                if len(prefix) + len(prog) <= 0.75 * text_width:
388
                    indent = " " * (len(prefix) + len(prog) + 1)
389
                    if opt_parts:
390
                        lines = get_lines([prog] + opt_parts, indent, prefix)
391
                        lines.extend(get_lines(pos_parts, indent))
392
                    elif pos_parts:
393
                        lines = get_lines([prog] + pos_parts, indent, prefix)
394
                    else:
395
                        lines = [prog]
396

397
                # if prog is long, put it on its own line
398
                else:
399
                    indent = " " * len(prefix)
400
                    parts = opt_parts + pos_parts
401
                    lines = get_lines(parts, indent)
402
                    if len(lines) > 1:
403
                        lines = []
404
                        lines.extend(get_lines(opt_parts, indent))
405
                        lines.extend(get_lines(pos_parts, indent))
406
                    lines = [prog] + lines
407

408
                # join lines into usage
409
                usage = "\n".join(lines)
410

411
        # prefix with 'usage:'
412
        return "%s%s\n\n" % (prefix, usage)
413

414
    def _format_actions_usage(self, actions, groups):
415
        # find group indices and identify actions in groups
416
        group_actions = _set()
417
        inserts = {}
418
        for group in groups:
419
            try:
420
                start = actions.index(group._group_actions[0])
421
            except ValueError:
422
                continue
423
            else:
424
                end = start + len(group._group_actions)
425
                if actions[start:end] == group._group_actions:
426
                    for action in group._group_actions:
427
                        group_actions.add(action)
428
                    if not group.required:
429
                        inserts[start] = "["
430
                        inserts[end] = "]"
431
                    else:
432
                        inserts[start] = "("
433
                        inserts[end] = ")"
434
                    for i in range(start + 1, end):
435
                        inserts[i] = "|"
436

437
        # collect all actions format strings
438
        parts = []
439
        for i, action in enumerate(actions):
440

441
            # suppressed arguments are marked with None
442
            # remove | separators for suppressed arguments
443
            if action.help is SUPPRESS:
444
                parts.append(None)
445
                if inserts.get(i) == "|":
446
                    inserts.pop(i)
447
                elif inserts.get(i + 1) == "|":
448
                    inserts.pop(i + 1)
449

450
            # produce all arg strings
451
            elif not action.option_strings:
452
                part = self._format_args(action, action.dest)
453

454
                # if it's in a group, strip the outer []
455
                if action in group_actions:
456
                    if part[0] == "[" and part[-1] == "]":
457
                        part = part[1:-1]
458

459
                # add the action string to the list
460
                parts.append(part)
461

462
            # produce the first way to invoke the option in brackets
463
            else:
464
                option_string = action.option_strings[0]
465

466
                # if the Optional doesn't take a value, format is:
467
                #    -s or --long
468
                if action.nargs == 0:
469
                    part = "%s" % option_string
470

471
                # if the Optional takes a value, format is:
472
                #    -s ARGS or --long ARGS
473
                else:
474
                    default = action.dest.upper()
475
                    args_string = self._format_args(action, default)
476
                    part = "%s %s" % (option_string, args_string)
477

478
                # make it look optional if it's not required or in a group
479
                if not action.required and action not in group_actions:
480
                    part = "[%s]" % part
481

482
                # add the action string to the list
483
                parts.append(part)
484

485
        # insert things at the necessary indices
486
        for i in _sorted(inserts, reverse=True):
487
            parts[i:i] = [inserts[i]]
488

489
        # join all the action items with spaces
490
        text = " ".join([item for item in parts if item is not None])
491

492
        # clean up separators for mutually exclusive groups
493
        open = r"[\[(]"
494
        close = r"[\])]"
495
        text = _re.sub(r"(%s) " % open, r"\1", text)
496
        text = _re.sub(r" (%s)" % close, r"\1", text)
497
        text = _re.sub(r"%s *%s" % (open, close), r"", text)
498
        text = _re.sub(r"\(([^|]*)\)", r"\1", text)
499
        text = text.strip()
500

501
        # return the text
502
        return text
503

504
    def _format_text(self, text):
505
        if "%(prog)" in text:
506
            text = text % dict(prog=self._prog)
507
        text_width = self._width - self._current_indent
508
        indent = " " * self._current_indent
509
        return self._fill_text(text, text_width, indent) + "\n\n"
510

511
    def _format_action(self, action):
512
        # determine the required width and the entry label
513
        help_position = min(self._action_max_length + 2, self._max_help_position)
514
        help_width = self._width - help_position
515
        action_width = help_position - self._current_indent - 2
516
        action_header = self._format_action_invocation(action)
517

518
        # ho nelp; start on same line and add a final newline
519
        if not action.help:
520
            tup = self._current_indent, "", action_header
521
            action_header = "%*s%s\n" % tup
522

523
        # short action name; start on the same line and pad two spaces
524
        elif len(action_header) <= action_width:
525
            tup = self._current_indent, "", action_width, action_header
526
            action_header = "%*s%-*s  " % tup
527
            indent_first = 0
528

529
        # long action name; start on the next line
530
        else:
531
            tup = self._current_indent, "", action_header
532
            action_header = "%*s%s\n" % tup
533
            indent_first = help_position
534

535
        # collect the pieces of the action help
536
        parts = [action_header]
537

538
        # if there was help for the action, add lines of help text
539
        if action.help:
540
            help_text = self._expand_help(action)
541
            help_lines = self._split_lines(help_text, help_width)
542
            parts.append("%*s%s\n" % (indent_first, "", help_lines[0]))
543
            for line in help_lines[1:]:
544
                parts.append("%*s%s\n" % (help_position, "", line))
545

546
        # or add a newline if the description doesn't end with one
547
        elif not action_header.endswith("\n"):
548
            parts.append("\n")
549

550
        # if there are any sub-actions, add their help as well
551
        for subaction in self._iter_indented_subactions(action):
552
            parts.append(self._format_action(subaction))
553

554
        # return a single string
555
        return self._join_parts(parts)
556

557
    def _format_action_invocation(self, action):
558
        if not action.option_strings:
559
            (metavar,) = self._metavar_formatter(action, action.dest)(1)
560
            return metavar
561

562
        else:
563
            parts = []
564

565
            # if the Optional doesn't take a value, format is:
566
            #    -s, --long
567
            if action.nargs == 0:
568
                parts.extend(action.option_strings)
569

570
            # if the Optional takes a value, format is:
571
            #    -s ARGS, --long ARGS
572
            else:
573
                default = action.dest.upper()
574
                args_string = self._format_args(action, default)
575
                for option_string in action.option_strings:
576
                    parts.append("%s %s" % (option_string, args_string))
577

578
            return ", ".join(parts)
579

580
    def _metavar_formatter(self, action, default_metavar):
581
        if action.metavar is not None:
582
            result = action.metavar
583
        elif action.choices is not None:
584
            choice_strs = [str(choice) for choice in action.choices]
585
            result = "{%s}" % ",".join(choice_strs)
586
        else:
587
            result = default_metavar
588

589
        def format(tuple_size):
590
            if isinstance(result, tuple):
591
                return result
592
            else:
593
                return (result,) * tuple_size
594

595
        return format
596

597
    def _format_args(self, action, default_metavar):
598
        get_metavar = self._metavar_formatter(action, default_metavar)
599
        if action.nargs is None:
600
            result = "%s" % get_metavar(1)
601
        elif action.nargs == OPTIONAL:
602
            result = "[%s]" % get_metavar(1)
603
        elif action.nargs == ZERO_OR_MORE:
604
            result = "[%s [%s ...]]" % get_metavar(2)
605
        elif action.nargs == ONE_OR_MORE:
606
            result = "%s [%s ...]" % get_metavar(2)
607
        elif action.nargs == REMAINDER:
608
            result = "..."
609
        elif action.nargs == PARSER:
610
            result = "%s ..." % get_metavar(1)
611
        else:
612
            formats = ["%s" for _ in range(action.nargs)]
613
            result = " ".join(formats) % get_metavar(action.nargs)
614
        return result
615

616
    def _expand_help(self, action):
617
        params = dict(vars(action), prog=self._prog)
618
        for name in list(params):
619
            if params[name] is SUPPRESS:
620
                del params[name]
621
        for name in list(params):
622
            if hasattr(params[name], "__name__"):
623
                params[name] = params[name].__name__
624
        if params.get("choices") is not None:
625
            choices_str = ", ".join([str(c) for c in params["choices"]])
626
            params["choices"] = choices_str
627
        return self._get_help_string(action) % params
628

629
    def _iter_indented_subactions(self, action):
630
        try:
631
            get_subactions = action._get_subactions
632
        except AttributeError:
633
            pass
634
        else:
635
            self._indent()
636
            for subaction in get_subactions():
637
                yield subaction
638
            self._dedent()
639

640
    def _split_lines(self, text, width):
641
        text = self._whitespace_matcher.sub(" ", text).strip()
642
        return _textwrap.wrap(text, width)
643

644
    def _fill_text(self, text, width, indent):
645
        text = self._whitespace_matcher.sub(" ", text).strip()
646
        return _textwrap.fill(
647
            text, width, initial_indent=indent, subsequent_indent=indent
648
        )
649

650
    def _get_help_string(self, action):
651
        return action.help
652

653

654
class RawDescriptionHelpFormatter(HelpFormatter):
655
    """Help message formatter which retains any formatting in descriptions.
656

657
    Only the name of this class is considered a public API. All the methods
658
    provided by the class are considered an implementation detail.
659
    """
660

661
    def _fill_text(self, text, width, indent):
662
        return "".join([indent + line for line in text.splitlines(True)])
663

664

665
class RawTextHelpFormatter(RawDescriptionHelpFormatter):
666
    """Help message formatter which retains formatting of all help text.
667

668
    Only the name of this class is considered a public API. All the methods
669
    provided by the class are considered an implementation detail.
670
    """
671

672
    def _split_lines(self, text, width):
673
        return text.splitlines()
674

675

676
class ArgumentDefaultsHelpFormatter(HelpFormatter):
677
    """Help message formatter which adds default values to argument help.
678

679
    Only the name of this class is considered a public API. All the methods
680
    provided by the class are considered an implementation detail.
681
    """
682

683
    def _get_help_string(self, action):
684
        help = action.help
685
        if "%(default)" not in action.help:
686
            if action.default is not SUPPRESS:
687
                defaulting_nargs = [OPTIONAL, ZERO_OR_MORE]
688
                if action.option_strings or action.nargs in defaulting_nargs:
689
                    help += " (default: %(default)s)"
690
        return help
691

692

693
# =====================
694
# Options and Arguments
695
# =====================
696

697

698
def _get_action_name(argument):
699
    if argument is None:
700
        return None
701
    elif argument.option_strings:
702
        return "/".join(argument.option_strings)
703
    elif argument.metavar not in (None, SUPPRESS):
704
        return argument.metavar
705
    elif argument.dest not in (None, SUPPRESS):
706
        return argument.dest
707
    else:
708
        return None
709

710

711
class ArgumentError(Exception):
712
    """An error from creating or using an argument (optional or positional).
713

714
    The string value of this exception is the message, augmented with
715
    information about the argument that caused it.
716
    """
717

718
    def __init__(self, argument, message):
719
        self.argument_name = _get_action_name(argument)
720
        self.message = message
721

722
    def __str__(self):
723
        if self.argument_name is None:
724
            format = "%(message)s"
725
        else:
726
            format = "argument %(argument_name)s: %(message)s"
727
        return format % dict(message=self.message, argument_name=self.argument_name)
728

729

730
class ArgumentTypeError(Exception):
731
    """An error from trying to convert a command line string to a type."""
732

733
    pass
734

735

736
# ==============
737
# Action classes
738
# ==============
739

740

741
class Action(_AttributeHolder):
742
    """Information about how to convert command line strings to Python objects.
743

744
    Action objects are used by an ArgumentParser to represent the information
745
    needed to parse a single argument from one or more strings from the
746
    command line. The keyword arguments to the Action constructor are also
747
    all attributes of Action instances.
748

749
    Keyword Arguments:
750

751
        - option_strings -- A list of command-line option strings which
752
            should be associated with this action.
753

754
        - dest -- The name of the attribute to hold the created object(s)
755

756
        - nargs -- The number of command-line arguments that should be
757
            consumed. By default, one argument will be consumed and a single
758
            value will be produced.  Other values include:
759
                - N (an integer) consumes N arguments (and produces a list)
760
                - '?' consumes zero or one arguments
761
                - '*' consumes zero or more arguments (and produces a list)
762
                - '+' consumes one or more arguments (and produces a list)
763
            Note that the difference between the default and nargs=1 is that
764
            with the default, a single value will be produced, while with
765
            nargs=1, a list containing a single value will be produced.
766

767
        - const -- The value to be produced if the option is specified and the
768
            option uses an action that takes no values.
769

770
        - default -- The value to be produced if the option is not specified.
771

772
        - type -- The type which the command-line arguments should be converted
773
            to, should be one of 'string', 'int', 'float', 'complex' or a
774
            callable object that accepts a single string argument. If None,
775
            'string' is assumed.
776

777
        - choices -- A container of values that should be allowed. If not None,
778
            after a command-line argument has been converted to the appropriate
779
            type, an exception will be raised if it is not a member of this
780
            collection.
781

782
        - required -- True if the action must always be specified at the
783
            command line. This is only meaningful for optional command-line
784
            arguments.
785

786
        - help -- The help string describing the argument.
787

788
        - metavar -- The name to be used for the option's argument with the
789
            help string. If None, the 'dest' value will be used as the name.
790
    """
791

792
    def __init__(
793
        self,
794
        option_strings,
795
        dest,
796
        nargs=None,
797
        const=None,
798
        default=None,
799
        type=None,
800
        choices=None,
801
        required=False,
802
        help=None,
803
        metavar=None,
804
    ):
805
        self.option_strings = option_strings
806
        self.dest = dest
807
        self.nargs = nargs
808
        self.const = const
809
        self.default = default
810
        self.type = type
811
        self.choices = choices
812
        self.required = required
813
        self.help = help
814
        self.metavar = metavar
815

816
    def _get_kwargs(self):
817
        names = [
818
            "option_strings",
819
            "dest",
820
            "nargs",
821
            "const",
822
            "default",
823
            "type",
824
            "choices",
825
            "help",
826
            "metavar",
827
        ]
828
        return [(name, getattr(self, name)) for name in names]
829

830
    def __call__(self, parser, namespace, values, option_string=None):
831
        raise NotImplementedError(_(".__call__() not defined"))
832

833

834
class _StoreAction(Action):
835
    def __init__(
836
        self,
837
        option_strings,
838
        dest,
839
        nargs=None,
840
        const=None,
841
        default=None,
842
        type=None,
843
        choices=None,
844
        required=False,
845
        help=None,
846
        metavar=None,
847
    ):
848
        if nargs == 0:
849
            raise ValueError(
850
                "nargs for store actions must be > 0; if you "
851
                "have nothing to store, actions such as store "
852
                "true or store const may be more appropriate"
853
            )
854
        if const is not None and nargs != OPTIONAL:
855
            raise ValueError("nargs must be %r to supply const" % OPTIONAL)
856
        super(_StoreAction, self).__init__(
857
            option_strings=option_strings,
858
            dest=dest,
859
            nargs=nargs,
860
            const=const,
861
            default=default,
862
            type=type,
863
            choices=choices,
864
            required=required,
865
            help=help,
866
            metavar=metavar,
867
        )
868

869
    def __call__(self, parser, namespace, values, option_string=None):
870
        setattr(namespace, self.dest, values)
871

872

873
class _StoreConstAction(Action):
874
    def __init__(
875
        self,
876
        option_strings,
877
        dest,
878
        const,
879
        default=None,
880
        required=False,
881
        help=None,
882
        metavar=None,
883
    ):
884
        super(_StoreConstAction, self).__init__(
885
            option_strings=option_strings,
886
            dest=dest,
887
            nargs=0,
888
            const=const,
889
            default=default,
890
            required=required,
891
            help=help,
892
        )
893

894
    def __call__(self, parser, namespace, values, option_string=None):
895
        setattr(namespace, self.dest, self.const)
896

897

898
class _StoreTrueAction(_StoreConstAction):
899
    def __init__(self, option_strings, dest, default=False, required=False, help=None):
900
        super(_StoreTrueAction, self).__init__(
901
            option_strings=option_strings,
902
            dest=dest,
903
            const=True,
904
            default=default,
905
            required=required,
906
            help=help,
907
        )
908

909

910
class _StoreFalseAction(_StoreConstAction):
911
    def __init__(self, option_strings, dest, default=True, required=False, help=None):
912
        super(_StoreFalseAction, self).__init__(
913
            option_strings=option_strings,
914
            dest=dest,
915
            const=False,
916
            default=default,
917
            required=required,
918
            help=help,
919
        )
920

921

922
class _AppendAction(Action):
923
    def __init__(
924
        self,
925
        option_strings,
926
        dest,
927
        nargs=None,
928
        const=None,
929
        default=None,
930
        type=None,
931
        choices=None,
932
        required=False,
933
        help=None,
934
        metavar=None,
935
    ):
936
        if nargs == 0:
937
            raise ValueError(
938
                "nargs for append actions must be > 0; if arg "
939
                "strings are not supplying the value to append, "
940
                "the append const action may be more appropriate"
941
            )
942
        if const is not None and nargs != OPTIONAL:
943
            raise ValueError("nargs must be %r to supply const" % OPTIONAL)
944
        super(_AppendAction, self).__init__(
945
            option_strings=option_strings,
946
            dest=dest,
947
            nargs=nargs,
948
            const=const,
949
            default=default,
950
            type=type,
951
            choices=choices,
952
            required=required,
953
            help=help,
954
            metavar=metavar,
955
        )
956

957
    def __call__(self, parser, namespace, values, option_string=None):
958
        items = _copy.copy(_ensure_value(namespace, self.dest, []))
959
        items.append(values)
960
        setattr(namespace, self.dest, items)
961

962

963
class _AppendConstAction(Action):
964
    def __init__(
965
        self,
966
        option_strings,
967
        dest,
968
        const,
969
        default=None,
970
        required=False,
971
        help=None,
972
        metavar=None,
973
    ):
974
        super(_AppendConstAction, self).__init__(
975
            option_strings=option_strings,
976
            dest=dest,
977
            nargs=0,
978
            const=const,
979
            default=default,
980
            required=required,
981
            help=help,
982
            metavar=metavar,
983
        )
984

985
    def __call__(self, parser, namespace, values, option_string=None):
986
        items = _copy.copy(_ensure_value(namespace, self.dest, []))
987
        items.append(self.const)
988
        setattr(namespace, self.dest, items)
989

990

991
class _CountAction(Action):
992
    def __init__(self, option_strings, dest, default=None, required=False, help=None):
993
        super(_CountAction, self).__init__(
994
            option_strings=option_strings,
995
            dest=dest,
996
            nargs=0,
997
            default=default,
998
            required=required,
999
            help=help,
1000
        )
1001

1002
    def __call__(self, parser, namespace, values, option_string=None):
1003
        new_count = _ensure_value(namespace, self.dest, 0) + 1
1004
        setattr(namespace, self.dest, new_count)
1005

1006

1007
class _HelpAction(Action):
1008
    def __init__(self, option_strings, dest=SUPPRESS, default=SUPPRESS, help=None):
1009
        super(_HelpAction, self).__init__(
1010
            option_strings=option_strings,
1011
            dest=dest,
1012
            default=default,
1013
            nargs=0,
1014
            help=help,
1015
        )
1016

1017
    def __call__(self, parser, namespace, values, option_string=None):
1018
        parser.print_help()
1019
        parser.exit()
1020

1021

1022
class _VersionAction(Action):
1023
    def __init__(
1024
        self, option_strings, version=None, dest=SUPPRESS, default=SUPPRESS, help=None
1025
    ):
1026
        super(_VersionAction, self).__init__(
1027
            option_strings=option_strings,
1028
            dest=dest,
1029
            default=default,
1030
            nargs=0,
1031
            help=help,
1032
        )
1033
        self.version = version
1034

1035
    def __call__(self, parser, namespace, values, option_string=None):
1036
        version = self.version
1037
        if version is None:
1038
            version = parser.version
1039
        formatter = parser._get_formatter()
1040
        formatter.add_text(version)
1041
        parser.exit(message=formatter.format_help())
1042

1043

1044
class _SubParsersAction(Action):
1045
    class _ChoicesPseudoAction(Action):
1046
        def __init__(self, name, help):
1047
            sup = super(_SubParsersAction._ChoicesPseudoAction, self)
1048
            sup.__init__(option_strings=[], dest=name, help=help)
1049

1050
    def __init__(
1051
        self, option_strings, prog, parser_class, dest=SUPPRESS, help=None, metavar=None
1052
    ):
1053

1054
        self._prog_prefix = prog
1055
        self._parser_class = parser_class
1056
        self._name_parser_map = {}
1057
        self._choices_actions = []
1058

1059
        super(_SubParsersAction, self).__init__(
1060
            option_strings=option_strings,
1061
            dest=dest,
1062
            nargs=PARSER,
1063
            choices=self._name_parser_map,
1064
            help=help,
1065
            metavar=metavar,
1066
        )
1067

1068
    def add_parser(self, name, **kwargs):
1069
        # set prog from the existing prefix
1070
        if kwargs.get("prog") is None:
1071
            kwargs["prog"] = "%s %s" % (self._prog_prefix, name)
1072

1073
        # create a pseudo-action to hold the choice help
1074
        if "help" in kwargs:
1075
            help = kwargs.pop("help")
1076
            choice_action = self._ChoicesPseudoAction(name, help)
1077
            self._choices_actions.append(choice_action)
1078

1079
        # create the parser and add it to the map
1080
        parser = self._parser_class(**kwargs)
1081
        self._name_parser_map[name] = parser
1082
        return parser
1083

1084
    def _get_subactions(self):
1085
        return self._choices_actions
1086

1087
    def __call__(self, parser, namespace, values, option_string=None):
1088
        parser_name = values[0]
1089
        arg_strings = values[1:]
1090

1091
        # set the parser name if requested
1092
        if self.dest is not SUPPRESS:
1093
            setattr(namespace, self.dest, parser_name)
1094

1095
        # select the parser
1096
        try:
1097
            parser = self._name_parser_map[parser_name]
1098
        except KeyError:
1099
            tup = parser_name, ", ".join(self._name_parser_map)
1100
            msg = _("unknown parser %r (choices: %s)" % tup)
1101
            raise ArgumentError(self, msg)
1102

1103
        # parse all the remaining options into the namespace
1104
        parser.parse_args(arg_strings, namespace)
1105

1106

1107
# ==============
1108
# Type classes
1109
# ==============
1110

1111

1112
class FileType(object):
1113
    """Factory for creating file object types
1114

1115
    Instances of FileType are typically passed as type= arguments to the
1116
    ArgumentParser add_argument() method.
1117

1118
    Keyword Arguments:
1119
        - mode -- A string indicating how the file is to be opened. Accepts the
1120
            same values as the builtin open() function.
1121
        - bufsize -- The file's desired buffer size. Accepts the same values as
1122
            the builtin open() function.
1123
    """
1124

1125
    def __init__(self, mode="r", bufsize=None):
1126
        self._mode = mode
1127
        self._bufsize = bufsize
1128

1129
    def __call__(self, string):
1130
        # the special argument "-" means sys.std{in,out}
1131
        if string == "-":
1132
            if "r" in self._mode:
1133
                return _sys.stdin
1134
            elif "w" in self._mode:
1135
                return _sys.stdout
1136
            else:
1137
                msg = _('argument "-" with mode %r' % self._mode)
1138
                raise ValueError(msg)
1139

1140
        # all other arguments are used as file names
1141
        if self._bufsize:
1142
            return open(string, self._mode, self._bufsize)
1143
        else:
1144
            return open(string, self._mode)
1145

1146
    def __repr__(self):
1147
        args = [self._mode, self._bufsize]
1148
        args_str = ", ".join([repr(arg) for arg in args if arg is not None])
1149
        return "%s(%s)" % (type(self).__name__, args_str)
1150

1151

1152
# ===========================
1153
# Optional and Positional Parsing
1154
# ===========================
1155

1156

1157
class Namespace(_AttributeHolder):
1158
    """Simple object for storing attributes.
1159

1160
    Implements equality by attribute names and values, and provides a simple
1161
    string representation.
1162
    """
1163

1164
    def __init__(self, **kwargs):
1165
        for name in kwargs:
1166
            setattr(self, name, kwargs[name])
1167

1168
    def __eq__(self, other):
1169
        return vars(self) == vars(other)
1170

1171
    def __ne__(self, other):
1172
        return not (self == other)
1173

1174
    def __contains__(self, key):
1175
        return key in self.__dict__
1176

1177

1178
class _ActionsContainer(object):
1179
    def __init__(self, description, prefix_chars, argument_default, conflict_handler):
1180
        super(_ActionsContainer, self).__init__()
1181

1182
        self.description = description
1183
        self.argument_default = argument_default
1184
        self.prefix_chars = prefix_chars
1185
        self.conflict_handler = conflict_handler
1186

1187
        # set up registries
1188
        self._registries = {}
1189

1190
        # register actions
1191
        self.register("action", None, _StoreAction)
1192
        self.register("action", "store", _StoreAction)
1193
        self.register("action", "store_const", _StoreConstAction)
1194
        self.register("action", "store_true", _StoreTrueAction)
1195
        self.register("action", "store_false", _StoreFalseAction)
1196
        self.register("action", "append", _AppendAction)
1197
        self.register("action", "append_const", _AppendConstAction)
1198
        self.register("action", "count", _CountAction)
1199
        self.register("action", "help", _HelpAction)
1200
        self.register("action", "version", _VersionAction)
1201
        self.register("action", "parsers", _SubParsersAction)
1202

1203
        # raise an exception if the conflict handler is invalid
1204
        self._get_handler()
1205

1206
        # action storage
1207
        self._actions = []
1208
        self._option_string_actions = {}
1209

1210
        # groups
1211
        self._action_groups = []
1212
        self._mutually_exclusive_groups = []
1213

1214
        # defaults storage
1215
        self._defaults = {}
1216

1217
        # determines whether an "option" looks like a negative number
1218
        self._negative_number_matcher = _re.compile(r"^-\d+$|^-\d*\.\d+$")
1219

1220
        # whether or not there are any optionals that look like negative
1221
        # numbers -- uses a list so it can be shared and edited
1222
        self._has_negative_number_optionals = []
1223

1224
    # ====================
1225
    # Registration methods
1226
    # ====================
1227
    def register(self, registry_name, value, object):
1228
        registry = self._registries.setdefault(registry_name, {})
1229
        registry[value] = object
1230

1231
    def _registry_get(self, registry_name, value, default=None):
1232
        return self._registries[registry_name].get(value, default)
1233

1234
    # ==================================
1235
    # Namespace default accessor methods
1236
    # ==================================
1237
    def set_defaults(self, **kwargs):
1238
        self._defaults.update(kwargs)
1239

1240
        # if these defaults match any existing arguments, replace
1241
        # the previous default on the object with the new one
1242
        for action in self._actions:
1243
            if action.dest in kwargs:
1244
                action.default = kwargs[action.dest]
1245

1246
    def get_default(self, dest):
1247
        for action in self._actions:
1248
            if action.dest == dest and action.default is not None:
1249
                return action.default
1250
        return self._defaults.get(dest, None)
1251

1252
    # =======================
1253
    # Adding argument actions
1254
    # =======================
1255
    def add_argument(self, *args, **kwargs):
1256
        """
1257
        add_argument(dest, ..., name=value, ...)
1258
        add_argument(option_string, option_string, ..., name=value, ...)
1259
        """
1260

1261
        # if no positional args are supplied or only one is supplied and
1262
        # it doesn't look like an option string, parse a positional
1263
        # argument
1264
        chars = self.prefix_chars
1265
        if not args or len(args) == 1 and args[0][0] not in chars:
1266
            if args and "dest" in kwargs:
1267
                raise ValueError("dest supplied twice for positional argument")
1268
            kwargs = self._get_positional_kwargs(*args, **kwargs)
1269

1270
        # otherwise, we're adding an optional argument
1271
        else:
1272
            kwargs = self._get_optional_kwargs(*args, **kwargs)
1273

1274
        # if no default was supplied, use the parser-level default
1275
        if "default" not in kwargs:
1276
            dest = kwargs["dest"]
1277
            if dest in self._defaults:
1278
                kwargs["default"] = self._defaults[dest]
1279
            elif self.argument_default is not None:
1280
                kwargs["default"] = self.argument_default
1281

1282
        # create the action object, and add it to the parser
1283
        action_class = self._pop_action_class(kwargs)
1284
        if not _callable(action_class):
1285
            raise ValueError('unknown action "%s"' % action_class)
1286
        action = action_class(**kwargs)
1287

1288
        # raise an error if the action type is not callable
1289
        type_func = self._registry_get("type", action.type, action.type)
1290
        if not _callable(type_func):
1291
            raise ValueError("%r is not callable" % type_func)
1292

1293
        return self._add_action(action)
1294

1295
    def add_argument_group(self, *args, **kwargs):
1296
        group = _ArgumentGroup(self, *args, **kwargs)
1297
        self._action_groups.append(group)
1298
        return group
1299

1300
    def add_mutually_exclusive_group(self, **kwargs):
1301
        group = _MutuallyExclusiveGroup(self, **kwargs)
1302
        self._mutually_exclusive_groups.append(group)
1303
        return group
1304

1305
    def _add_action(self, action):
1306
        # resolve any conflicts
1307
        self._check_conflict(action)
1308

1309
        # add to actions list
1310
        self._actions.append(action)
1311
        action.container = self
1312

1313
        # index the action by any option strings it has
1314
        for option_string in action.option_strings:
1315
            self._option_string_actions[option_string] = action
1316

1317
        # set the flag if any option strings look like negative numbers
1318
        for option_string in action.option_strings:
1319
            if self._negative_number_matcher.match(option_string):
1320
                if not self._has_negative_number_optionals:
1321
                    self._has_negative_number_optionals.append(True)
1322

1323
        # return the created action
1324
        return action
1325

1326
    def _remove_action(self, action):
1327
        self._actions.remove(action)
1328

1329
    def _add_container_actions(self, container):
1330
        # collect groups by titles
1331
        title_group_map = {}
1332
        for group in self._action_groups:
1333
            if group.title in title_group_map:
1334
                msg = _("cannot merge actions - two groups are named %r")
1335
                raise ValueError(msg % (group.title))
1336
            title_group_map[group.title] = group
1337

1338
        # map each action to its group
1339
        group_map = {}
1340
        for group in container._action_groups:
1341

1342
            # if a group with the title exists, use that, otherwise
1343
            # create a new group matching the container's group
1344
            if group.title not in title_group_map:
1345
                title_group_map[group.title] = self.add_argument_group(
1346
                    title=group.title,
1347
                    description=group.description,
1348
                    conflict_handler=group.conflict_handler,
1349
                )
1350

1351
            # map the actions to their new group
1352
            for action in group._group_actions:
1353
                group_map[action] = title_group_map[group.title]
1354

1355
        # add container's mutually exclusive groups
1356
        # NOTE: if add_mutually_exclusive_group ever gains title= and
1357
        # description= then this code will need to be expanded as above
1358
        for group in container._mutually_exclusive_groups:
1359
            mutex_group = self.add_mutually_exclusive_group(required=group.required)
1360

1361
            # map the actions to their new mutex group
1362
            for action in group._group_actions:
1363
                group_map[action] = mutex_group
1364

1365
        # add all actions to this container or their group
1366
        for action in container._actions:
1367
            group_map.get(action, self)._add_action(action)
1368

1369
    def _get_positional_kwargs(self, dest, **kwargs):
1370
        # make sure required is not specified
1371
        if "required" in kwargs:
1372
            msg = _("'required' is an invalid argument for positionals")
1373
            raise TypeError(msg)
1374

1375
        # mark positional arguments as required if at least one is
1376
        # always required
1377
        if kwargs.get("nargs") not in [OPTIONAL, ZERO_OR_MORE]:
1378
            kwargs["required"] = True
1379
        if kwargs.get("nargs") == ZERO_OR_MORE and "default" not in kwargs:
1380
            kwargs["required"] = True
1381

1382
        # return the keyword arguments with no option strings
1383
        return dict(kwargs, dest=dest, option_strings=[])
1384

1385
    def _get_optional_kwargs(self, *args, **kwargs):
1386
        # determine short and long option strings
1387
        option_strings = []
1388
        long_option_strings = []
1389
        for option_string in args:
1390
            # error on strings that don't start with an appropriate prefix
1391
            if not option_string[0] in self.prefix_chars:
1392
                msg = _("invalid option string %r: " "must start with a character %r")
1393
                tup = option_string, self.prefix_chars
1394
                raise ValueError(msg % tup)
1395

1396
            # strings starting with two prefix characters are long options
1397
            option_strings.append(option_string)
1398
            if option_string[0] in self.prefix_chars:
1399
                if len(option_string) > 1:
1400
                    if option_string[1] in self.prefix_chars:
1401
                        long_option_strings.append(option_string)
1402

1403
        # infer destination, '--foo-bar' -> 'foo_bar' and '-x' -> 'x'
1404
        dest = kwargs.pop("dest", None)
1405
        if dest is None:
1406
            if long_option_strings:
1407
                dest_option_string = long_option_strings[0]
1408
            else:
1409
                dest_option_string = option_strings[0]
1410
            dest = dest_option_string.lstrip(self.prefix_chars)
1411
            if not dest:
1412
                msg = _("dest= is required for options like %r")
1413
                raise ValueError(msg % option_string)
1414
            dest = dest.replace("-", "_")
1415

1416
        # return the updated keyword arguments
1417
        return dict(kwargs, dest=dest, option_strings=option_strings)
1418

1419
    def _pop_action_class(self, kwargs, default=None):
1420
        action = kwargs.pop("action", default)
1421
        return self._registry_get("action", action, action)
1422

1423
    def _get_handler(self):
1424
        # determine function from conflict handler string
1425
        handler_func_name = "_handle_conflict_%s" % self.conflict_handler
1426
        try:
1427
            return getattr(self, handler_func_name)
1428
        except AttributeError:
1429
            msg = _("invalid conflict_resolution value: %r")
1430
            raise ValueError(msg % self.conflict_handler)
1431

1432
    def _check_conflict(self, action):
1433

1434
        # find all options that conflict with this option
1435
        confl_optionals = []
1436
        for option_string in action.option_strings:
1437
            if option_string in self._option_string_actions:
1438
                confl_optional = self._option_string_actions[option_string]
1439
                confl_optionals.append((option_string, confl_optional))
1440

1441
        # resolve any conflicts
1442
        if confl_optionals:
1443
            conflict_handler = self._get_handler()
1444
            conflict_handler(action, confl_optionals)
1445

1446
    def _handle_conflict_error(self, action, conflicting_actions):
1447
        message = _("conflicting option string(s): %s")
1448
        conflict_string = ", ".join(
1449
            [option_string for option_string, action in conflicting_actions]
1450
        )
1451
        raise ArgumentError(action, message % conflict_string)
1452

1453
    def _handle_conflict_resolve(self, action, conflicting_actions):
1454

1455
        # remove all conflicting options
1456
        for option_string, action in conflicting_actions:
1457

1458
            # remove the conflicting option
1459
            action.option_strings.remove(option_string)
1460
            self._option_string_actions.pop(option_string, None)
1461

1462
            # if the option now has no option string, remove it from the
1463
            # container holding it
1464
            if not action.option_strings:
1465
                action.container._remove_action(action)
1466

1467

1468
class _ArgumentGroup(_ActionsContainer):
1469
    def __init__(self, container, title=None, description=None, **kwargs):
1470
        # add any missing keyword arguments by checking the container
1471
        update = kwargs.setdefault
1472
        update("conflict_handler", container.conflict_handler)
1473
        update("prefix_chars", container.prefix_chars)
1474
        update("argument_default", container.argument_default)
1475
        super_init = super(_ArgumentGroup, self).__init__
1476
        super_init(description=description, **kwargs)
1477

1478
        # group attributes
1479
        self.title = title
1480
        self._group_actions = []
1481

1482
        # share most attributes with the container
1483
        self._registries = container._registries
1484
        self._actions = container._actions
1485
        self._option_string_actions = container._option_string_actions
1486
        self._defaults = container._defaults
1487
        self._has_negative_number_optionals = container._has_negative_number_optionals
1488

1489
    def _add_action(self, action):
1490
        action = super(_ArgumentGroup, self)._add_action(action)
1491
        self._group_actions.append(action)
1492
        return action
1493

1494
    def _remove_action(self, action):
1495
        super(_ArgumentGroup, self)._remove_action(action)
1496
        self._group_actions.remove(action)
1497

1498

1499
class _MutuallyExclusiveGroup(_ArgumentGroup):
1500
    def __init__(self, container, required=False):
1501
        super(_MutuallyExclusiveGroup, self).__init__(container)
1502
        self.required = required
1503
        self._container = container
1504

1505
    def _add_action(self, action):
1506
        if action.required:
1507
            msg = _("mutually exclusive arguments must be optional")
1508
            raise ValueError(msg)
1509
        action = self._container._add_action(action)
1510
        self._group_actions.append(action)
1511
        return action
1512

1513
    def _remove_action(self, action):
1514
        self._container._remove_action(action)
1515
        self._group_actions.remove(action)
1516

1517

1518
class ArgumentParser(_AttributeHolder, _ActionsContainer):
1519
    """Object for parsing command line strings into Python objects.
1520

1521
    Keyword Arguments:
1522
        - prog -- The name of the program (default: sys.argv[0])
1523
        - usage -- A usage message (default: auto-generated from arguments)
1524
        - description -- A description of what the program does
1525
        - epilog -- Text following the argument descriptions
1526
        - parents -- Parsers whose arguments should be copied into this one
1527
        - formatter_class -- HelpFormatter class for printing help messages
1528
        - prefix_chars -- Characters that prefix optional arguments
1529
        - fromfile_prefix_chars -- Characters that prefix files containing
1530
            additional arguments
1531
        - argument_default -- The default value for all arguments
1532
        - conflict_handler -- String indicating how to handle conflicts
1533
        - add_help -- Add a -h/-help option
1534
    """
1535

1536
    def __init__(
1537
        self,
1538
        prog=None,
1539
        usage=None,
1540
        description=None,
1541
        epilog=None,
1542
        version=None,
1543
        parents=[],
1544
        formatter_class=HelpFormatter,
1545
        prefix_chars="-",
1546
        fromfile_prefix_chars=None,
1547
        argument_default=None,
1548
        conflict_handler="error",
1549
        add_help=True,
1550
    ):
1551

1552
        if version is not None:
1553
            import warnings
1554

1555
            warnings.warn(
1556
                """The "version" argument to ArgumentParser is deprecated. """
1557
                """Please use """
1558
                """"add_argument(..., action='version', version="N", ...)" """
1559
                """instead""",
1560
                DeprecationWarning,
1561
            )
1562

1563
        superinit = super(ArgumentParser, self).__init__
1564
        superinit(
1565
            description=description,
1566
            prefix_chars=prefix_chars,
1567
            argument_default=argument_default,
1568
            conflict_handler=conflict_handler,
1569
        )
1570

1571
        # default setting for prog
1572
        if prog is None:
1573
            prog = _os.path.basename(_sys.argv[0])
1574

1575
        self.prog = prog
1576
        self.usage = usage
1577
        self.epilog = epilog
1578
        self.version = version
1579
        self.formatter_class = formatter_class
1580
        self.fromfile_prefix_chars = fromfile_prefix_chars
1581
        self.add_help = add_help
1582

1583
        add_group = self.add_argument_group
1584
        self._positionals = add_group(_("positional arguments"))
1585
        self._optionals = add_group(_("optional arguments"))
1586
        self._subparsers = None
1587

1588
        # register types
1589
        def identity(string):
1590
            return string
1591

1592
        self.register("type", None, identity)
1593

1594
        # add help and version arguments if necessary
1595
        # (using explicit default to override global argument_default)
1596
        if self.add_help:
1597
            self.add_argument(
1598
                "-h",
1599
                "--help",
1600
                action="help",
1601
                default=SUPPRESS,
1602
                help=_("show this help message and exit"),
1603
            )
1604
        if self.version:
1605
            self.add_argument(
1606
                "-v",
1607
                "--version",
1608
                action="version",
1609
                default=SUPPRESS,
1610
                version=self.version,
1611
                help=_("show program's version number and exit"),
1612
            )
1613

1614
        # add parent arguments and defaults
1615
        for parent in parents:
1616
            self._add_container_actions(parent)
1617
            try:
1618
                defaults = parent._defaults
1619
            except AttributeError:
1620
                pass
1621
            else:
1622
                self._defaults.update(defaults)
1623

1624
    # =======================
1625
    # Pretty __repr__ methods
1626
    # =======================
1627
    def _get_kwargs(self):
1628
        names = [
1629
            "prog",
1630
            "usage",
1631
            "description",
1632
            "version",
1633
            "formatter_class",
1634
            "conflict_handler",
1635
            "add_help",
1636
        ]
1637
        return [(name, getattr(self, name)) for name in names]
1638

1639
    # ==================================
1640
    # Optional/Positional adding methods
1641
    # ==================================
1642
    def add_subparsers(self, **kwargs):
1643
        if self._subparsers is not None:
1644
            self.error(_("cannot have multiple subparser arguments"))
1645

1646
        # add the parser class to the arguments if it's not present
1647
        kwargs.setdefault("parser_class", type(self))
1648

1649
        if "title" in kwargs or "description" in kwargs:
1650
            title = _(kwargs.pop("title", "subcommands"))
1651
            description = _(kwargs.pop("description", None))
1652
            self._subparsers = self.add_argument_group(title, description)
1653
        else:
1654
            self._subparsers = self._positionals
1655

1656
        # prog defaults to the usage message of this parser, skipping
1657
        # optional arguments and with no "usage:" prefix
1658
        if kwargs.get("prog") is None:
1659
            formatter = self._get_formatter()
1660
            positionals = self._get_positional_actions()
1661
            groups = self._mutually_exclusive_groups
1662
            formatter.add_usage(self.usage, positionals, groups, "")
1663
            kwargs["prog"] = formatter.format_help().strip()
1664

1665
        # create the parsers action and add it to the positionals list
1666
        parsers_class = self._pop_action_class(kwargs, "parsers")
1667
        action = parsers_class(option_strings=[], **kwargs)
1668
        self._subparsers._add_action(action)
1669

1670
        # return the created parsers action
1671
        return action
1672

1673
    def _add_action(self, action):
1674
        if action.option_strings:
1675
            self._optionals._add_action(action)
1676
        else:
1677
            self._positionals._add_action(action)
1678
        return action
1679

1680
    def _get_optional_actions(self):
1681
        return [action for action in self._actions if action.option_strings]
1682

1683
    def _get_positional_actions(self):
1684
        return [action for action in self._actions if not action.option_strings]
1685

1686
    # =====================================
1687
    # Command line argument parsing methods
1688
    # =====================================
1689
    def parse_args(self, args=None, namespace=None):
1690
        args, argv = self.parse_known_args(args, namespace)
1691
        if argv:
1692
            msg = _("unrecognized arguments: %s")
1693
            self.error(msg % " ".join(argv))
1694
        return args
1695

1696
    def parse_known_args(self, args=None, namespace=None):
1697
        # args default to the system args
1698
        if args is None:
1699
            args = _sys.argv[1:]
1700

1701
        # default Namespace built from parser defaults
1702
        if namespace is None:
1703
            namespace = Namespace()
1704

1705
        # add any action defaults that aren't present
1706
        for action in self._actions:
1707
            if action.dest is not SUPPRESS:
1708
                if not hasattr(namespace, action.dest):
1709
                    if action.default is not SUPPRESS:
1710
                        default = action.default
1711
                        if isinstance(action.default, _basestring):
1712
                            default = self._get_value(action, default)
1713
                        setattr(namespace, action.dest, default)
1714

1715
        # add any parser defaults that aren't present
1716
        for dest in self._defaults:
1717
            if not hasattr(namespace, dest):
1718
                setattr(namespace, dest, self._defaults[dest])
1719

1720
        # parse the arguments and exit if there are any errors
1721
        try:
1722
            return self._parse_known_args(args, namespace)
1723
        except ArgumentError:
1724
            err = _sys.exc_info()[1]
1725
            self.error(str(err))
1726

1727
    def _parse_known_args(self, arg_strings, namespace):
1728
        # replace arg strings that are file references
1729
        if self.fromfile_prefix_chars is not None:
1730
            arg_strings = self._read_args_from_files(arg_strings)
1731

1732
        # map all mutually exclusive arguments to the other arguments
1733
        # they can't occur with
1734
        action_conflicts = {}
1735
        for mutex_group in self._mutually_exclusive_groups:
1736
            group_actions = mutex_group._group_actions
1737
            for i, mutex_action in enumerate(mutex_group._group_actions):
1738
                conflicts = action_conflicts.setdefault(mutex_action, [])
1739
                conflicts.extend(group_actions[:i])
1740
                conflicts.extend(group_actions[i + 1 :])
1741

1742
        # find all option indices, and determine the arg_string_pattern
1743
        # which has an 'O' if there is an option at an index,
1744
        # an 'A' if there is an argument, or a '-' if there is a '--'
1745
        option_string_indices = {}
1746
        arg_string_pattern_parts = []
1747
        arg_strings_iter = iter(arg_strings)
1748
        for i, arg_string in enumerate(arg_strings_iter):
1749

1750
            # all args after -- are non-options
1751
            if arg_string == "--":
1752
                arg_string_pattern_parts.append("-")
1753
                for arg_string in arg_strings_iter:
1754
                    arg_string_pattern_parts.append("A")
1755

1756
            # otherwise, add the arg to the arg strings
1757
            # and note the index if it was an option
1758
            else:
1759
                option_tuple = self._parse_optional(arg_string)
1760
                if option_tuple is None:
1761
                    pattern = "A"
1762
                else:
1763
                    option_string_indices[i] = option_tuple
1764
                    pattern = "O"
1765
                arg_string_pattern_parts.append(pattern)
1766

1767
        # join the pieces together to form the pattern
1768
        arg_strings_pattern = "".join(arg_string_pattern_parts)
1769

1770
        # converts arg strings to the appropriate and then takes the action
1771
        seen_actions = _set()
1772
        seen_non_default_actions = _set()
1773

1774
        def take_action(action, argument_strings, option_string=None):
1775
            seen_actions.add(action)
1776
            argument_values = self._get_values(action, argument_strings)
1777

1778
            # error if this argument is not allowed with other previously
1779
            # seen arguments, assuming that actions that use the default
1780
            # value don't really count as "present"
1781
            if argument_values is not action.default:
1782
                seen_non_default_actions.add(action)
1783
                for conflict_action in action_conflicts.get(action, []):
1784
                    if conflict_action in seen_non_default_actions:
1785
                        msg = _("not allowed with argument %s")
1786
                        action_name = _get_action_name(conflict_action)
1787
                        raise ArgumentError(action, msg % action_name)
1788

1789
            # take the action if we didn't receive a SUPPRESS value
1790
            # (e.g. from a default)
1791
            if argument_values is not SUPPRESS:
1792
                action(self, namespace, argument_values, option_string)
1793

1794
        # function to convert arg_strings into an optional action
1795
        def consume_optional(start_index):
1796

1797
            # get the optional identified at this index
1798
            option_tuple = option_string_indices[start_index]
1799
            action, option_string, explicit_arg = option_tuple
1800

1801
            # identify additional optionals in the same arg string
1802
            # (e.g. -xyz is the same as -x -y -z if no args are required)
1803
            match_argument = self._match_argument
1804
            action_tuples = []
1805
            while True:
1806

1807
                # if we found no optional action, skip it
1808
                if action is None:
1809
                    extras.append(arg_strings[start_index])
1810
                    return start_index + 1
1811

1812
                # if there is an explicit argument, try to match the
1813
                # optional's string arguments to only this
1814
                if explicit_arg is not None:
1815
                    arg_count = match_argument(action, "A")
1816

1817
                    # if the action is a single-dash option and takes no
1818
                    # arguments, try to parse more single-dash options out
1819
                    # of the tail of the option string
1820
                    chars = self.prefix_chars
1821
                    if arg_count == 0 and option_string[1] not in chars:
1822
                        action_tuples.append((action, [], option_string))
1823
                        for char in self.prefix_chars:
1824
                            option_string = char + explicit_arg[0]
1825
                            explicit_arg = explicit_arg[1:] or None
1826
                            optionals_map = self._option_string_actions
1827
                            if option_string in optionals_map:
1828
                                action = optionals_map[option_string]
1829
                                break
1830
                        else:
1831
                            msg = _("ignored explicit argument %r")
1832
                            raise ArgumentError(action, msg % explicit_arg)
1833

1834
                    # if the action expect exactly one argument, we've
1835
                    # successfully matched the option; exit the loop
1836
                    elif arg_count == 1:
1837
                        stop = start_index + 1
1838
                        args = [explicit_arg]
1839
                        action_tuples.append((action, args, option_string))
1840
                        break
1841

1842
                    # error if a double-dash option did not use the
1843
                    # explicit argument
1844
                    else:
1845
                        msg = _("ignored explicit argument %r")
1846
                        raise ArgumentError(action, msg % explicit_arg)
1847

1848
                # if there is no explicit argument, try to match the
1849
                # optional's string arguments with the following strings
1850
                # if successful, exit the loop
1851
                else:
1852
                    start = start_index + 1
1853
                    selected_patterns = arg_strings_pattern[start:]
1854
                    arg_count = match_argument(action, selected_patterns)
1855
                    stop = start + arg_count
1856
                    args = arg_strings[start:stop]
1857
                    action_tuples.append((action, args, option_string))
1858
                    break
1859

1860
            # add the Optional to the list and return the index at which
1861
            # the Optional's string args stopped
1862
            assert action_tuples
1863
            for action, args, option_string in action_tuples:
1864
                take_action(action, args, option_string)
1865
            return stop
1866

1867
        # the list of Positionals left to be parsed; this is modified
1868
        # by consume_positionals()
1869
        positionals = self._get_positional_actions()
1870

1871
        # function to convert arg_strings into positional actions
1872
        def consume_positionals(start_index):
1873
            # match as many Positionals as possible
1874
            match_partial = self._match_arguments_partial
1875
            selected_pattern = arg_strings_pattern[start_index:]
1876
            arg_counts = match_partial(positionals, selected_pattern)
1877

1878
            # slice off the appropriate arg strings for each Positional
1879
            # and add the Positional and its args to the list
1880
            for action, arg_count in zip(positionals, arg_counts):
1881
                args = arg_strings[start_index : start_index + arg_count]
1882
                start_index += arg_count
1883
                take_action(action, args)
1884

1885
            # slice off the Positionals that we just parsed and return the
1886
            # index at which the Positionals' string args stopped
1887
            positionals[:] = positionals[len(arg_counts) :]
1888
            return start_index
1889

1890
        # consume Positionals and Optionals alternately, until we have
1891
        # passed the last option string
1892
        extras = []
1893
        start_index = 0
1894
        if option_string_indices:
1895
            max_option_string_index = max(option_string_indices)
1896
        else:
1897
            max_option_string_index = -1
1898
        while start_index <= max_option_string_index:
1899

1900
            # consume any Positionals preceding the next option
1901
            next_option_string_index = min(
1902
                [index for index in option_string_indices if index >= start_index]
1903
            )
1904
            if start_index != next_option_string_index:
1905
                positionals_end_index = consume_positionals(start_index)
1906

1907
                # only try to parse the next optional if we didn't consume
1908
                # the option string during the positionals parsing
1909
                if positionals_end_index > start_index:
1910
                    start_index = positionals_end_index
1911
                    continue
1912
                else:
1913
                    start_index = positionals_end_index
1914

1915
            # if we consumed all the positionals we could and we're not
1916
            # at the index of an option string, there were extra arguments
1917
            if start_index not in option_string_indices:
1918
                strings = arg_strings[start_index:next_option_string_index]
1919
                extras.extend(strings)
1920
                start_index = next_option_string_index
1921

1922
            # consume the next optional and any arguments for it
1923
            start_index = consume_optional(start_index)
1924

1925
        # consume any positionals following the last Optional
1926
        stop_index = consume_positionals(start_index)
1927

1928
        # if we didn't consume all the argument strings, there were extras
1929
        extras.extend(arg_strings[stop_index:])
1930

1931
        # if we didn't use all the Positional objects, there were too few
1932
        # arg strings supplied.
1933
        if positionals:
1934
            self.error(_("too few arguments"))
1935

1936
        # make sure all required actions were present
1937
        for action in self._actions:
1938
            if action.required:
1939
                if action not in seen_actions:
1940
                    name = _get_action_name(action)
1941
                    self.error(_("argument %s is required") % name)
1942

1943
        # make sure all required groups had one option present
1944
        for group in self._mutually_exclusive_groups:
1945
            if group.required:
1946
                for action in group._group_actions:
1947
                    if action in seen_non_default_actions:
1948
                        break
1949

1950
                # if no actions were used, report the error
1951
                else:
1952
                    names = [
1953
                        _get_action_name(action)
1954
                        for action in group._group_actions
1955
                        if action.help is not SUPPRESS
1956
                    ]
1957
                    msg = _("one of the arguments %s is required")
1958
                    self.error(msg % " ".join(names))
1959

1960
        # return the updated namespace and the extra arguments
1961
        return namespace, extras
1962

1963
    def _read_args_from_files(self, arg_strings):
1964
        # expand arguments referencing files
1965
        new_arg_strings = []
1966
        for arg_string in arg_strings:
1967

1968
            # for regular arguments, just add them back into the list
1969
            if arg_string[0] not in self.fromfile_prefix_chars:
1970
                new_arg_strings.append(arg_string)
1971

1972
            # replace arguments referencing files with the file content
1973
            else:
1974
                try:
1975
                    args_file = open(arg_string[1:])
1976
                    try:
1977
                        arg_strings = []
1978
                        for arg_line in args_file.read().splitlines():
1979
                            for arg in self.convert_arg_line_to_args(arg_line):
1980
                                arg_strings.append(arg)
1981
                        arg_strings = self._read_args_from_files(arg_strings)
1982
                        new_arg_strings.extend(arg_strings)
1983
                    finally:
1984
                        args_file.close()
1985
                except IOError:
1986
                    err = _sys.exc_info()[1]
1987
                    self.error(str(err))
1988

1989
        # return the modified argument list
1990
        return new_arg_strings
1991

1992
    def convert_arg_line_to_args(self, arg_line):
1993
        return [arg_line]
1994

1995
    def _match_argument(self, action, arg_strings_pattern):
1996
        # match the pattern for this action to the arg strings
1997
        nargs_pattern = self._get_nargs_pattern(action)
1998
        match = _re.match(nargs_pattern, arg_strings_pattern)
1999

2000
        # raise an exception if we weren't able to find a match
2001
        if match is None:
2002
            nargs_errors = {
2003
                None: _("expected one argument"),
2004
                OPTIONAL: _("expected at most one argument"),
2005
                ONE_OR_MORE: _("expected at least one argument"),
2006
            }
2007
            default = _("expected %s argument(s)") % action.nargs
2008
            msg = nargs_errors.get(action.nargs, default)
2009
            raise ArgumentError(action, msg)
2010

2011
        # return the number of arguments matched
2012
        return len(match.group(1))
2013

2014
    def _match_arguments_partial(self, actions, arg_strings_pattern):
2015
        # progressively shorten the actions list by slicing off the
2016
        # final actions until we find a match
2017
        result = []
2018
        for i in range(len(actions), 0, -1):
2019
            actions_slice = actions[:i]
2020
            pattern = "".join(
2021
                [self._get_nargs_pattern(action) for action in actions_slice]
2022
            )
2023
            match = _re.match(pattern, arg_strings_pattern)
2024
            if match is not None:
2025
                result.extend([len(string) for string in match.groups()])
2026
                break
2027

2028
        # return the list of arg string counts
2029
        return result
2030

2031
    def _parse_optional(self, arg_string):
2032
        # if it's an empty string, it was meant to be a positional
2033
        if not arg_string:
2034
            return None
2035

2036
        # if it doesn't start with a prefix, it was meant to be positional
2037
        if not arg_string[0] in self.prefix_chars:
2038
            return None
2039

2040
        # if the option string is present in the parser, return the action
2041
        if arg_string in self._option_string_actions:
2042
            action = self._option_string_actions[arg_string]
2043
            return action, arg_string, None
2044

2045
        # if it's just a single character, it was meant to be positional
2046
        if len(arg_string) == 1:
2047
            return None
2048

2049
        # if the option string before the "=" is present, return the action
2050
        if "=" in arg_string:
2051
            option_string, explicit_arg = arg_string.split("=", 1)
2052
            if option_string in self._option_string_actions:
2053
                action = self._option_string_actions[option_string]
2054
                return action, option_string, explicit_arg
2055

2056
        # search through all possible prefixes of the option string
2057
        # and all actions in the parser for possible interpretations
2058
        option_tuples = self._get_option_tuples(arg_string)
2059

2060
        # if multiple actions match, the option string was ambiguous
2061
        if len(option_tuples) > 1:
2062
            options = ", ".join(
2063
                [option_string for action, option_string, explicit_arg in option_tuples]
2064
            )
2065
            tup = arg_string, options
2066
            self.error(_("ambiguous option: %s could match %s") % tup)
2067

2068
        # if exactly one action matched, this segmentation is good,
2069
        # so return the parsed action
2070
        elif len(option_tuples) == 1:
2071
            (option_tuple,) = option_tuples
2072
            return option_tuple
2073

2074
        # if it was not found as an option, but it looks like a negative
2075
        # number, it was meant to be positional
2076
        # unless there are negative-number-like options
2077
        if self._negative_number_matcher.match(arg_string):
2078
            if not self._has_negative_number_optionals:
2079
                return None
2080

2081
        # if it contains a space, it was meant to be a positional
2082
        if " " in arg_string:
2083
            return None
2084

2085
        # it was meant to be an optional but there is no such option
2086
        # in this parser (though it might be a valid option in a subparser)
2087
        return None, arg_string, None
2088

2089
    def _get_option_tuples(self, option_string):
2090
        result = []
2091

2092
        # option strings starting with two prefix characters are only
2093
        # split at the '='
2094
        chars = self.prefix_chars
2095
        if option_string[0] in chars and option_string[1] in chars:
2096
            if "=" in option_string:
2097
                option_prefix, explicit_arg = option_string.split("=", 1)
2098
            else:
2099
                option_prefix = option_string
2100
                explicit_arg = None
2101
            for option_string in self._option_string_actions:
2102
                if option_string.startswith(option_prefix):
2103
                    action = self._option_string_actions[option_string]
2104
                    tup = action, option_string, explicit_arg
2105
                    result.append(tup)
2106

2107
        # single character options can be concatenated with their arguments
2108
        # but multiple character options always have to have their argument
2109
        # separate
2110
        elif option_string[0] in chars and option_string[1] not in chars:
2111
            option_prefix = option_string
2112
            explicit_arg = None
2113
            short_option_prefix = option_string[:2]
2114
            short_explicit_arg = option_string[2:]
2115

2116
            for option_string in self._option_string_actions:
2117
                if option_string == short_option_prefix:
2118
                    action = self._option_string_actions[option_string]
2119
                    tup = action, option_string, short_explicit_arg
2120
                    result.append(tup)
2121
                elif option_string.startswith(option_prefix):
2122
                    action = self._option_string_actions[option_string]
2123
                    tup = action, option_string, explicit_arg
2124
                    result.append(tup)
2125

2126
        # shouldn't ever get here
2127
        else:
2128
            self.error(_("unexpected option string: %s") % option_string)
2129

2130
        # return the collected option tuples
2131
        return result
2132

2133
    def _get_nargs_pattern(self, action):
2134
        # in all examples below, we have to allow for '--' args
2135
        # which are represented as '-' in the pattern
2136
        nargs = action.nargs
2137

2138
        # the default (None) is assumed to be a single argument
2139
        if nargs is None:
2140
            nargs_pattern = "(-*A-*)"
2141

2142
        # allow zero or one arguments
2143
        elif nargs == OPTIONAL:
2144
            nargs_pattern = "(-*A?-*)"
2145

2146
        # allow zero or more arguments
2147
        elif nargs == ZERO_OR_MORE:
2148
            nargs_pattern = "(-*[A-]*)"
2149

2150
        # allow one or more arguments
2151
        elif nargs == ONE_OR_MORE:
2152
            nargs_pattern = "(-*A[A-]*)"
2153

2154
        # allow any number of options or arguments
2155
        elif nargs == REMAINDER:
2156
            nargs_pattern = "([-AO]*)"
2157

2158
        # allow one argument followed by any number of options or arguments
2159
        elif nargs == PARSER:
2160
            nargs_pattern = "(-*A[-AO]*)"
2161

2162
        # all others should be integers
2163
        else:
2164
            nargs_pattern = "(-*%s-*)" % "-*".join("A" * nargs)
2165

2166
        # if this is an optional action, -- is not allowed
2167
        if action.option_strings:
2168
            nargs_pattern = nargs_pattern.replace("-*", "")
2169
            nargs_pattern = nargs_pattern.replace("-", "")
2170

2171
        # return the pattern
2172
        return nargs_pattern
2173

2174
    # ========================
2175
    # Value conversion methods
2176
    # ========================
2177
    def _get_values(self, action, arg_strings):
2178
        # for everything but PARSER args, strip out '--'
2179
        if action.nargs not in [PARSER, REMAINDER]:
2180
            arg_strings = [s for s in arg_strings if s != "--"]
2181

2182
        # optional argument produces a default when not present
2183
        if not arg_strings and action.nargs == OPTIONAL:
2184
            if action.option_strings:
2185
                value = action.const
2186
            else:
2187
                value = action.default
2188
            if isinstance(value, _basestring):
2189
                value = self._get_value(action, value)
2190
                self._check_value(action, value)
2191

2192
        # when nargs='*' on a positional, if there were no command-line
2193
        # args, use the default if it is anything other than None
2194
        elif (
2195
            not arg_strings
2196
            and action.nargs == ZERO_OR_MORE
2197
            and not action.option_strings
2198
        ):
2199
            if action.default is not None:
2200
                value = action.default
2201
            else:
2202
                value = arg_strings
2203
            self._check_value(action, value)
2204

2205
        # single argument or optional argument produces a single value
2206
        elif len(arg_strings) == 1 and action.nargs in [None, OPTIONAL]:
2207
            (arg_string,) = arg_strings
2208
            value = self._get_value(action, arg_string)
2209
            self._check_value(action, value)
2210

2211
        # REMAINDER arguments convert all values, checking none
2212
        elif action.nargs == REMAINDER:
2213
            value = [self._get_value(action, v) for v in arg_strings]
2214

2215
        # PARSER arguments convert all values, but check only the first
2216
        elif action.nargs == PARSER:
2217
            value = [self._get_value(action, v) for v in arg_strings]
2218
            self._check_value(action, value[0])
2219

2220
        # all other types of nargs produce a list
2221
        else:
2222
            value = [self._get_value(action, v) for v in arg_strings]
2223
            for v in value:
2224
                self._check_value(action, v)
2225

2226
        # return the converted value
2227
        return value
2228

2229
    def _get_value(self, action, arg_string):
2230
        type_func = self._registry_get("type", action.type, action.type)
2231
        if not _callable(type_func):
2232
            msg = _("%r is not callable")
2233
            raise ArgumentError(action, msg % type_func)
2234

2235
        # convert the value to the appropriate type
2236
        try:
2237
            result = type_func(arg_string)
2238

2239
        # ArgumentTypeErrors indicate errors
2240
        except ArgumentTypeError:
2241
            name = getattr(action.type, "__name__", repr(action.type))
2242
            msg = str(_sys.exc_info()[1])
2243
            raise ArgumentError(action, msg)
2244

2245
        # TypeErrors or ValueErrors also indicate errors
2246
        except (TypeError, ValueError):
2247
            name = getattr(action.type, "__name__", repr(action.type))
2248
            msg = _("invalid %s value: %r")
2249
            raise ArgumentError(action, msg % (name, arg_string))
2250

2251
        # return the converted value
2252
        return result
2253

2254
    def _check_value(self, action, value):
2255
        # converted value must be one of the choices (if specified)
2256
        if action.choices is not None and value not in action.choices:
2257
            tup = value, ", ".join(map(repr, action.choices))
2258
            msg = _("invalid choice: %r (choose from %s)") % tup
2259
            raise ArgumentError(action, msg)
2260

2261
    # =======================
2262
    # Help-formatting methods
2263
    # =======================
2264
    def format_usage(self):
2265
        formatter = self._get_formatter()
2266
        formatter.add_usage(self.usage, self._actions, self._mutually_exclusive_groups)
2267
        return formatter.format_help()
2268

2269
    def format_help(self):
2270
        formatter = self._get_formatter()
2271

2272
        # usage
2273
        formatter.add_usage(self.usage, self._actions, self._mutually_exclusive_groups)
2274

2275
        # description
2276
        formatter.add_text(self.description)
2277

2278
        # positionals, optionals and user-defined groups
2279
        for action_group in self._action_groups:
2280
            formatter.start_section(action_group.title)
2281
            formatter.add_text(action_group.description)
2282
            formatter.add_arguments(action_group._group_actions)
2283
            formatter.end_section()
2284

2285
        # epilog
2286
        formatter.add_text(self.epilog)
2287

2288
        # determine help from format above
2289
        return formatter.format_help()
2290

2291
    def format_version(self):
2292
        import warnings
2293

2294
        warnings.warn(
2295
            'The format_version method is deprecated -- the "version" '
2296
            "argument to ArgumentParser is no longer supported.",
2297
            DeprecationWarning,
2298
        )
2299
        formatter = self._get_formatter()
2300
        formatter.add_text(self.version)
2301
        return formatter.format_help()
2302

2303
    def _get_formatter(self):
2304
        return self.formatter_class(prog=self.prog)
2305

2306
    # =====================
2307
    # Help-printing methods
2308
    # =====================
2309
    def print_usage(self, file=None):
2310
        if file is None:
2311
            file = _sys.stdout
2312
        self._print_message(self.format_usage(), file)
2313

2314
    def print_help(self, file=None):
2315
        if file is None:
2316
            file = _sys.stdout
2317
        self._print_message(self.format_help(), file)
2318

2319
    def print_version(self, file=None):
2320
        import warnings
2321

2322
        warnings.warn(
2323
            'The print_version method is deprecated -- the "version" '
2324
            "argument to ArgumentParser is no longer supported.",
2325
            DeprecationWarning,
2326
        )
2327
        self._print_message(self.format_version(), file)
2328

2329
    def _print_message(self, message, file=None):
2330
        if message:
2331
            if file is None:
2332
                file = _sys.stderr
2333
            file.write(message)
2334

2335
    # ===============
2336
    # Exiting methods
2337
    # ===============
2338
    def exit(self, status=0, message=None):
2339
        if message:
2340
            self._print_message(message, _sys.stderr)
2341
        _sys.exit(status)
2342

2343
    def error(self, message):
2344
        """error(message: string)
2345

2346
        Prints a usage message incorporating the message to stderr and
2347
        exits.
2348

2349
        If you override this in a subclass, it should not return -- it
2350
        should either exit or raise an exception.
2351
        """
2352
        self.print_usage(_sys.stderr)
2353
        self.exit(2, _("%s: error: %s\n") % (self.prog, message))
2354