argparse.py
1
# Author: Steven J. Bethard <[email protected]>.
2
# New maintainer as of 29 August 2019: Raymond Hettinger <[email protected]>
3
4
"""Command-line parsing library
5
6
This module is an optparse-inspired command-line parsing library that:
7
8
- handles both optional and positional arguments
9
- produces highly informative usage messages
10
- supports parsers that dispatch to sub-parsers
11
12
The following is a simple usage example that sums integers from the
13
command-line and writes the result to a file::
14
15
parser = argparse.ArgumentParser(
16
description='sum the integers at the command line')
17
parser.add_argument(
18
'integers', metavar='int', nargs='+', type=int,
19
help='an integer to be summed')
20
parser.add_argument(
21
'--log', default=sys.stdout, type=argparse.FileType('w'),
22
help='the file where the sum should be written')
23
args = parser.parse_args()
24
args.log.write('%s' % sum(args.integers))
25
args.log.close()
26
27
The module contains the following public classes:
28
29
- ArgumentParser -- The main entry point for command-line parsing. As the
30
example above shows, the add_argument() method is used to populate
31
the parser with actions for optional and positional arguments. Then
32
the parse_args() method is invoked to convert the args at the
33
command-line into an object with attributes.
34
35
- ArgumentError -- The exception raised by ArgumentParser objects when
36
there are errors with the parser's actions. Errors raised while
37
parsing the command-line are caught by ArgumentParser and emitted
38
as command-line messages.
39
40
- FileType -- A factory for defining types of files to be created. As the
41
example above shows, instances of FileType are typically passed as
42
the type= argument of add_argument() calls.
43
44
- Action -- The base class for parser actions. Typically actions are
45
selected by passing strings like 'store_true' or 'append_const' to
46
the action= argument of add_argument(). However, for greater
47
customization of ArgumentParser actions, subclasses of Action may
48
be defined and passed as the action= argument.
49
50
- HelpFormatter, RawDescriptionHelpFormatter, RawTextHelpFormatter,
51
ArgumentDefaultsHelpFormatter -- Formatter classes which
52
may be passed as the formatter_class= argument to the
53
ArgumentParser constructor. HelpFormatter is the default,
54
RawDescriptionHelpFormatter and RawTextHelpFormatter tell the parser
55
not to change the formatting for help text, and
56
ArgumentDefaultsHelpFormatter adds information about argument defaults
57
to the help.
58
59
All other classes in this module are considered implementation details.
60
(Also note that HelpFormatter and RawDescriptionHelpFormatter are only
61
considered public as object names -- the API of the formatter objects is
62
still considered an implementation detail.)
63
"""
64
65
__version__ = '1.1'
66
__all__ = [
67
'ArgumentParser',
68
'ArgumentError',
69
'ArgumentTypeError',
70
'BooleanOptionalAction',
71
'FileType',
72
'HelpFormatter',
73
'ArgumentDefaultsHelpFormatter',
74
'RawDescriptionHelpFormatter',
75
'RawTextHelpFormatter',
76
'MetavarTypeHelpFormatter',
77
'Namespace',
78
'Action',
79
'ONE_OR_MORE',
80
'OPTIONAL',
81
'PARSER',
82
'REMAINDER',
83
'SUPPRESS',
84
'ZERO_OR_MORE',
85
]
86
87
88
import os as _os
89
import re as _re
90
import sys as _sys
91
92
from gettext import gettext as _, ngettext
93
94
SUPPRESS = '==SUPPRESS=='
95
96
OPTIONAL = '?'
97
ZERO_OR_MORE = '*'
98
ONE_OR_MORE = '+'
99
PARSER = 'A...'
100
REMAINDER = '...'
101
_UNRECOGNIZED_ARGS_ATTR = '_unrecognized_args'
102
103
# =============================
104
# Utility functions and classes
105
# =============================
106
107
class _AttributeHolder(object):
108
"""Abstract base class that provides __repr__.
109
110
The __repr__ method returns a string in the format::
111
ClassName(attr=name, attr=name, ...)
112
The attributes are determined either by a class-level attribute,
113
'_kwarg_names', or by inspecting the instance __dict__.
114
"""
115
116
def __repr__(self):
117
type_name = type(self).__name__
118
arg_strings = []
119
star_args = {}
120
for arg in self._get_args():
121
arg_strings.append(repr(arg))
122
for name, value in self._get_kwargs():
123
if name.isidentifier():
124
arg_strings.append('%s=%r' % (name, value))
125
else:
126
star_args[name] = value
127
if star_args:
128
arg_strings.append('**%s' % repr(star_args))
129
return '%s(%s)' % (type_name, ', '.join(arg_strings))
130
131
def _get_kwargs(self):
132
return sorted(self.__dict__.items())
133
134
def _get_args(self):
135
return []
136
137
138
def _copy_items(items):
139
if items is None:
140
return []
141
# The copy module is used only in the 'append' and 'append_const'
142
# actions, and it is needed only when the default value isn't a list.
143
# Delay its import for speeding up the common case.
144
if type(items) is list:
145
return items[:]
146
import copy
147
return copy.copy(items)
148
149
150
# ===============
151
# Formatting Help
152
# ===============
153
154
class HelpFormatter(object):
155
"""Formatter for generating usage messages and argument help strings.
156
157
Only the name of this class is considered a public API. All the methods
158
provided by the class are considered an implementation detail.
159
"""
160
161
def __init__(self,
162
prog,
163
indent_increment=2,
164
max_help_position=24,
165
width=None):
166
167
# default setting for width
168
if width is None:
169
import shutil
170
width = shutil.get_terminal_size().columns
171
width -= 2
172
173
self._prog = prog
174
self._indent_increment = indent_increment
175
self._max_help_position = min(max_help_position,
176
max(width - 20, indent_increment * 2))
177
self._width = width
178
179
self._current_indent = 0
180
self._level = 0
181
self._action_max_length = 0
182
183
self._root_section = self._Section(self, None)
184
self._current_section = self._root_section
185
186
self._whitespace_matcher = _re.compile(r'\s+', _re.ASCII)
187
self._long_break_matcher = _re.compile(r'\n\n\n+')
188
189
# ===============================
190
# Section and indentation methods
191
# ===============================
192
def _indent(self):
193
self._current_indent += self._indent_increment
194
self._level += 1
195
196
def _dedent(self):
197
self._current_indent -= self._indent_increment
198
assert self._current_indent >= 0, 'Indent decreased below 0.'
199
self._level -= 1
200
201
class _Section(object):
202
203
def __init__(self, formatter, parent, heading=None):
204
self.formatter = formatter
205
self.parent = parent
206
self.heading = heading
207
self.items = []
208
209
def format_help(self):
210
# format the indented section
211
if self.parent is not None:
212
self.formatter._indent()
213
join = self.formatter._join_parts
214
item_help = join([func(*args) for func, args in self.items])
215
if self.parent is not None:
216
self.formatter._dedent()
217
218
# return nothing if the section was empty
219
if not item_help:
220
return ''
221
222
# add the heading if the section was non-empty
223
if self.heading is not SUPPRESS and self.heading is not None:
224
current_indent = self.formatter._current_indent
225
heading = '%*s%s:\n' % (current_indent, '', self.heading)
226
else:
227
heading = ''
228
229
# join the section-initial newline, the heading and the help
230
return join(['\n', heading, item_help, '\n'])
231
232
def _add_item(self, func, args):
233
self._current_section.items.append((func, args))
234
235
# ========================
236
# Message building methods
237
# ========================
238
def start_section(self, heading):
239
self._indent()
240
section = self._Section(self, self._current_section, heading)
241
self._add_item(section.format_help, [])
242
self._current_section = section
243
244
def end_section(self):
245
self._current_section = self._current_section.parent
246
self._dedent()
247
248
def add_text(self, text):
249
if text is not SUPPRESS and text is not None:
250
self._add_item(self._format_text, [text])
251
252
def add_usage(self, usage, actions, groups, prefix=None):
253
if usage is not SUPPRESS:
254
args = usage, actions, groups, prefix
255
self._add_item(self._format_usage, args)
256
257
def add_argument(self, action):
258
if action.help is not SUPPRESS:
259
260
# find all invocations
261
get_invocation = self._format_action_invocation
262
invocations = [get_invocation(action)]
263
for subaction in self._iter_indented_subactions(action):
264
invocations.append(get_invocation(subaction))
265
266
# update the maximum item length
267
invocation_length = max(map(len, invocations))
268
action_length = invocation_length + self._current_indent
269
self._action_max_length = max(self._action_max_length,
270
action_length)
271
272
# add the item to the list
273
self._add_item(self._format_action, [action])
274
275
def add_arguments(self, actions):
276
for action in actions:
277
self.add_argument(action)
278
279
# =======================
280
# Help-formatting methods
281
# =======================
282
def format_help(self):
283
help = self._root_section.format_help()
284
if help:
285
help = self._long_break_matcher.sub('\n\n', help)
286
help = help.strip('\n') + '\n'
287
return help
288
289
def _join_parts(self, part_strings):
290
return ''.join([part
291
for part in part_strings
292
if part and part is not SUPPRESS])
293
294
def _format_usage(self, usage, actions, groups, prefix):
295
if prefix is None:
296
prefix = _('usage: ')
297
298
# if usage is specified, use that
299
if usage is not None:
300
usage = usage % dict(prog=self._prog)
301
302
# if no optionals or positionals are available, usage is just prog
303
elif usage is None and not actions:
304
usage = '%(prog)s' % dict(prog=self._prog)
305
306
# if optionals and positionals are available, calculate usage
307
elif usage is None:
308
prog = '%(prog)s' % dict(prog=self._prog)
309
310
# split optionals from positionals
311
optionals = []
312
positionals = []
313
for action in actions:
314
if action.option_strings:
315
optionals.append(action)
316
else:
317
positionals.append(action)
318
319
# build full usage string
320
format = self._format_actions_usage
321
action_usage = format(optionals + positionals, groups)
322
usage = ' '.join([s for s in [prog, action_usage] if s])
323
324
# wrap the usage parts if it's too long
325
text_width = self._width - self._current_indent
326
if len(prefix) + len(usage) > text_width:
327
328
# break usage into wrappable parts
329
part_regexp = (
330
r'\(.*?\)+(?=\s|$)|'
331
r'\[.*?\]+(?=\s|$)|'
332
r'\S+'
333
)
334
opt_usage = format(optionals, groups)
335
pos_usage = format(positionals, groups)
336
opt_parts = _re.findall(part_regexp, opt_usage)
337
pos_parts = _re.findall(part_regexp, pos_usage)
338
assert ' '.join(opt_parts) == opt_usage
339
assert ' '.join(pos_parts) == pos_usage
340
341
# helper for wrapping lines
342
def get_lines(parts, indent, prefix=None):
343
lines = []
344
line = []
345
if prefix is not None:
346
line_len = len(prefix) - 1
347
else:
348
line_len = len(indent) - 1
349
for part in parts:
350
if line_len + 1 + len(part) > text_width and line:
351
lines.append(indent + ' '.join(line))
352
line = []
353
line_len = len(indent) - 1
354
line.append(part)
355
line_len += len(part) + 1
356
if line:
357
lines.append(indent + ' '.join(line))
358
if prefix is not None:
359
lines[0] = lines[0][len(indent):]
360
return lines
361
362
# if prog is short, follow it with optionals or positionals
363
if len(prefix) + len(prog) <= 0.75 * text_width:
364
indent = ' ' * (len(prefix) + len(prog) + 1)
365
if opt_parts:
366
lines = get_lines([prog] + opt_parts, indent, prefix)
367
lines.extend(get_lines(pos_parts, indent))
368
elif pos_parts:
369
lines = get_lines([prog] + pos_parts, indent, prefix)
370
else:
371
lines = [prog]
372
373
# if prog is long, put it on its own line
374
else:
375
indent = ' ' * len(prefix)
376
parts = opt_parts + pos_parts
377
lines = get_lines(parts, indent)
378
if len(lines) > 1:
379
lines = []
380
lines.extend(get_lines(opt_parts, indent))
381
lines.extend(get_lines(pos_parts, indent))
382
lines = [prog] + lines
383
384
# join lines into usage
385
usage = '\n'.join(lines)
386
387
# prefix with 'usage:'
388
return '%s%s\n\n' % (prefix, usage)
389
390
def _format_actions_usage(self, actions, groups):
391
# find group indices and identify actions in groups
392
group_actions = set()
393
inserts = {}
394
for group in groups:
395
try:
396
start = actions.index(group._group_actions[0])
397
except ValueError:
398
continue
399
else:
400
end = start + len(group._group_actions)
401
if actions[start:end] == group._group_actions:
402
for action in group._group_actions:
403
group_actions.add(action)
404
if not group.required:
405
if start in inserts:
406
inserts[start] += ' ['
407
else:
408
inserts[start] = '['
409
if end in inserts:
410
inserts[end] += ']'
411
else:
412
inserts[end] = ']'
414
if start in inserts:
415
inserts[start] += ' ('
416
else:
417
inserts[start] = '('
418
if end in inserts:
419
inserts[end] += ')'
420
else:
421
inserts[end] = ')'
422
for i in range(start + 1, end):
423
inserts[i] = '|'
424
425
# collect all actions format strings
426
parts = []
427
for i, action in enumerate(actions):
428
429
# suppressed arguments are marked with None
430
# remove | separators for suppressed arguments
431
if action.help is SUPPRESS:
432
parts.append(None)
433
if inserts.get(i) == '|':
434
inserts.pop(i)
435
elif inserts.get(i + 1) == '|':
436
inserts.pop(i + 1)
437
438
# produce all arg strings
439
elif not action.option_strings:
440
default = self._get_default_metavar_for_positional(action)
441
part = self._format_args(action, default)
442
443
# if it's in a group, strip the outer []
444
if action in group_actions:
445
if part[0] == '[' and part[-1] == ']':
446
part = part[1:-1]
447
448
# add the action string to the list
449
parts.append(part)
450
451
# produce the first way to invoke the option in brackets
452
else:
453
option_string = action.option_strings[0]
454
455
# if the Optional doesn't take a value, format is:
456
# -s or --long
457
if action.nargs == 0:
458
part = action.format_usage()
459
460
# if the Optional takes a value, format is:
461
# -s ARGS or --long ARGS
462
else:
463
default = self._get_default_metavar_for_optional(action)
464
args_string = self._format_args(action, default)
465
part = '%s %s' % (option_string, args_string)
466
467
# make it look optional if it's not required or in a group
468
if not action.required and action not in group_actions:
469
part = '[%s]' % part
470
471
# add the action string to the list
472
parts.append(part)
473
474
# insert things at the necessary indices
475
for i in sorted(inserts, reverse=True):
476
parts[i:i] = [inserts[i]]
477
478
# join all the action items with spaces
479
text = ' '.join([item for item in parts if item is not None])
480
481
# clean up separators for mutually exclusive groups
482
open = r'[\[(]'
483
close = r'[\])]'
484
text = _re.sub(r'(%s) ' % open, r'\1', text)
485
text = _re.sub(r' (%s)' % close, r'\1', text)
486
text = _re.sub(r'%s *%s' % (open, close), r'', text)
487
text = _re.sub(r'\(([^|]*)\)', r'\1', text)
488
text = text.strip()
489
490
# return the text
491
return text
492
493
def _format_text(self, text):
494
if '%(prog)' in text:
495
text = text % dict(prog=self._prog)
496
text_width = max(self._width - self._current_indent, 11)
497
indent = ' ' * self._current_indent
498
return self._fill_text(text, text_width, indent) + '\n\n'
499
500
def _format_action(self, action):
501
# determine the required width and the entry label
502
help_position = min(self._action_max_length + 2,
503
self._max_help_position)
504
help_width = max(self._width - help_position, 11)
505
action_width = help_position - self._current_indent - 2
506
action_header = self._format_action_invocation(action)
507
508
# no help; start on same line and add a final newline
509
if not action.help:
510
tup = self._current_indent, '', action_header
511
action_header = '%*s%s\n' % tup
512
513
# short action name; start on the same line and pad two spaces
514
elif len(action_header) <= action_width:
515
tup = self._current_indent, '', action_width, action_header
516
action_header = '%*s%-*s ' % tup
517
indent_first = 0
518
519
# long action name; start on the next line
520
else:
521
tup = self._current_indent, '', action_header
522
action_header = '%*s%s\n' % tup
523
indent_first = help_position
524
525
# collect the pieces of the action help
526
parts = [action_header]
527
528
# if there was help for the action, add lines of help text
529
if action.help:
530
help_text = self._expand_help(action)
531
help_lines = self._split_lines(help_text, help_width)
532
parts.append('%*s%s\n' % (indent_first, '', help_lines[0]))
533
for line in help_lines[1:]:
534
parts.append('%*s%s\n' % (help_position, '', line))
535
536
# or add a newline if the description doesn't end with one
537
elif not action_header.endswith('\n'):
538
parts.append('\n')
539
540
# if there are any sub-actions, add their help as well
541
for subaction in self._iter_indented_subactions(action):
542
parts.append(self._format_action(subaction))
543
544
# return a single string
545
return self._join_parts(parts)
546
547
def _format_action_invocation(self, action):
548
if not action.option_strings:
549
default = self._get_default_metavar_for_positional(action)
550
metavar, = self._metavar_formatter(action, default)(1)
551
return metavar
552
553
else:
554
parts = []
555
556
# if the Optional doesn't take a value, format is:
557
# -s, --long
558
if action.nargs == 0:
559
parts.extend(action.option_strings)
560
561
# if the Optional takes a value, format is:
562
# -s ARGS, --long ARGS
563
else:
564
default = self._get_default_metavar_for_optional(action)
565
args_string = self._format_args(action, default)
566
for option_string in action.option_strings:
567
parts.append('%s %s' % (option_string, args_string))
568
569
return ', '.join(parts)
570
571
def _metavar_formatter(self, action, default_metavar):
572
if action.metavar is not None:
573
result = action.metavar
574
elif action.choices is not None:
575
choice_strs = [str(choice) for choice in action.choices]
576
result = '{%s}' % ','.join(choice_strs)
577
else:
578
result = default_metavar
579
580
def format(tuple_size):
581
if isinstance(result, tuple):
582
return result
583
else:
584
return (result, ) * tuple_size
585
return format
586
587
def _format_args(self, action, default_metavar):
588
get_metavar = self._metavar_formatter(action, default_metavar)
589
if action.nargs is None:
590
result = '%s' % get_metavar(1)
591
elif action.nargs == OPTIONAL:
592
result = '[%s]' % get_metavar(1)
593
elif action.nargs == ZERO_OR_MORE:
594
metavar = get_metavar(1)
595
if len(metavar) == 2:
596
result = '[%s [%s ...]]' % metavar
597
else:
598
result = '[%s ...]' % metavar
599
elif action.nargs == ONE_OR_MORE:
600
result = '%s [%s ...]' % get_metavar(2)
601
elif action.nargs == REMAINDER:
602
result = '...'
603
elif action.nargs == PARSER:
604
result = '%s ...' % get_metavar(1)
605
elif action.nargs == SUPPRESS:
606
result = ''
608
try:
609
formats = ['%s' for _ in range(action.nargs)]
610
except TypeError:
611
raise ValueError("invalid nargs value") from None
612
result = ' '.join(formats) % get_metavar(action.nargs)
613
return result
614
615
def _expand_help(self, action):
616
params = dict(vars(action), prog=self._prog)
617
for name in list(params):
618
if params[name] is SUPPRESS:
619
del params[name]
620
for name in list(params):
621
if hasattr(params[name], '__name__'):
622
params[name] = params[name].__name__
623
if params.get('choices') is not None:
624
choices_str = ', '.join([str(c) for c in params['choices']])
625
params['choices'] = choices_str
626
return self._get_help_string(action) % params
627
628
def _iter_indented_subactions(self, action):
629
try:
630
get_subactions = action._get_subactions
631
except AttributeError:
632
pass
633
else:
634
self._indent()
635
yield from get_subactions()
636
self._dedent()
637
638
def _split_lines(self, text, width):
639
text = self._whitespace_matcher.sub(' ', text).strip()
640
# The textwrap module is used only for formatting help.
641
# Delay its import for speeding up the common usage of argparse.
642
import textwrap
643
return textwrap.wrap(text, width)
644
645
def _fill_text(self, text, width, indent):
646
text = self._whitespace_matcher.sub(' ', text).strip()
647
import textwrap
648
return textwrap.fill(text, width,
649
initial_indent=indent,
650
subsequent_indent=indent)
651
652
def _get_help_string(self, action):
653
return action.help
654
655
def _get_default_metavar_for_optional(self, action):
656
return action.dest.upper()
657
658
def _get_default_metavar_for_positional(self, action):
659
return action.dest
660
661
662
class RawDescriptionHelpFormatter(HelpFormatter):
663
"""Help message formatter which retains any formatting in descriptions.
664
665
Only the name of this class is considered a public API. All the methods
666
provided by the class are considered an implementation detail.
667
"""
668
669
def _fill_text(self, text, width, indent):
670
return ''.join(indent + line for line in text.splitlines(keepends=True))
671
672
673
class RawTextHelpFormatter(RawDescriptionHelpFormatter):
674
"""Help message formatter which retains formatting of all help text.
675
676
Only the name of this class is considered a public API. All the methods
677
provided by the class are considered an implementation detail.
678
"""
679
680
def _split_lines(self, text, width):
681
return text.splitlines()
682
683
684
class ArgumentDefaultsHelpFormatter(HelpFormatter):
685
"""Help message formatter which adds default values to argument help.
686
687
Only the name of this class is considered a public API. All the methods
688
provided by the class are considered an implementation detail.
689
"""
690
691
def _get_help_string(self, action):
692
help = action.help
693
if '%(default)' not in action.help:
694
if action.default is not SUPPRESS:
695
defaulting_nargs = [OPTIONAL, ZERO_OR_MORE]
696
if action.option_strings or action.nargs in defaulting_nargs:
697
help += ' (default: %(default)s)'
698
return help
699
700
701
class MetavarTypeHelpFormatter(HelpFormatter):
702
"""Help message formatter which uses the argument 'type' as the default
703
metavar value (instead of the argument 'dest')
704
705
Only the name of this class is considered a public API. All the methods
706
provided by the class are considered an implementation detail.
707
"""
708
709
def _get_default_metavar_for_optional(self, action):
710
return action.type.__name__
711
712
def _get_default_metavar_for_positional(self, action):
713
return action.type.__name__
714
715
716
717
# =====================
718
# Options and Arguments
719
# =====================
720
721
def _get_action_name(argument):
722
if argument is None:
723
return None
724
elif argument.option_strings:
725
return '/'.join(argument.option_strings)
726
elif argument.metavar not in (None, SUPPRESS):
727
return argument.metavar
728
elif argument.dest not in (None, SUPPRESS):
729
return argument.dest
730
else:
731
return None
732
733
734
class ArgumentError(Exception):
735
"""An error from creating or using an argument (optional or positional).
736
737
The string value of this exception is the message, augmented with
738
information about the argument that caused it.
739
"""
740
741
def __init__(self, argument, message):
742
self.argument_name = _get_action_name(argument)
743
self.message = message
744
745
def __str__(self):
746
if self.argument_name is None:
747
format = '%(message)s'
748
else:
749
format = 'argument %(argument_name)s: %(message)s'
750
return format % dict(message=self.message,
751
argument_name=self.argument_name)
752
753
754
class ArgumentTypeError(Exception):
755
"""An error from trying to convert a command line string to a type."""
756
pass
757
758
759
# ==============
760
# Action classes
761
# ==============
762
763
class Action(_AttributeHolder):
764
"""Information about how to convert command line strings to Python objects.
765
766
Action objects are used by an ArgumentParser to represent the information
767
needed to parse a single argument from one or more strings from the
768
command line. The keyword arguments to the Action constructor are also
769
all attributes of Action instances.
770
771
Keyword Arguments:
772
773
- option_strings -- A list of command-line option strings which
774
should be associated with this action.
775
776
- dest -- The name of the attribute to hold the created object(s)
777
778
- nargs -- The number of command-line arguments that should be
779
consumed. By default, one argument will be consumed and a single
780
value will be produced. Other values include:
781
- N (an integer) consumes N arguments (and produces a list)
782
- '?' consumes zero or one arguments
783
- '*' consumes zero or more arguments (and produces a list)
784
- '+' consumes one or more arguments (and produces a list)
785
Note that the difference between the default and nargs=1 is that
786
with the default, a single value will be produced, while with
787
nargs=1, a list containing a single value will be produced.
788
789
- const -- The value to be produced if the option is specified and the
790
option uses an action that takes no values.
791
792
- default -- The value to be produced if the option is not specified.
793
794
- type -- A callable that accepts a single string argument, and
795
returns the converted value. The standard Python types str, int,
796
float, and complex are useful examples of such callables. If None,
797
str is used.
798
799
- choices -- A container of values that should be allowed. If not None,
800
after a command-line argument has been converted to the appropriate
801
type, an exception will be raised if it is not a member of this
802
collection.
803
804
- required -- True if the action must always be specified at the
805
command line. This is only meaningful for optional command-line
806
arguments.
807
808
- help -- The help string describing the argument.
809
810
- metavar -- The name to be used for the option's argument with the
811
help string. If None, the 'dest' value will be used as the name.
812
"""
813
814
def __init__(self,
815
option_strings,
816
dest,
817
nargs=None,
818
const=None,
819
default=None,
820
type=None,
821
choices=None,
822
required=False,
823
help=None,
824
metavar=None):
825
self.option_strings = option_strings
826
self.dest = dest
827
self.nargs = nargs
828
self.const = const
829
self.default = default
830
self.type = type
831
self.choices = choices
832
self.required = required
833
self.help = help
834
self.metavar = metavar
835
836
def _get_kwargs(self):
837
names = [
838
'option_strings',
839
'dest',
840
'nargs',
841
'const',
842
'default',
843
'type',
844
'choices',
845
'help',
846
'metavar',
847
]
848
return [(name, getattr(self, name)) for name in names]
849
850
def format_usage(self):
851
return self.option_strings[0]
852
853
def __call__(self, parser, namespace, values, option_string=None):
854
raise NotImplementedError(_('.__call__() not defined'))
855
856
class BooleanOptionalAction(Action):
857
def __init__(self,
858
option_strings,
859
dest,
860
const=None,
861
default=None,
862
type=None,
863
choices=None,
864
required=False,
865
help=None,
866
metavar=None):
867
868
_option_strings = []
869
for option_string in option_strings:
870
_option_strings.append(option_string)
871
872
if option_string.startswith('--'):
873
option_string = '--no-' + option_string[2:]
874
_option_strings.append(option_string)
875
876
if help is not None and default is not None:
877
help += f" (default: {default})"
878
879
super().__init__(
880
option_strings=_option_strings,
881
dest=dest,
882
nargs=0,
883
default=default,
884
type=type,
885
choices=choices,
886
required=required,
887
help=help,
888
metavar=metavar)
889
890
def __call__(self, parser, namespace, values, option_string=None):
891
if option_string in self.option_strings:
892
setattr(namespace, self.dest, not option_string.startswith('--no-'))
893
894
def format_usage(self):
895
return ' | '.join(self.option_strings)
896
897
898
class _StoreAction(Action):
899
900
def __init__(self,
901
option_strings,
902
dest,
903
nargs=None,
904
const=None,
905
default=None,
906
type=None,
907
choices=None,
908
required=False,
909
help=None,
910
metavar=None):
911
if nargs == 0:
912
raise ValueError('nargs for store actions must be != 0; if you '
913
'have nothing to store, actions such as store '
914
'true or store const may be more appropriate')
915
if const is not None and nargs != OPTIONAL:
916
raise ValueError('nargs must be %r to supply const' % OPTIONAL)
917
super(_StoreAction, self).__init__(
918
option_strings=option_strings,
919
dest=dest,
920
nargs=nargs,
921
const=const,
922
default=default,
923
type=type,
924
choices=choices,
925
required=required,
926
help=help,
927
metavar=metavar)
928
929
def __call__(self, parser, namespace, values, option_string=None):
930
setattr(namespace, self.dest, values)
931
932
933
class _StoreConstAction(Action):
934
935
def __init__(self,
936
option_strings,
937
dest,
938
const,
939
default=None,
940
required=False,
941
help=None,
942
metavar=None):
943
super(_StoreConstAction, self).__init__(
944
option_strings=option_strings,
945
dest=dest,
946
nargs=0,
947
const=const,
948
default=default,
949
required=required,
950
help=help)
951
952
def __call__(self, parser, namespace, values, option_string=None):
953
setattr(namespace, self.dest, self.const)
954
955
956
class _StoreTrueAction(_StoreConstAction):
957
958
def __init__(self,
959
option_strings,
960
dest,
961
default=False,
962
required=False,
963
help=None):
964
super(_StoreTrueAction, self).__init__(
965
option_strings=option_strings,
966
dest=dest,
967
const=True,
968
default=default,
969
required=required,
970
help=help)
971
972
973
class _StoreFalseAction(_StoreConstAction):
974
975
def __init__(self,
976
option_strings,
977
dest,
978
default=True,
979
required=False,
980
help=None):
981
super(_StoreFalseAction, self).__init__(
982
option_strings=option_strings,
983
dest=dest,
984
const=False,
985
default=default,
986
required=required,
987
help=help)
988
989
990
class _AppendAction(Action):
991
992
def __init__(self,
993
option_strings,
994
dest,
995
nargs=None,
996
const=None,
997
default=None,
998
type=None,
999
choices=None,
1000
required=False,