Coverage for Lib/argparse.py: 97%
1302 statements
« prev ^ index » next coverage.py v7.2.1, created at 2023-04-15 13:10 +0300
« prev ^ index » next coverage.py v7.2.1, created at 2023-04-15 13:10 +0300
1# Author: Steven J. Bethard <steven.bethard@gmail.com>.
2# New maintainer as of 29 August 2019: Raymond Hettinger <raymond.hettinger@gmail.com>
4"""Command-line parsing library
6This module is an optparse-inspired command-line parsing library that:
8 - handles both optional and positional arguments
9 - produces highly informative usage messages
10 - supports parsers that dispatch to sub-parsers
12The following is a simple usage example that sums integers from the
13command-line and writes the result to a file::
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()
27The module contains the following public classes:
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.
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.
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.
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.
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.
59All other classes in this module are considered implementation details.
60(Also note that HelpFormatter and RawDescriptionHelpFormatter are only
61considered public as object names -- the API of the formatter objects is
62still considered an implementation detail.)
63"""
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]
88import os as _os
89import re as _re
90import sys as _sys
92import warnings
94from gettext import gettext as _, ngettext
96SUPPRESS = '==SUPPRESS=='
98OPTIONAL = '?'
99ZERO_OR_MORE = '*'
100ONE_OR_MORE = '+'
101PARSER = 'A...'
102REMAINDER = '...'
103_UNRECOGNIZED_ARGS_ATTR = '_unrecognized_args'
105# =============================
106# Utility functions and classes
107# =============================
109class _AttributeHolder(object):
110 """Abstract base class that provides __repr__.
112 The __repr__ method returns a string in the format::
113 ClassName(attr=name, attr=name, ...)
114 The attributes are determined either by a class-level attribute,
115 '_kwarg_names', or by inspecting the instance __dict__.
116 """
118 def __repr__(self):
119 type_name = type(self).__name__
120 arg_strings = []
121 star_args = {}
122 for arg in self._get_args(): 122 ↛ 123line 122 didn't jump to line 123, because the loop on line 122 never started
123 arg_strings.append(repr(arg))
124 for name, value in self._get_kwargs():
125 if name.isidentifier():
126 arg_strings.append('%s=%r' % (name, value))
127 else:
128 star_args[name] = value
129 if star_args:
130 arg_strings.append('**%s' % repr(star_args))
131 return '%s(%s)' % (type_name, ', '.join(arg_strings))
133 def _get_kwargs(self):
134 return list(self.__dict__.items())
136 def _get_args(self):
137 return []
140def _copy_items(items):
141 if items is None:
142 return []
143 # The copy module is used only in the 'append' and 'append_const'
144 # actions, and it is needed only when the default value isn't a list.
145 # Delay its import for speeding up the common case.
146 if type(items) is list: 146 ↛ 148line 146 didn't jump to line 148, because the condition on line 146 was never false
147 return items[:]
148 import copy
149 return copy.copy(items)
152# ===============
153# Formatting Help
154# ===============
157class HelpFormatter(object):
158 """Formatter for generating usage messages and argument help strings.
160 Only the name of this class is considered a public API. All the methods
161 provided by the class are considered an implementation detail.
162 """
164 def __init__(self,
165 prog,
166 indent_increment=2,
167 max_help_position=24,
168 width=None):
170 # default setting for width
171 if width is None: 171 ↛ 176line 171 didn't jump to line 176, because the condition on line 171 was never false
172 import shutil
173 width = shutil.get_terminal_size().columns
174 width -= 2
176 self._prog = prog
177 self._indent_increment = indent_increment
178 self._max_help_position = min(max_help_position,
179 max(width - 20, indent_increment * 2))
180 self._width = width
182 self._current_indent = 0
183 self._level = 0
184 self._action_max_length = 0
186 self._root_section = self._Section(self, None)
187 self._current_section = self._root_section
189 self._whitespace_matcher = _re.compile(r'\s+', _re.ASCII)
190 self._long_break_matcher = _re.compile(r'\n\n\n+')
192 # ===============================
193 # Section and indentation methods
194 # ===============================
195 def _indent(self):
196 self._current_indent += self._indent_increment
197 self._level += 1
199 def _dedent(self):
200 self._current_indent -= self._indent_increment
201 assert self._current_indent >= 0, 'Indent decreased below 0.'
202 self._level -= 1
204 class _Section(object):
206 def __init__(self, formatter, parent, heading=None):
207 self.formatter = formatter
208 self.parent = parent
209 self.heading = heading
210 self.items = []
212 def format_help(self):
213 # format the indented section
214 if self.parent is not None:
215 self.formatter._indent()
216 join = self.formatter._join_parts
217 item_help = join([func(*args) for func, args in self.items])
218 if self.parent is not None:
219 self.formatter._dedent()
221 # return nothing if the section was empty
222 if not item_help:
223 return ''
225 # add the heading if the section was non-empty
226 if self.heading is not SUPPRESS and self.heading is not None:
227 current_indent = self.formatter._current_indent
228 heading = '%*s%s:\n' % (current_indent, '', self.heading)
229 else:
230 heading = ''
232 # join the section-initial newline, the heading and the help
233 return join(['\n', heading, item_help, '\n'])
235 def _add_item(self, func, args):
236 self._current_section.items.append((func, args))
238 # ========================
239 # Message building methods
240 # ========================
241 def start_section(self, heading):
242 self._indent()
243 section = self._Section(self, self._current_section, heading)
244 self._add_item(section.format_help, [])
245 self._current_section = section
247 def end_section(self):
248 self._current_section = self._current_section.parent
249 self._dedent()
251 def add_text(self, text):
252 if text is not SUPPRESS and text is not None:
253 self._add_item(self._format_text, [text])
255 def add_usage(self, usage, actions, groups, prefix=None):
256 if usage is not SUPPRESS:
257 args = usage, actions, groups, prefix
258 self._add_item(self._format_usage, args)
260 def add_argument(self, action):
261 if action.help is not SUPPRESS:
263 # find all invocations
264 get_invocation = self._format_action_invocation
265 invocations = [get_invocation(action)]
266 for subaction in self._iter_indented_subactions(action):
267 invocations.append(get_invocation(subaction))
269 # update the maximum item length
270 invocation_length = max(map(len, invocations))
271 action_length = invocation_length + self._current_indent
272 self._action_max_length = max(self._action_max_length,
273 action_length)
275 # add the item to the list
276 self._add_item(self._format_action, [action])
278 def add_arguments(self, actions):
279 for action in actions:
280 self.add_argument(action)
282 # =======================
283 # Help-formatting methods
284 # =======================
285 def format_help(self):
286 help = self._root_section.format_help()
287 if help:
288 help = self._long_break_matcher.sub('\n\n', help)
289 help = help.strip('\n') + '\n'
290 return help
292 def _join_parts(self, part_strings):
293 return ''.join([part
294 for part in part_strings
295 if part and part is not SUPPRESS])
297 def _format_usage(self, usage, actions, groups, prefix):
298 if prefix is None:
299 prefix = _('usage: ')
301 # if usage is specified, use that
302 if usage is not None:
303 usage = usage % dict(prog=self._prog)
305 # if no optionals or positionals are available, usage is just prog
306 elif usage is None and not actions:
307 usage = '%(prog)s' % dict(prog=self._prog)
309 # if optionals and positionals are available, calculate usage
310 elif usage is None: 310 ↛ 391line 310 didn't jump to line 391, because the condition on line 310 was never false
311 prog = '%(prog)s' % dict(prog=self._prog)
313 # split optionals from positionals
314 optionals = []
315 positionals = []
316 for action in actions:
317 if action.option_strings:
318 optionals.append(action)
319 else:
320 positionals.append(action)
322 # build full usage string
323 format = self._format_actions_usage
324 action_usage = format(optionals + positionals, groups)
325 usage = ' '.join([s for s in [prog, action_usage] if s])
327 # wrap the usage parts if it's too long
328 text_width = self._width - self._current_indent
329 if len(prefix) + len(usage) > text_width:
331 # break usage into wrappable parts
332 part_regexp = (
333 r'\(.*?\)+(?=\s|$)|'
334 r'\[.*?\]+(?=\s|$)|'
335 r'\S+'
336 )
337 opt_usage = format(optionals, groups)
338 pos_usage = format(positionals, groups)
339 opt_parts = _re.findall(part_regexp, opt_usage)
340 pos_parts = _re.findall(part_regexp, pos_usage)
341 assert ' '.join(opt_parts) == opt_usage
342 assert ' '.join(pos_parts) == pos_usage
344 # helper for wrapping lines
345 def get_lines(parts, indent, prefix=None):
346 lines = []
347 line = []
348 if prefix is not None:
349 line_len = len(prefix) - 1
350 else:
351 line_len = len(indent) - 1
352 for part in parts:
353 if line_len + 1 + len(part) > text_width and line:
354 lines.append(indent + ' '.join(line))
355 line = []
356 line_len = len(indent) - 1
357 line.append(part)
358 line_len += len(part) + 1
359 if line:
360 lines.append(indent + ' '.join(line))
361 if prefix is not None:
362 lines[0] = lines[0][len(indent):]
363 return lines
365 # if prog is short, follow it with optionals or positionals
366 if len(prefix) + len(prog) <= 0.75 * text_width:
367 indent = ' ' * (len(prefix) + len(prog) + 1)
368 if opt_parts:
369 lines = get_lines([prog] + opt_parts, indent, prefix)
370 lines.extend(get_lines(pos_parts, indent))
371 elif pos_parts: 371 ↛ 374line 371 didn't jump to line 374, because the condition on line 371 was never false
372 lines = get_lines([prog] + pos_parts, indent, prefix)
373 else:
374 lines = [prog]
376 # if prog is long, put it on its own line
377 else:
378 indent = ' ' * len(prefix)
379 parts = opt_parts + pos_parts
380 lines = get_lines(parts, indent)
381 if len(lines) > 1:
382 lines = []
383 lines.extend(get_lines(opt_parts, indent))
384 lines.extend(get_lines(pos_parts, indent))
385 lines = [prog] + lines
387 # join lines into usage
388 usage = '\n'.join(lines)
390 # prefix with 'usage:'
391 return '%s%s\n\n' % (prefix, usage)
393 def _format_actions_usage(self, actions, groups):
394 # find group indices and identify actions in groups
395 group_actions = set()
396 inserts = {}
397 for group in groups:
398 if not group._group_actions:
399 raise ValueError(f'empty group {group}')
401 try:
402 start = actions.index(group._group_actions[0])
403 except ValueError:
404 continue
405 else:
406 group_action_count = len(group._group_actions)
407 end = start + group_action_count
408 if actions[start:end] == group._group_actions:
410 suppressed_actions_count = 0
411 for action in group._group_actions:
412 group_actions.add(action)
413 if action.help is SUPPRESS:
414 suppressed_actions_count += 1
416 exposed_actions_count = group_action_count - suppressed_actions_count
418 if not group.required:
419 if start in inserts:
420 inserts[start] += ' ['
421 else:
422 inserts[start] = '['
423 if end in inserts:
424 inserts[end] += ']'
425 else:
426 inserts[end] = ']'
427 elif exposed_actions_count > 1:
428 if start in inserts:
429 inserts[start] += ' ('
430 else:
431 inserts[start] = '('
432 if end in inserts:
433 inserts[end] += ')'
434 else:
435 inserts[end] = ')'
436 for i in range(start + 1, end):
437 inserts[i] = '|'
439 # collect all actions format strings
440 parts = []
441 for i, action in enumerate(actions):
443 # suppressed arguments are marked with None
444 # remove | separators for suppressed arguments
445 if action.help is SUPPRESS:
446 parts.append(None)
447 if inserts.get(i) == '|': 447 ↛ 448line 447 didn't jump to line 448, because the condition on line 447 was never true
448 inserts.pop(i)
449 elif inserts.get(i + 1) == '|':
450 inserts.pop(i + 1)
452 # produce all arg strings
453 elif not action.option_strings:
454 default = self._get_default_metavar_for_positional(action)
455 part = self._format_args(action, default)
457 # if it's in a group, strip the outer []
458 if action in group_actions:
459 if part[0] == '[' and part[-1] == ']': 459 ↛ 463line 459 didn't jump to line 463, because the condition on line 459 was never false
460 part = part[1:-1]
462 # add the action string to the list
463 parts.append(part)
465 # produce the first way to invoke the option in brackets
466 else:
467 option_string = action.option_strings[0]
469 # if the Optional doesn't take a value, format is:
470 # -s or --long
471 if action.nargs == 0:
472 part = action.format_usage()
474 # if the Optional takes a value, format is:
475 # -s ARGS or --long ARGS
476 else:
477 default = self._get_default_metavar_for_optional(action)
478 args_string = self._format_args(action, default)
479 part = '%s %s' % (option_string, args_string)
481 # make it look optional if it's not required or in a group
482 if not action.required and action not in group_actions:
483 part = '[%s]' % part
485 # add the action string to the list
486 parts.append(part)
488 # insert things at the necessary indices
489 for i in sorted(inserts, reverse=True):
490 parts[i:i] = [inserts[i]]
492 # join all the action items with spaces
493 text = ' '.join([item for item in parts if item is not None])
495 # clean up separators for mutually exclusive groups
496 open = r'[\[(]'
497 close = r'[\])]'
498 text = _re.sub(r'(%s) ' % open, r'\1', text)
499 text = _re.sub(r' (%s)' % close, r'\1', text)
500 text = _re.sub(r'%s *%s' % (open, close), r'', text)
501 text = text.strip()
503 # return the text
504 return text
506 def _format_text(self, text):
507 if '%(prog)' in text:
508 text = text % dict(prog=self._prog)
509 text_width = max(self._width - self._current_indent, 11)
510 indent = ' ' * self._current_indent
511 return self._fill_text(text, text_width, indent) + '\n\n'
513 def _format_action(self, action):
514 # determine the required width and the entry label
515 help_position = min(self._action_max_length + 2,
516 self._max_help_position)
517 help_width = max(self._width - help_position, 11)
518 action_width = help_position - self._current_indent - 2
519 action_header = self._format_action_invocation(action)
521 # no help; start on same line and add a final newline
522 if not action.help:
523 tup = self._current_indent, '', action_header
524 action_header = '%*s%s\n' % tup
526 # short action name; start on the same line and pad two spaces
527 elif len(action_header) <= action_width:
528 tup = self._current_indent, '', action_width, action_header
529 action_header = '%*s%-*s ' % tup
530 indent_first = 0
532 # long action name; start on the next line
533 else:
534 tup = self._current_indent, '', action_header
535 action_header = '%*s%s\n' % tup
536 indent_first = help_position
538 # collect the pieces of the action help
539 parts = [action_header]
541 # if there was help for the action, add lines of help text
542 if action.help and action.help.strip():
543 help_text = self._expand_help(action)
544 if help_text:
545 help_lines = self._split_lines(help_text, help_width)
546 parts.append('%*s%s\n' % (indent_first, '', help_lines[0]))
547 for line in help_lines[1:]:
548 parts.append('%*s%s\n' % (help_position, '', line))
550 # or add a newline if the description doesn't end with one
551 elif not action_header.endswith('\n'):
552 parts.append('\n')
554 # if there are any sub-actions, add their help as well
555 for subaction in self._iter_indented_subactions(action):
556 parts.append(self._format_action(subaction))
558 # return a single string
559 return self._join_parts(parts)
561 def _format_action_invocation(self, action):
562 if not action.option_strings:
563 default = self._get_default_metavar_for_positional(action)
564 metavar, = self._metavar_formatter(action, default)(1)
565 return metavar
567 else:
568 parts = []
570 # if the Optional doesn't take a value, format is:
571 # -s, --long
572 if action.nargs == 0:
573 parts.extend(action.option_strings)
575 # if the Optional takes a value, format is:
576 # -s ARGS, --long ARGS
577 else:
578 default = self._get_default_metavar_for_optional(action)
579 args_string = self._format_args(action, default)
580 for option_string in action.option_strings:
581 parts.append('%s %s' % (option_string, args_string))
583 return ', '.join(parts)
585 def _metavar_formatter(self, action, default_metavar):
586 if action.metavar is not None:
587 result = action.metavar
588 elif action.choices is not None:
589 choice_strs = [str(choice) for choice in action.choices]
590 result = '{%s}' % ','.join(choice_strs)
591 else:
592 result = default_metavar
594 def format(tuple_size):
595 if isinstance(result, tuple):
596 return result
597 else:
598 return (result, ) * tuple_size
599 return format
601 def _format_args(self, action, default_metavar):
602 get_metavar = self._metavar_formatter(action, default_metavar)
603 if action.nargs is None:
604 result = '%s' % get_metavar(1)
605 elif action.nargs == OPTIONAL:
606 result = '[%s]' % get_metavar(1)
607 elif action.nargs == ZERO_OR_MORE:
608 metavar = get_metavar(1)
609 if len(metavar) == 2:
610 result = '[%s [%s ...]]' % metavar
611 else:
612 result = '[%s ...]' % metavar
613 elif action.nargs == ONE_OR_MORE:
614 result = '%s [%s ...]' % get_metavar(2)
615 elif action.nargs == REMAINDER:
616 result = '...'
617 elif action.nargs == PARSER:
618 result = '%s ...' % get_metavar(1)
619 elif action.nargs == SUPPRESS: 619 ↛ 620line 619 didn't jump to line 620, because the condition on line 619 was never true
620 result = ''
621 else:
622 try:
623 formats = ['%s' for _ in range(action.nargs)]
624 except TypeError:
625 raise ValueError("invalid nargs value") from None
626 result = ' '.join(formats) % get_metavar(action.nargs)
627 return result
629 def _expand_help(self, action):
630 params = dict(vars(action), prog=self._prog)
631 for name in list(params):
632 if params[name] is SUPPRESS:
633 del params[name]
634 for name in list(params):
635 if hasattr(params[name], '__name__'):
636 params[name] = params[name].__name__
637 if params.get('choices') is not None:
638 choices_str = ', '.join([str(c) for c in params['choices']])
639 params['choices'] = choices_str
640 return self._get_help_string(action) % params
642 def _iter_indented_subactions(self, action):
643 try:
644 get_subactions = action._get_subactions
645 except AttributeError:
646 pass
647 else:
648 self._indent()
649 yield from get_subactions()
650 self._dedent()
652 def _split_lines(self, text, width):
653 text = self._whitespace_matcher.sub(' ', text).strip()
654 # The textwrap module is used only for formatting help.
655 # Delay its import for speeding up the common usage of argparse.
656 import textwrap
657 return textwrap.wrap(text, width)
659 def _fill_text(self, text, width, indent):
660 text = self._whitespace_matcher.sub(' ', text).strip()
661 import textwrap
662 return textwrap.fill(text, width,
663 initial_indent=indent,
664 subsequent_indent=indent)
666 def _get_help_string(self, action):
667 return action.help
669 def _get_default_metavar_for_optional(self, action):
670 return action.dest.upper()
672 def _get_default_metavar_for_positional(self, action):
673 return action.dest
676class RawDescriptionHelpFormatter(HelpFormatter):
677 """Help message formatter which retains any formatting in descriptions.
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 """
683 def _fill_text(self, text, width, indent):
684 return ''.join(indent + line for line in text.splitlines(keepends=True))
687class RawTextHelpFormatter(RawDescriptionHelpFormatter):
688 """Help message formatter which retains formatting of all help text.
690 Only the name of this class is considered a public API. All the methods
691 provided by the class are considered an implementation detail.
692 """
694 def _split_lines(self, text, width):
695 return text.splitlines()
698class ArgumentDefaultsHelpFormatter(HelpFormatter):
699 """Help message formatter which adds default values to argument help.
701 Only the name of this class is considered a public API. All the methods
702 provided by the class are considered an implementation detail.
703 """
705 def _get_help_string(self, action):
706 """
707 Add the default value to the option help message.
709 ArgumentDefaultsHelpFormatter and BooleanOptionalAction when it isn't
710 already present. This code will do that, detecting cornercases to
711 prevent duplicates or cases where it wouldn't make sense to the end
712 user.
713 """
714 help = action.help
715 if help is None: 715 ↛ 716line 715 didn't jump to line 716, because the condition on line 715 was never true
716 help = ''
718 if '%(default)' not in help:
719 if action.default is not SUPPRESS:
720 defaulting_nargs = [OPTIONAL, ZERO_OR_MORE]
721 if action.option_strings or action.nargs in defaulting_nargs:
722 help += ' (default: %(default)s)'
723 return help
727class MetavarTypeHelpFormatter(HelpFormatter):
728 """Help message formatter which uses the argument 'type' as the default
729 metavar value (instead of the argument 'dest')
731 Only the name of this class is considered a public API. All the methods
732 provided by the class are considered an implementation detail.
733 """
735 def _get_default_metavar_for_optional(self, action):
736 return action.type.__name__
738 def _get_default_metavar_for_positional(self, action):
739 return action.type.__name__
742# =====================
743# Options and Arguments
744# =====================
746def _get_action_name(argument):
747 if argument is None:
748 return None
749 elif argument.option_strings:
750 return '/'.join(argument.option_strings)
751 elif argument.metavar not in (None, SUPPRESS):
752 return argument.metavar
753 elif argument.dest not in (None, SUPPRESS):
754 return argument.dest
755 elif argument.choices: 755 ↛ 758line 755 didn't jump to line 758, because the condition on line 755 was never false
756 return '{' + ','.join(argument.choices) + '}'
757 else:
758 return None
761class ArgumentError(Exception):
762 """An error from creating or using an argument (optional or positional).
764 The string value of this exception is the message, augmented with
765 information about the argument that caused it.
766 """
768 def __init__(self, argument, message):
769 self.argument_name = _get_action_name(argument)
770 self.message = message
772 def __str__(self):
773 if self.argument_name is None:
774 format = '%(message)s'
775 else:
776 format = _('argument %(argument_name)s: %(message)s')
777 return format % dict(message=self.message,
778 argument_name=self.argument_name)
781class ArgumentTypeError(Exception):
782 """An error from trying to convert a command line string to a type."""
783 pass
786# ==============
787# Action classes
788# ==============
790class Action(_AttributeHolder):
791 """Information about how to convert command line strings to Python objects.
793 Action objects are used by an ArgumentParser to represent the information
794 needed to parse a single argument from one or more strings from the
795 command line. The keyword arguments to the Action constructor are also
796 all attributes of Action instances.
798 Keyword Arguments:
800 - option_strings -- A list of command-line option strings which
801 should be associated with this action.
803 - dest -- The name of the attribute to hold the created object(s)
805 - nargs -- The number of command-line arguments that should be
806 consumed. By default, one argument will be consumed and a single
807 value will be produced. Other values include:
808 - N (an integer) consumes N arguments (and produces a list)
809 - '?' consumes zero or one arguments
810 - '*' consumes zero or more arguments (and produces a list)
811 - '+' consumes one or more arguments (and produces a list)
812 Note that the difference between the default and nargs=1 is that
813 with the default, a single value will be produced, while with
814 nargs=1, a list containing a single value will be produced.
816 - const -- The value to be produced if the option is specified and the
817 option uses an action that takes no values.
819 - default -- The value to be produced if the option is not specified.
821 - type -- A callable that accepts a single string argument, and
822 returns the converted value. The standard Python types str, int,
823 float, and complex are useful examples of such callables. If None,
824 str is used.
826 - choices -- A container of values that should be allowed. If not None,
827 after a command-line argument has been converted to the appropriate
828 type, an exception will be raised if it is not a member of this
829 collection.
831 - required -- True if the action must always be specified at the
832 command line. This is only meaningful for optional command-line
833 arguments.
835 - help -- The help string describing the argument.
837 - metavar -- The name to be used for the option's argument with the
838 help string. If None, the 'dest' value will be used as the name.
839 """
841 def __init__(self,
842 option_strings,
843 dest,
844 nargs=None,
845 const=None,
846 default=None,
847 type=None,
848 choices=None,
849 required=False,
850 help=None,
851 metavar=None):
852 self.option_strings = option_strings
853 self.dest = dest
854 self.nargs = nargs
855 self.const = const
856 self.default = default
857 self.type = type
858 self.choices = choices
859 self.required = required
860 self.help = help
861 self.metavar = metavar
863 def _get_kwargs(self):
864 names = [
865 'option_strings',
866 'dest',
867 'nargs',
868 'const',
869 'default',
870 'type',
871 'choices',
872 'required',
873 'help',
874 'metavar',
875 ]
876 return [(name, getattr(self, name)) for name in names]
878 def format_usage(self):
879 return self.option_strings[0]
881 def __call__(self, parser, namespace, values, option_string=None):
882 raise NotImplementedError(_('.__call__() not defined'))
885class BooleanOptionalAction(Action):
886 def __init__(self,
887 option_strings,
888 dest,
889 default=None,
890 type=None,
891 choices=None,
892 required=False,
893 help=None,
894 metavar=None):
896 _option_strings = []
897 for option_string in option_strings:
898 _option_strings.append(option_string)
900 if option_string.startswith('--'):
901 option_string = '--no-' + option_string[2:]
902 _option_strings.append(option_string)
904 super().__init__(
905 option_strings=_option_strings,
906 dest=dest,
907 nargs=0,
908 default=default,
909 type=type,
910 choices=choices,
911 required=required,
912 help=help,
913 metavar=metavar)
916 def __call__(self, parser, namespace, values, option_string=None):
917 if option_string in self.option_strings: 917 ↛ exitline 917 didn't return from function '__call__', because the condition on line 917 was never false
918 setattr(namespace, self.dest, not option_string.startswith('--no-'))
920 def format_usage(self):
921 return ' | '.join(self.option_strings)
924class _StoreAction(Action):
926 def __init__(self,
927 option_strings,
928 dest,
929 nargs=None,
930 const=None,
931 default=None,
932 type=None,
933 choices=None,
934 required=False,
935 help=None,
936 metavar=None):
937 if nargs == 0:
938 raise ValueError('nargs for store actions must be != 0; if you '
939 'have nothing to store, actions such as store '
940 'true or store const may be more appropriate')
941 if const is not None and nargs != OPTIONAL:
942 raise ValueError('nargs must be %r to supply const' % OPTIONAL)
943 super(_StoreAction, self).__init__(
944 option_strings=option_strings,
945 dest=dest,
946 nargs=nargs,
947 const=const,
948 default=default,
949 type=type,
950 choices=choices,
951 required=required,
952 help=help,
953 metavar=metavar)
955 def __call__(self, parser, namespace, values, option_string=None):
956 setattr(namespace, self.dest, values)
959class _StoreConstAction(Action):
961 def __init__(self,
962 option_strings,
963 dest,
964 const=None,
965 default=None,
966 required=False,
967 help=None,
968 metavar=None):
969 super(_StoreConstAction, self).__init__(
970 option_strings=option_strings,
971 dest=dest,
972 nargs=0,
973 const=const,
974 default=default,
975 required=required,
976 help=help)
978 def __call__(self, parser, namespace, values, option_string=None):
979 setattr(namespace, self.dest, self.const)
982class _StoreTrueAction(_StoreConstAction):
984 def __init__(self,
985 option_strings,
986 dest,
987 default=False,
988 required=False,
989 help=None):
990 super(_StoreTrueAction, self).__init__(
991 option_strings=option_strings,
992 dest=dest,
993 const=True,
994 default=default,
995 required=required,
996 help=help)
999class _StoreFalseAction(_StoreConstAction):
1001 def __init__(self,
1002 option_strings,
1003 dest,
1004 default=True,
1005 required=False,
1006 help=None):
1007 super(_StoreFalseAction, self).__init__(
1008 option_strings=option_strings,
1009 dest=dest,
1010 const=False,
1011 default=default,
1012 required=required,
1013 help=help)
1016class _AppendAction(Action):
1018 def __init__(self,
1019 option_strings,
1020 dest,
1021 nargs=None,
1022 const=None,
1023 default=None,
1024 type=None,
1025 choices=None,
1026 required=False,
1027 help=None,
1028 metavar=None):
1029 if nargs == 0:
1030 raise ValueError('nargs for append actions must be != 0; if arg '
1031 'strings are not supplying the value to append, '
1032 'the append const action may be more appropriate')
1033 if const is not None and nargs != OPTIONAL:
1034 raise ValueError('nargs must be %r to supply const' % OPTIONAL)
1035 super(_AppendAction, self).__init__(
1036 option_strings=option_strings,
1037 dest=dest,
1038 nargs=nargs,
1039 const=const,
1040 default=default,
1041 type=type,
1042 choices=choices,
1043 required=required,
1044 help=help,
1045 metavar=metavar)
1047 def __call__(self, parser, namespace, values, option_string=None):
1048 items = getattr(namespace, self.dest, None)
1049 items = _copy_items(items)
1050 items.append(values)
1051 setattr(namespace, self.dest, items)
1054class _AppendConstAction(Action):
1056 def __init__(self,
1057 option_strings,
1058 dest,
1059 const=None,
1060 default=None,
1061 required=False,
1062 help=None,
1063 metavar=None):
1064 super(_AppendConstAction, self).__init__(
1065 option_strings=option_strings,
1066 dest=dest,
1067 nargs=0,
1068 const=const,
1069 default=default,
1070 required=required,
1071 help=help,
1072 metavar=metavar)
1074 def __call__(self, parser, namespace, values, option_string=None):
1075 items = getattr(namespace, self.dest, None)
1076 items = _copy_items(items)
1077 items.append(self.const)
1078 setattr(namespace, self.dest, items)
1081class _CountAction(Action):
1083 def __init__(self,
1084 option_strings,
1085 dest,
1086 default=None,
1087 required=False,
1088 help=None):
1089 super(_CountAction, self).__init__(
1090 option_strings=option_strings,
1091 dest=dest,
1092 nargs=0,
1093 default=default,
1094 required=required,
1095 help=help)
1097 def __call__(self, parser, namespace, values, option_string=None):
1098 count = getattr(namespace, self.dest, None)
1099 if count is None:
1100 count = 0
1101 setattr(namespace, self.dest, count + 1)
1104class _HelpAction(Action):
1106 def __init__(self,
1107 option_strings,
1108 dest=SUPPRESS,
1109 default=SUPPRESS,
1110 help=None):
1111 super(_HelpAction, self).__init__(
1112 option_strings=option_strings,
1113 dest=dest,
1114 default=default,
1115 nargs=0,
1116 help=help)
1118 def __call__(self, parser, namespace, values, option_string=None):
1119 parser.print_help()
1120 parser.exit()
1123class _VersionAction(Action):
1125 def __init__(self,
1126 option_strings,
1127 version=None,
1128 dest=SUPPRESS,
1129 default=SUPPRESS,
1130 help="show program's version number and exit"):
1131 super(_VersionAction, self).__init__(
1132 option_strings=option_strings,
1133 dest=dest,
1134 default=default,
1135 nargs=0,
1136 help=help)
1137 self.version = version
1139 def __call__(self, parser, namespace, values, option_string=None):
1140 version = self.version
1141 if version is None: 1141 ↛ 1142line 1141 didn't jump to line 1142, because the condition on line 1141 was never true
1142 version = parser.version
1143 formatter = parser._get_formatter()
1144 formatter.add_text(version)
1145 parser._print_message(formatter.format_help(), _sys.stdout)
1146 parser.exit()
1149class _SubParsersAction(Action):
1151 class _ChoicesPseudoAction(Action):
1153 def __init__(self, name, aliases, help):
1154 metavar = dest = name
1155 if aliases:
1156 metavar += ' (%s)' % ', '.join(aliases)
1157 sup = super(_SubParsersAction._ChoicesPseudoAction, self)
1158 sup.__init__(option_strings=[], dest=dest, help=help,
1159 metavar=metavar)
1161 def __init__(self,
1162 option_strings,
1163 prog,
1164 parser_class,
1165 dest=SUPPRESS,
1166 required=False,
1167 help=None,
1168 metavar=None):
1170 self._prog_prefix = prog
1171 self._parser_class = parser_class
1172 self._name_parser_map = {}
1173 self._choices_actions = []
1175 super(_SubParsersAction, self).__init__(
1176 option_strings=option_strings,
1177 dest=dest,
1178 nargs=PARSER,
1179 choices=self._name_parser_map,
1180 required=required,
1181 help=help,
1182 metavar=metavar)
1184 def add_parser(self, name, **kwargs):
1185 # set prog from the existing prefix
1186 if kwargs.get('prog') is None: 1186 ↛ 1189line 1186 didn't jump to line 1189, because the condition on line 1186 was never false
1187 kwargs['prog'] = '%s %s' % (self._prog_prefix, name)
1189 aliases = kwargs.pop('aliases', ())
1191 if name in self._name_parser_map:
1192 raise ArgumentError(self, _('conflicting subparser: %s') % name)
1193 for alias in aliases:
1194 if alias in self._name_parser_map:
1195 raise ArgumentError(
1196 self, _('conflicting subparser alias: %s') % alias)
1198 # create a pseudo-action to hold the choice help
1199 if 'help' in kwargs:
1200 help = kwargs.pop('help')
1201 choice_action = self._ChoicesPseudoAction(name, aliases, help)
1202 self._choices_actions.append(choice_action)
1204 # create the parser and add it to the map
1205 parser = self._parser_class(**kwargs)
1206 self._name_parser_map[name] = parser
1208 # make parser available under aliases also
1209 for alias in aliases:
1210 self._name_parser_map[alias] = parser
1212 return parser
1214 def _get_subactions(self):
1215 return self._choices_actions
1217 def __call__(self, parser, namespace, values, option_string=None):
1218 parser_name = values[0]
1219 arg_strings = values[1:]
1221 # set the parser name if requested
1222 if self.dest is not SUPPRESS:
1223 setattr(namespace, self.dest, parser_name)
1225 # select the parser
1226 try:
1227 parser = self._name_parser_map[parser_name]
1228 except KeyError:
1229 args = {'parser_name': parser_name,
1230 'choices': ', '.join(self._name_parser_map)}
1231 msg = _('unknown parser %(parser_name)r (choices: %(choices)s)') % args
1232 raise ArgumentError(self, msg)
1234 # parse all the remaining options into the namespace
1235 # store any unrecognized options on the object, so that the top
1236 # level parser can decide what to do with them
1238 # In case this subparser defines new defaults, we parse them
1239 # in a new namespace object and then update the original
1240 # namespace for the relevant parts.
1241 subnamespace, arg_strings = parser.parse_known_args(arg_strings, None)
1242 for key, value in vars(subnamespace).items():
1243 setattr(namespace, key, value)
1245 if arg_strings:
1246 vars(namespace).setdefault(_UNRECOGNIZED_ARGS_ATTR, [])
1247 getattr(namespace, _UNRECOGNIZED_ARGS_ATTR).extend(arg_strings)
1249class _ExtendAction(_AppendAction):
1250 def __call__(self, parser, namespace, values, option_string=None):
1251 items = getattr(namespace, self.dest, None)
1252 items = _copy_items(items)
1253 items.extend(values)
1254 setattr(namespace, self.dest, items)
1256# ==============
1257# Type classes
1258# ==============
1260class FileType(object):
1261 """Factory for creating file object types
1263 Instances of FileType are typically passed as type= arguments to the
1264 ArgumentParser add_argument() method.
1266 Keyword Arguments:
1267 - mode -- A string indicating how the file is to be opened. Accepts the
1268 same values as the builtin open() function.
1269 - bufsize -- The file's desired buffer size. Accepts the same values as
1270 the builtin open() function.
1271 - encoding -- The file's encoding. Accepts the same values as the
1272 builtin open() function.
1273 - errors -- A string indicating how encoding and decoding errors are to
1274 be handled. Accepts the same value as the builtin open() function.
1275 """
1277 def __init__(self, mode='r', bufsize=-1, encoding=None, errors=None):
1278 self._mode = mode
1279 self._bufsize = bufsize
1280 self._encoding = encoding
1281 self._errors = errors
1283 def __call__(self, string):
1284 # the special argument "-" means sys.std{in,out}
1285 if string == '-':
1286 if 'r' in self._mode:
1287 return _sys.stdin.buffer if 'b' in self._mode else _sys.stdin
1288 elif any(c in self._mode for c in 'wax'): 1288 ↛ exit, 1288 ↛ 12912 missed branches: 1) line 1288 didn't finish the generator expression on line 1288, 2) line 1288 didn't jump to line 1291, because the condition on line 1288 was never false
1289 return _sys.stdout.buffer if 'b' in self._mode else _sys.stdout
1290 else:
1291 msg = _('argument "-" with mode %r') % self._mode
1292 raise ValueError(msg)
1294 # all other arguments are used as file names
1295 try:
1296 return open(string, self._mode, self._bufsize, self._encoding,
1297 self._errors)
1298 except OSError as e:
1299 args = {'filename': string, 'error': e}
1300 message = _("can't open '%(filename)s': %(error)s")
1301 raise ArgumentTypeError(message % args)
1303 def __repr__(self):
1304 args = self._mode, self._bufsize
1305 kwargs = [('encoding', self._encoding), ('errors', self._errors)]
1306 args_str = ', '.join([repr(arg) for arg in args if arg != -1] +
1307 ['%s=%r' % (kw, arg) for kw, arg in kwargs
1308 if arg is not None])
1309 return '%s(%s)' % (type(self).__name__, args_str)
1311# ===========================
1312# Optional and Positional Parsing
1313# ===========================
1315class Namespace(_AttributeHolder):
1316 """Simple object for storing attributes.
1318 Implements equality by attribute names and values, and provides a simple
1319 string representation.
1320 """
1322 def __init__(self, **kwargs):
1323 for name in kwargs:
1324 setattr(self, name, kwargs[name])
1326 def __eq__(self, other):
1327 if not isinstance(other, Namespace):
1328 return NotImplemented
1329 return vars(self) == vars(other)
1331 def __contains__(self, key):
1332 return key in self.__dict__
1335class _ActionsContainer(object):
1337 def __init__(self,
1338 description,
1339 prefix_chars,
1340 argument_default,
1341 conflict_handler):
1342 super(_ActionsContainer, self).__init__()
1344 self.description = description
1345 self.argument_default = argument_default
1346 self.prefix_chars = prefix_chars
1347 self.conflict_handler = conflict_handler
1349 # set up registries
1350 self._registries = {}
1352 # register actions
1353 self.register('action', None, _StoreAction)
1354 self.register('action', 'store', _StoreAction)
1355 self.register('action', 'store_const', _StoreConstAction)
1356 self.register('action', 'store_true', _StoreTrueAction)
1357 self.register('action', 'store_false', _StoreFalseAction)
1358 self.register('action', 'append', _AppendAction)
1359 self.register('action', 'append_const', _AppendConstAction)
1360 self.register('action', 'count', _CountAction)
1361 self.register('action', 'help', _HelpAction)
1362 self.register('action', 'version', _VersionAction)
1363 self.register('action', 'parsers', _SubParsersAction)
1364 self.register('action', 'extend', _ExtendAction)
1366 # raise an exception if the conflict handler is invalid
1367 self._get_handler()
1369 # action storage
1370 self._actions = []
1371 self._option_string_actions = {}
1373 # groups
1374 self._action_groups = []
1375 self._mutually_exclusive_groups = []
1377 # defaults storage
1378 self._defaults = {}
1380 # determines whether an "option" looks like a negative number
1381 self._negative_number_matcher = _re.compile(r'^-\d+$|^-\d*\.\d+$')
1383 # whether or not there are any optionals that look like negative
1384 # numbers -- uses a list so it can be shared and edited
1385 self._has_negative_number_optionals = []
1387 # ====================
1388 # Registration methods
1389 # ====================
1390 def register(self, registry_name, value, object):
1391 registry = self._registries.setdefault(registry_name, {})
1392 registry[value] = object
1394 def _registry_get(self, registry_name, value, default=None):
1395 return self._registries[registry_name].get(value, default)
1397 # ==================================
1398 # Namespace default accessor methods
1399 # ==================================
1400 def set_defaults(self, **kwargs):
1401 self._defaults.update(kwargs)
1403 # if these defaults match any existing arguments, replace
1404 # the previous default on the object with the new one
1405 for action in self._actions:
1406 if action.dest in kwargs:
1407 action.default = kwargs[action.dest]
1409 def get_default(self, dest):
1410 for action in self._actions:
1411 if action.dest == dest and action.default is not None:
1412 return action.default
1413 return self._defaults.get(dest, None)
1416 # =======================
1417 # Adding argument actions
1418 # =======================
1419 def add_argument(self, *args, **kwargs):
1420 """
1421 add_argument(dest, ..., name=value, ...)
1422 add_argument(option_string, option_string, ..., name=value, ...)
1423 """
1425 # if no positional args are supplied or only one is supplied and
1426 # it doesn't look like an option string, parse a positional
1427 # argument
1428 chars = self.prefix_chars
1429 if not args or len(args) == 1 and args[0][0] not in chars:
1430 if args and 'dest' in kwargs:
1431 raise ValueError('dest supplied twice for positional argument')
1432 kwargs = self._get_positional_kwargs(*args, **kwargs)
1434 # otherwise, we're adding an optional argument
1435 else:
1436 kwargs = self._get_optional_kwargs(*args, **kwargs)
1438 # if no default was supplied, use the parser-level default
1439 if 'default' not in kwargs:
1440 dest = kwargs['dest']
1441 if dest in self._defaults:
1442 kwargs['default'] = self._defaults[dest]
1443 elif self.argument_default is not None:
1444 kwargs['default'] = self.argument_default
1446 # create the action object, and add it to the parser
1447 action_class = self._pop_action_class(kwargs)
1448 if not callable(action_class):
1449 raise ValueError('unknown action "%s"' % (action_class,))
1450 action = action_class(**kwargs)
1452 # raise an error if the action type is not callable
1453 type_func = self._registry_get('type', action.type, action.type)
1454 if not callable(type_func):
1455 raise ValueError('%r is not callable' % (type_func,))
1457 if type_func is FileType:
1458 raise ValueError('%r is a FileType class object, instance of it'
1459 ' must be passed' % (type_func,))
1461 # raise an error if the metavar does not match the type
1462 if hasattr(self, "_get_formatter"):
1463 try:
1464 self._get_formatter()._format_args(action, None)
1465 except TypeError:
1466 raise ValueError("length of metavar tuple does not match nargs")
1468 return self._add_action(action)
1470 def add_argument_group(self, *args, **kwargs):
1471 group = _ArgumentGroup(self, *args, **kwargs)
1472 self._action_groups.append(group)
1473 return group
1475 def add_mutually_exclusive_group(self, **kwargs):
1476 group = _MutuallyExclusiveGroup(self, **kwargs)
1477 self._mutually_exclusive_groups.append(group)
1478 return group
1480 def _add_action(self, action):
1481 # resolve any conflicts
1482 self._check_conflict(action)
1484 # add to actions list
1485 self._actions.append(action)
1486 action.container = self
1488 # index the action by any option strings it has
1489 for option_string in action.option_strings:
1490 self._option_string_actions[option_string] = action
1492 # set the flag if any option strings look like negative numbers
1493 for option_string in action.option_strings:
1494 if self._negative_number_matcher.match(option_string):
1495 if not self._has_negative_number_optionals: 1495 ↛ 1493line 1495 didn't jump to line 1493, because the condition on line 1495 was never false
1496 self._has_negative_number_optionals.append(True)
1498 # return the created action
1499 return action
1501 def _remove_action(self, action):
1502 self._actions.remove(action)
1504 def _add_container_actions(self, container):
1505 # collect groups by titles
1506 title_group_map = {}
1507 for group in self._action_groups:
1508 if group.title in title_group_map: 1508 ↛ 1509line 1508 didn't jump to line 1509, because the condition on line 1508 was never true
1509 msg = _('cannot merge actions - two groups are named %r')
1510 raise ValueError(msg % (group.title))
1511 title_group_map[group.title] = group
1513 # map each action to its group
1514 group_map = {}
1515 for group in container._action_groups:
1517 # if a group with the title exists, use that, otherwise
1518 # create a new group matching the container's group
1519 if group.title not in title_group_map:
1520 title_group_map[group.title] = self.add_argument_group(
1521 title=group.title,
1522 description=group.description,
1523 conflict_handler=group.conflict_handler)
1525 # map the actions to their new group
1526 for action in group._group_actions:
1527 group_map[action] = title_group_map[group.title]
1529 # add container's mutually exclusive groups
1530 # NOTE: if add_mutually_exclusive_group ever gains title= and
1531 # description= then this code will need to be expanded as above
1532 for group in container._mutually_exclusive_groups:
1533 mutex_group = self.add_mutually_exclusive_group(
1534 required=group.required)
1536 # map the actions to their new mutex group
1537 for action in group._group_actions:
1538 group_map[action] = mutex_group
1540 # add all actions to this container or their group
1541 for action in container._actions:
1542 group_map.get(action, self)._add_action(action)
1544 def _get_positional_kwargs(self, dest, **kwargs):
1545 # make sure required is not specified
1546 if 'required' in kwargs:
1547 msg = _("'required' is an invalid argument for positionals")
1548 raise TypeError(msg)
1550 # mark positional arguments as required if at least one is
1551 # always required
1552 if kwargs.get('nargs') not in [OPTIONAL, ZERO_OR_MORE]:
1553 kwargs['required'] = True
1554 if kwargs.get('nargs') == ZERO_OR_MORE and 'default' not in kwargs:
1555 kwargs['required'] = True
1557 # return the keyword arguments with no option strings
1558 return dict(kwargs, dest=dest, option_strings=[])
1560 def _get_optional_kwargs(self, *args, **kwargs):
1561 # determine short and long option strings
1562 option_strings = []
1563 long_option_strings = []
1564 for option_string in args:
1565 # error on strings that don't start with an appropriate prefix
1566 if not option_string[0] in self.prefix_chars: 1566 ↛ 1567line 1566 didn't jump to line 1567, because the condition on line 1566 was never true
1567 args = {'option': option_string,
1568 'prefix_chars': self.prefix_chars}
1569 msg = _('invalid option string %(option)r: '
1570 'must start with a character %(prefix_chars)r')
1571 raise ValueError(msg % args)
1573 # strings starting with two prefix characters are long options
1574 option_strings.append(option_string)
1575 if len(option_string) > 1 and option_string[1] in self.prefix_chars:
1576 long_option_strings.append(option_string)
1578 # infer destination, '--foo-bar' -> 'foo_bar' and '-x' -> 'x'
1579 dest = kwargs.pop('dest', None)
1580 if dest is None:
1581 if long_option_strings:
1582 dest_option_string = long_option_strings[0]
1583 else:
1584 dest_option_string = option_strings[0]
1585 dest = dest_option_string.lstrip(self.prefix_chars)
1586 if not dest:
1587 msg = _('dest= is required for options like %r')
1588 raise ValueError(msg % option_string)
1589 dest = dest.replace('-', '_')
1591 # return the updated keyword arguments
1592 return dict(kwargs, dest=dest, option_strings=option_strings)
1594 def _pop_action_class(self, kwargs, default=None):
1595 action = kwargs.pop('action', default)
1596 return self._registry_get('action', action, action)
1598 def _get_handler(self):
1599 # determine function from conflict handler string
1600 handler_func_name = '_handle_conflict_%s' % self.conflict_handler
1601 try:
1602 return getattr(self, handler_func_name)
1603 except AttributeError:
1604 msg = _('invalid conflict_resolution value: %r')
1605 raise ValueError(msg % self.conflict_handler)
1607 def _check_conflict(self, action):
1609 # find all options that conflict with this option
1610 confl_optionals = []
1611 for option_string in action.option_strings:
1612 if option_string in self._option_string_actions:
1613 confl_optional = self._option_string_actions[option_string]
1614 confl_optionals.append((option_string, confl_optional))
1616 # resolve any conflicts
1617 if confl_optionals:
1618 conflict_handler = self._get_handler()
1619 conflict_handler(action, confl_optionals)
1621 def _handle_conflict_error(self, action, conflicting_actions):
1622 message = ngettext('conflicting option string: %s',
1623 'conflicting option strings: %s',
1624 len(conflicting_actions))
1625 conflict_string = ', '.join([option_string
1626 for option_string, action
1627 in conflicting_actions])
1628 raise ArgumentError(action, message % conflict_string)
1630 def _handle_conflict_resolve(self, action, conflicting_actions):
1632 # remove all conflicting options
1633 for option_string, action in conflicting_actions:
1635 # remove the conflicting option
1636 action.option_strings.remove(option_string)
1637 self._option_string_actions.pop(option_string, None)
1639 # if the option now has no option string, remove it from the
1640 # container holding it
1641 if not action.option_strings: 1641 ↛ 1633line 1641 didn't jump to line 1633, because the condition on line 1641 was never false
1642 action.container._remove_action(action)
1645class _ArgumentGroup(_ActionsContainer):
1647 def __init__(self, container, title=None, description=None, **kwargs):
1648 # add any missing keyword arguments by checking the container
1649 update = kwargs.setdefault
1650 update('conflict_handler', container.conflict_handler)
1651 update('prefix_chars', container.prefix_chars)
1652 update('argument_default', container.argument_default)
1653 super_init = super(_ArgumentGroup, self).__init__
1654 super_init(description=description, **kwargs)
1656 # group attributes
1657 self.title = title
1658 self._group_actions = []
1660 # share most attributes with the container
1661 self._registries = container._registries
1662 self._actions = container._actions
1663 self._option_string_actions = container._option_string_actions
1664 self._defaults = container._defaults
1665 self._has_negative_number_optionals = \
1666 container._has_negative_number_optionals
1667 self._mutually_exclusive_groups = container._mutually_exclusive_groups
1669 def _add_action(self, action):
1670 action = super(_ArgumentGroup, self)._add_action(action)
1671 self._group_actions.append(action)
1672 return action
1674 def _remove_action(self, action):
1675 super(_ArgumentGroup, self)._remove_action(action)
1676 self._group_actions.remove(action)
1678 def add_argument_group(self, *args, **kwargs):
1679 warnings.warn(
1680 "Nesting argument groups is deprecated.",
1681 category=DeprecationWarning,
1682 stacklevel=2
1683 )
1684 return super().add_argument_group(*args, **kwargs)
1687class _MutuallyExclusiveGroup(_ArgumentGroup):
1689 def __init__(self, container, required=False):
1690 super(_MutuallyExclusiveGroup, self).__init__(container)
1691 self.required = required
1692 self._container = container
1694 def _add_action(self, action):
1695 if action.required:
1696 msg = _('mutually exclusive arguments must be optional')
1697 raise ValueError(msg)
1698 action = self._container._add_action(action)
1699 self._group_actions.append(action)
1700 return action
1702 def _remove_action(self, action):
1703 self._container._remove_action(action)
1704 self._group_actions.remove(action)
1706 def add_mutually_exclusive_group(self, *args, **kwargs):
1707 warnings.warn(
1708 "Nesting mutually exclusive groups is deprecated.",
1709 category=DeprecationWarning,
1710 stacklevel=2
1711 )
1712 return super().add_mutually_exclusive_group(*args, **kwargs)
1715class ArgumentParser(_AttributeHolder, _ActionsContainer):
1716 """Object for parsing command line strings into Python objects.
1718 Keyword Arguments:
1719 - prog -- The name of the program (default:
1720 ``os.path.basename(sys.argv[0])``)
1721 - usage -- A usage message (default: auto-generated from arguments)
1722 - description -- A description of what the program does
1723 - epilog -- Text following the argument descriptions
1724 - parents -- Parsers whose arguments should be copied into this one
1725 - formatter_class -- HelpFormatter class for printing help messages
1726 - prefix_chars -- Characters that prefix optional arguments
1727 - fromfile_prefix_chars -- Characters that prefix files containing
1728 additional arguments
1729 - argument_default -- The default value for all arguments
1730 - conflict_handler -- String indicating how to handle conflicts
1731 - add_help -- Add a -h/-help option
1732 - allow_abbrev -- Allow long options to be abbreviated unambiguously
1733 - exit_on_error -- Determines whether or not ArgumentParser exits with
1734 error info when an error occurs
1735 """
1737 def __init__(self,
1738 prog=None,
1739 usage=None,
1740 description=None,
1741 epilog=None,
1742 parents=[],
1743 formatter_class=HelpFormatter,
1744 prefix_chars='-',
1745 fromfile_prefix_chars=None,
1746 argument_default=None,
1747 conflict_handler='error',
1748 add_help=True,
1749 allow_abbrev=True,
1750 exit_on_error=True):
1752 superinit = super(ArgumentParser, self).__init__
1753 superinit(description=description,
1754 prefix_chars=prefix_chars,
1755 argument_default=argument_default,
1756 conflict_handler=conflict_handler)
1758 # default setting for prog
1759 if prog is None:
1760 prog = _os.path.basename(_sys.argv[0])
1762 self.prog = prog
1763 self.usage = usage
1764 self.epilog = epilog
1765 self.formatter_class = formatter_class
1766 self.fromfile_prefix_chars = fromfile_prefix_chars
1767 self.add_help = add_help
1768 self.allow_abbrev = allow_abbrev
1769 self.exit_on_error = exit_on_error
1771 add_group = self.add_argument_group
1772 self._positionals = add_group(_('positional arguments'))
1773 self._optionals = add_group(_('options'))
1774 self._subparsers = None
1776 # register types
1777 def identity(string):
1778 return string
1779 self.register('type', None, identity)
1781 # add help argument if necessary
1782 # (using explicit default to override global argument_default)
1783 default_prefix = '-' if '-' in prefix_chars else prefix_chars[0]
1784 if self.add_help:
1785 self.add_argument(
1786 default_prefix+'h', default_prefix*2+'help',
1787 action='help', default=SUPPRESS,
1788 help=_('show this help message and exit'))
1790 # add parent arguments and defaults
1791 for parent in parents:
1792 self._add_container_actions(parent)
1793 try:
1794 defaults = parent._defaults
1795 except AttributeError:
1796 pass
1797 else:
1798 self._defaults.update(defaults)
1800 # =======================
1801 # Pretty __repr__ methods
1802 # =======================
1803 def _get_kwargs(self):
1804 names = [
1805 'prog',
1806 'usage',
1807 'description',
1808 'formatter_class',
1809 'conflict_handler',
1810 'add_help',
1811 ]
1812 return [(name, getattr(self, name)) for name in names]
1814 # ==================================
1815 # Optional/Positional adding methods
1816 # ==================================
1817 def add_subparsers(self, **kwargs):
1818 if self._subparsers is not None:
1819 self.error(_('cannot have multiple subparser arguments'))
1821 # add the parser class to the arguments if it's not present
1822 kwargs.setdefault('parser_class', type(self))
1824 if 'title' in kwargs or 'description' in kwargs:
1825 title = _(kwargs.pop('title', 'subcommands'))
1826 description = _(kwargs.pop('description', None))
1827 self._subparsers = self.add_argument_group(title, description)
1828 else:
1829 self._subparsers = self._positionals
1831 # prog defaults to the usage message of this parser, skipping
1832 # optional arguments and with no "usage:" prefix
1833 if kwargs.get('prog') is None: 1833 ↛ 1841line 1833 didn't jump to line 1841, because the condition on line 1833 was never false
1834 formatter = self._get_formatter()
1835 positionals = self._get_positional_actions()
1836 groups = self._mutually_exclusive_groups
1837 formatter.add_usage(self.usage, positionals, groups, '')
1838 kwargs['prog'] = formatter.format_help().strip()
1840 # create the parsers action and add it to the positionals list
1841 parsers_class = self._pop_action_class(kwargs, 'parsers')
1842 action = parsers_class(option_strings=[], **kwargs)
1843 self._subparsers._add_action(action)
1845 # return the created parsers action
1846 return action
1848 def _add_action(self, action):
1849 if action.option_strings:
1850 self._optionals._add_action(action)
1851 else:
1852 self._positionals._add_action(action)
1853 return action
1855 def _get_optional_actions(self):
1856 return [action
1857 for action in self._actions
1858 if action.option_strings]
1860 def _get_positional_actions(self):
1861 return [action
1862 for action in self._actions
1863 if not action.option_strings]
1865 # =====================================
1866 # Command line argument parsing methods
1867 # =====================================
1868 def parse_args(self, args=None, namespace=None):
1869 args, argv = self.parse_known_args(args, namespace)
1870 if argv:
1871 msg = _('unrecognized arguments: %s')
1872 self.error(msg % ' '.join(argv))
1873 return args
1875 def parse_known_args(self, args=None, namespace=None):
1876 if args is None:
1877 # args default to the system args
1878 args = _sys.argv[1:]
1879 else:
1880 # make sure that args are mutable
1881 args = list(args)
1883 # default Namespace built from parser defaults
1884 if namespace is None:
1885 namespace = Namespace()
1887 # add any action defaults that aren't present
1888 for action in self._actions:
1889 if action.dest is not SUPPRESS:
1890 if not hasattr(namespace, action.dest):
1891 if action.default is not SUPPRESS:
1892 setattr(namespace, action.dest, action.default)
1894 # add any parser defaults that aren't present
1895 for dest in self._defaults:
1896 if not hasattr(namespace, dest):
1897 setattr(namespace, dest, self._defaults[dest])
1899 # parse the arguments and exit if there are any errors
1900 if self.exit_on_error:
1901 try:
1902 namespace, args = self._parse_known_args(args, namespace)
1903 except ArgumentError as err:
1904 self.error(str(err))
1905 else:
1906 namespace, args = self._parse_known_args(args, namespace)
1908 if hasattr(namespace, _UNRECOGNIZED_ARGS_ATTR):
1909 args.extend(getattr(namespace, _UNRECOGNIZED_ARGS_ATTR))
1910 delattr(namespace, _UNRECOGNIZED_ARGS_ATTR)
1911 return namespace, args
1913 def _parse_known_args(self, arg_strings, namespace):
1914 # replace arg strings that are file references
1915 if self.fromfile_prefix_chars is not None:
1916 arg_strings = self._read_args_from_files(arg_strings)
1918 # map all mutually exclusive arguments to the other arguments
1919 # they can't occur with
1920 action_conflicts = {}
1921 for mutex_group in self._mutually_exclusive_groups:
1922 group_actions = mutex_group._group_actions
1923 for i, mutex_action in enumerate(mutex_group._group_actions):
1924 conflicts = action_conflicts.setdefault(mutex_action, [])
1925 conflicts.extend(group_actions[:i])
1926 conflicts.extend(group_actions[i + 1:])
1928 # find all option indices, and determine the arg_string_pattern
1929 # which has an 'O' if there is an option at an index,
1930 # an 'A' if there is an argument, or a '-' if there is a '--'
1931 option_string_indices = {}
1932 arg_string_pattern_parts = []
1933 arg_strings_iter = iter(arg_strings)
1934 for i, arg_string in enumerate(arg_strings_iter):
1936 # all args after -- are non-options
1937 if arg_string == '--':
1938 arg_string_pattern_parts.append('-')
1939 for arg_string in arg_strings_iter:
1940 arg_string_pattern_parts.append('A')
1942 # otherwise, add the arg to the arg strings
1943 # and note the index if it was an option
1944 else:
1945 option_tuple = self._parse_optional(arg_string)
1946 if option_tuple is None:
1947 pattern = 'A'
1948 else:
1949 option_string_indices[i] = option_tuple
1950 pattern = 'O'
1951 arg_string_pattern_parts.append(pattern)
1953 # join the pieces together to form the pattern
1954 arg_strings_pattern = ''.join(arg_string_pattern_parts)
1956 # converts arg strings to the appropriate and then takes the action
1957 seen_actions = set()
1958 seen_non_default_actions = set()
1960 def take_action(action, argument_strings, option_string=None):
1961 seen_actions.add(action)
1962 argument_values = self._get_values(action, argument_strings)
1964 # error if this argument is not allowed with other previously
1965 # seen arguments, assuming that actions that use the default
1966 # value don't really count as "present"
1967 if argument_values is not action.default:
1968 seen_non_default_actions.add(action)
1969 for conflict_action in action_conflicts.get(action, []):
1970 if conflict_action in seen_non_default_actions:
1971 msg = _('not allowed with argument %s')
1972 action_name = _get_action_name(conflict_action)
1973 raise ArgumentError(action, msg % action_name)
1975 # take the action if we didn't receive a SUPPRESS value
1976 # (e.g. from a default)
1977 if argument_values is not SUPPRESS:
1978 action(self, namespace, argument_values, option_string)
1980 # function to convert arg_strings into an optional action
1981 def consume_optional(start_index):
1983 # get the optional identified at this index
1984 option_tuple = option_string_indices[start_index]
1985 action, option_string, explicit_arg = option_tuple
1987 # identify additional optionals in the same arg string
1988 # (e.g. -xyz is the same as -x -y -z if no args are required)
1989 match_argument = self._match_argument
1990 action_tuples = []
1991 while True:
1993 # if we found no optional action, skip it
1994 if action is None:
1995 extras.append(arg_strings[start_index])
1996 return start_index + 1
1998 # if there is an explicit argument, try to match the
1999 # optional's string arguments to only this
2000 if explicit_arg is not None:
2001 arg_count = match_argument(action, 'A')
2003 # if the action is a single-dash option and takes no
2004 # arguments, try to parse more single-dash options out
2005 # of the tail of the option string
2006 chars = self.prefix_chars
2007 if (
2008 arg_count == 0
2009 and option_string[1] not in chars
2010 and explicit_arg != ''
2011 ):
2012 action_tuples.append((action, [], option_string))
2013 char = option_string[0]
2014 option_string = char + explicit_arg[0]
2015 new_explicit_arg = explicit_arg[1:] or None
2016 optionals_map = self._option_string_actions
2017 if option_string in optionals_map:
2018 action = optionals_map[option_string]
2019 explicit_arg = new_explicit_arg
2020 else:
2021 msg = _('ignored explicit argument %r')
2022 raise ArgumentError(action, msg % explicit_arg)
2024 # if the action expect exactly one argument, we've
2025 # successfully matched the option; exit the loop
2026 elif arg_count == 1:
2027 stop = start_index + 1
2028 args = [explicit_arg]
2029 action_tuples.append((action, args, option_string))
2030 break
2032 # error if a double-dash option did not use the
2033 # explicit argument
2034 else:
2035 msg = _('ignored explicit argument %r')
2036 raise ArgumentError(action, msg % explicit_arg)
2038 # if there is no explicit argument, try to match the
2039 # optional's string arguments with the following strings
2040 # if successful, exit the loop
2041 else:
2042 start = start_index + 1
2043 selected_patterns = arg_strings_pattern[start:]
2044 arg_count = match_argument(action, selected_patterns)
2045 stop = start + arg_count
2046 args = arg_strings[start:stop]
2047 action_tuples.append((action, args, option_string))
2048 break
2050 # add the Optional to the list and return the index at which
2051 # the Optional's string args stopped
2052 assert action_tuples
2053 for action, args, option_string in action_tuples:
2054 take_action(action, args, option_string)
2055 return stop
2057 # the list of Positionals left to be parsed; this is modified
2058 # by consume_positionals()
2059 positionals = self._get_positional_actions()
2061 # function to convert arg_strings into positional actions
2062 def consume_positionals(start_index):
2063 # match as many Positionals as possible
2064 match_partial = self._match_arguments_partial
2065 selected_pattern = arg_strings_pattern[start_index:]
2066 arg_counts = match_partial(positionals, selected_pattern)
2068 # slice off the appropriate arg strings for each Positional
2069 # and add the Positional and its args to the list
2070 for action, arg_count in zip(positionals, arg_counts):
2071 args = arg_strings[start_index: start_index + arg_count]
2072 start_index += arg_count
2073 take_action(action, args)
2075 # slice off the Positionals that we just parsed and return the
2076 # index at which the Positionals' string args stopped
2077 positionals[:] = positionals[len(arg_counts):]
2078 return start_index
2080 # consume Positionals and Optionals alternately, until we have
2081 # passed the last option string
2082 extras = []
2083 start_index = 0
2084 if option_string_indices:
2085 max_option_string_index = max(option_string_indices)
2086 else:
2087 max_option_string_index = -1
2088 while start_index <= max_option_string_index:
2090 # consume any Positionals preceding the next option
2091 next_option_string_index = min([
2092 index
2093 for index in option_string_indices
2094 if index >= start_index])
2095 if start_index != next_option_string_index:
2096 positionals_end_index = consume_positionals(start_index)
2098 # only try to parse the next optional if we didn't consume
2099 # the option string during the positionals parsing
2100 if positionals_end_index > start_index:
2101 start_index = positionals_end_index
2102 continue
2103 else:
2104 start_index = positionals_end_index
2106 # if we consumed all the positionals we could and we're not
2107 # at the index of an option string, there were extra arguments
2108 if start_index not in option_string_indices:
2109 strings = arg_strings[start_index:next_option_string_index]
2110 extras.extend(strings)
2111 start_index = next_option_string_index
2113 # consume the next optional and any arguments for it
2114 start_index = consume_optional(start_index)
2116 # consume any positionals following the last Optional
2117 stop_index = consume_positionals(start_index)
2119 # if we didn't consume all the argument strings, there were extras
2120 extras.extend(arg_strings[stop_index:])
2122 # make sure all required actions were present and also convert
2123 # action defaults which were not given as arguments
2124 required_actions = []
2125 for action in self._actions:
2126 if action not in seen_actions:
2127 if action.required:
2128 required_actions.append(_get_action_name(action))
2129 else:
2130 # Convert action default now instead of doing it before
2131 # parsing arguments to avoid calling convert functions
2132 # twice (which may fail) if the argument was given, but
2133 # only if it was defined already in the namespace
2134 if (action.default is not None and
2135 isinstance(action.default, str) and
2136 hasattr(namespace, action.dest) and
2137 action.default is getattr(namespace, action.dest)):
2138 setattr(namespace, action.dest,
2139 self._get_value(action, action.default))
2141 if required_actions:
2142 self.error(_('the following arguments are required: %s') %
2143 ', '.join(required_actions))
2145 # make sure all required groups had one option present
2146 for group in self._mutually_exclusive_groups:
2147 if group.required:
2148 for action in group._group_actions:
2149 if action in seen_non_default_actions:
2150 break
2152 # if no actions were used, report the error
2153 else:
2154 names = [_get_action_name(action)
2155 for action in group._group_actions
2156 if action.help is not SUPPRESS]
2157 msg = _('one of the arguments %s is required')
2158 self.error(msg % ' '.join(names))
2160 # return the updated namespace and the extra arguments
2161 return namespace, extras
2163 def _read_args_from_files(self, arg_strings):
2164 # expand arguments referencing files
2165 new_arg_strings = []
2166 for arg_string in arg_strings:
2168 # for regular arguments, just add them back into the list
2169 if not arg_string or arg_string[0] not in self.fromfile_prefix_chars:
2170 new_arg_strings.append(arg_string)
2172 # replace arguments referencing files with the file content
2173 else:
2174 try:
2175 with open(arg_string[1:],
2176 encoding=_sys.getfilesystemencoding(),
2177 errors=_sys.getfilesystemencodeerrors()) as args_file:
2178 arg_strings = []
2179 for arg_line in args_file.read().splitlines():
2180 for arg in self.convert_arg_line_to_args(arg_line):
2181 arg_strings.append(arg)
2182 arg_strings = self._read_args_from_files(arg_strings)
2183 new_arg_strings.extend(arg_strings)
2184 except OSError as err:
2185 self.error(str(err))
2187 # return the modified argument list
2188 return new_arg_strings
2190 def convert_arg_line_to_args(self, arg_line):
2191 return [arg_line]
2193 def _match_argument(self, action, arg_strings_pattern):
2194 # match the pattern for this action to the arg strings
2195 nargs_pattern = self._get_nargs_pattern(action)
2196 match = _re.match(nargs_pattern, arg_strings_pattern)
2198 # raise an exception if we weren't able to find a match
2199 if match is None:
2200 nargs_errors = {
2201 None: _('expected one argument'),
2202 OPTIONAL: _('expected at most one argument'),
2203 ONE_OR_MORE: _('expected at least one argument'),
2204 }
2205 msg = nargs_errors.get(action.nargs)
2206 if msg is None:
2207 msg = ngettext('expected %s argument',
2208 'expected %s arguments',
2209 action.nargs) % action.nargs
2210 raise ArgumentError(action, msg)
2212 # return the number of arguments matched
2213 return len(match.group(1))
2215 def _match_arguments_partial(self, actions, arg_strings_pattern):
2216 # progressively shorten the actions list by slicing off the
2217 # final actions until we find a match
2218 result = []
2219 for i in range(len(actions), 0, -1):
2220 actions_slice = actions[:i]
2221 pattern = ''.join([self._get_nargs_pattern(action)
2222 for action in actions_slice])
2223 match = _re.match(pattern, arg_strings_pattern)
2224 if match is not None:
2225 result.extend([len(string) for string in match.groups()])
2226 break
2228 # return the list of arg string counts
2229 return result
2231 def _parse_optional(self, arg_string):
2232 # if it's an empty string, it was meant to be a positional
2233 if not arg_string:
2234 return None
2236 # if it doesn't start with a prefix, it was meant to be positional
2237 if not arg_string[0] in self.prefix_chars:
2238 return None
2240 # if the option string is present in the parser, return the action
2241 if arg_string in self._option_string_actions:
2242 action = self._option_string_actions[arg_string]
2243 return action, arg_string, None
2245 # if it's just a single character, it was meant to be positional
2246 if len(arg_string) == 1:
2247 return None
2249 # if the option string before the "=" is present, return the action
2250 if '=' in arg_string:
2251 option_string, explicit_arg = arg_string.split('=', 1)
2252 if option_string in self._option_string_actions:
2253 action = self._option_string_actions[option_string]
2254 return action, option_string, explicit_arg
2256 # search through all possible prefixes of the option string
2257 # and all actions in the parser for possible interpretations
2258 option_tuples = self._get_option_tuples(arg_string)
2260 # if multiple actions match, the option string was ambiguous
2261 if len(option_tuples) > 1:
2262 options = ', '.join([option_string
2263 for action, option_string, explicit_arg in option_tuples])
2264 args = {'option': arg_string, 'matches': options}
2265 msg = _('ambiguous option: %(option)s could match %(matches)s')
2266 self.error(msg % args)
2268 # if exactly one action matched, this segmentation is good,
2269 # so return the parsed action
2270 elif len(option_tuples) == 1:
2271 option_tuple, = option_tuples
2272 return option_tuple
2274 # if it was not found as an option, but it looks like a negative
2275 # number, it was meant to be positional
2276 # unless there are negative-number-like options
2277 if self._negative_number_matcher.match(arg_string):
2278 if not self._has_negative_number_optionals:
2279 return None
2281 # if it contains a space, it was meant to be a positional
2282 if ' ' in arg_string:
2283 return None
2285 # it was meant to be an optional but there is no such option
2286 # in this parser (though it might be a valid option in a subparser)
2287 return None, arg_string, None
2289 def _get_option_tuples(self, option_string):
2290 result = []
2292 # option strings starting with two prefix characters are only
2293 # split at the '='
2294 chars = self.prefix_chars
2295 if option_string[0] in chars and option_string[1] in chars:
2296 if self.allow_abbrev:
2297 if '=' in option_string:
2298 option_prefix, explicit_arg = option_string.split('=', 1)
2299 else:
2300 option_prefix = option_string
2301 explicit_arg = None
2302 for option_string in self._option_string_actions:
2303 if option_string.startswith(option_prefix):
2304 action = self._option_string_actions[option_string]
2305 tup = action, option_string, explicit_arg
2306 result.append(tup)
2308 # single character options can be concatenated with their arguments
2309 # but multiple character options always have to have their argument
2310 # separate
2311 elif option_string[0] in chars and option_string[1] not in chars: 2311 ↛ 2329line 2311 didn't jump to line 2329, because the condition on line 2311 was never false
2312 option_prefix = option_string
2313 explicit_arg = None
2314 short_option_prefix = option_string[:2]
2315 short_explicit_arg = option_string[2:]
2317 for option_string in self._option_string_actions:
2318 if option_string == short_option_prefix:
2319 action = self._option_string_actions[option_string]
2320 tup = action, option_string, short_explicit_arg
2321 result.append(tup)
2322 elif option_string.startswith(option_prefix):
2323 action = self._option_string_actions[option_string]
2324 tup = action, option_string, explicit_arg
2325 result.append(tup)
2327 # shouldn't ever get here
2328 else:
2329 self.error(_('unexpected option string: %s') % option_string)
2331 # return the collected option tuples
2332 return result
2334 def _get_nargs_pattern(self, action):
2335 # in all examples below, we have to allow for '--' args
2336 # which are represented as '-' in the pattern
2337 nargs = action.nargs
2339 # the default (None) is assumed to be a single argument
2340 if nargs is None:
2341 nargs_pattern = '(-*A-*)'
2343 # allow zero or one arguments
2344 elif nargs == OPTIONAL:
2345 nargs_pattern = '(-*A?-*)'
2347 # allow zero or more arguments
2348 elif nargs == ZERO_OR_MORE:
2349 nargs_pattern = '(-*[A-]*)'
2351 # allow one or more arguments
2352 elif nargs == ONE_OR_MORE:
2353 nargs_pattern = '(-*A[A-]*)'
2355 # allow any number of options or arguments
2356 elif nargs == REMAINDER:
2357 nargs_pattern = '([-AO]*)'
2359 # allow one argument followed by any number of options or arguments
2360 elif nargs == PARSER:
2361 nargs_pattern = '(-*A[-AO]*)'
2363 # suppress action, like nargs=0
2364 elif nargs == SUPPRESS:
2365 nargs_pattern = '(-*-*)'
2367 # all others should be integers
2368 else:
2369 nargs_pattern = '(-*%s-*)' % '-*'.join('A' * nargs)
2371 # if this is an optional action, -- is not allowed
2372 if action.option_strings:
2373 nargs_pattern = nargs_pattern.replace('-*', '')
2374 nargs_pattern = nargs_pattern.replace('-', '')
2376 # return the pattern
2377 return nargs_pattern
2379 # ========================
2380 # Alt command line argument parsing, allowing free intermix
2381 # ========================
2383 def parse_intermixed_args(self, args=None, namespace=None):
2384 args, argv = self.parse_known_intermixed_args(args, namespace)
2385 if argv: 2385 ↛ 2386line 2385 didn't jump to line 2386, because the condition on line 2385 was never true
2386 msg = _('unrecognized arguments: %s')
2387 self.error(msg % ' '.join(argv))
2388 return args
2390 def parse_known_intermixed_args(self, args=None, namespace=None):
2391 # returns a namespace and list of extras
2392 #
2393 # positional can be freely intermixed with optionals. optionals are
2394 # first parsed with all positional arguments deactivated. The 'extras'
2395 # are then parsed. If the parser definition is incompatible with the
2396 # intermixed assumptions (e.g. use of REMAINDER, subparsers) a
2397 # TypeError is raised.
2398 #
2399 # positionals are 'deactivated' by setting nargs and default to
2400 # SUPPRESS. This blocks the addition of that positional to the
2401 # namespace
2403 positionals = self._get_positional_actions()
2404 a = [action for action in positionals
2405 if action.nargs in [PARSER, REMAINDER]]
2406 if a:
2407 raise TypeError('parse_intermixed_args: positional arg'
2408 ' with nargs=%s'%a[0].nargs)
2410 if [action.dest for group in self._mutually_exclusive_groups
2411 for action in group._group_actions if action in positionals]:
2412 raise TypeError('parse_intermixed_args: positional in'
2413 ' mutuallyExclusiveGroup')
2415 try:
2416 save_usage = self.usage
2417 try:
2418 if self.usage is None:
2419 # capture the full usage for use in error messages
2420 self.usage = self.format_usage()[7:]
2421 for action in positionals:
2422 # deactivate positionals
2423 action.save_nargs = action.nargs
2424 # action.nargs = 0
2425 action.nargs = SUPPRESS
2426 action.save_default = action.default
2427 action.default = SUPPRESS
2428 namespace, remaining_args = self.parse_known_args(args,
2429 namespace)
2430 for action in positionals:
2431 # remove the empty positional values from namespace
2432 if (hasattr(namespace, action.dest) 2432 ↛ 2434line 2432 didn't jump to line 2434, because the condition on line 2432 was never true
2433 and getattr(namespace, action.dest)==[]):
2434 from warnings import warn
2435 warn('Do not expect %s in %s' % (action.dest, namespace))
2436 delattr(namespace, action.dest)
2437 finally:
2438 # restore nargs and usage before exiting
2439 for action in positionals:
2440 action.nargs = action.save_nargs
2441 action.default = action.save_default
2442 optionals = self._get_optional_actions()
2443 try:
2444 # parse positionals. optionals aren't normally required, but
2445 # they could be, so make sure they aren't.
2446 for action in optionals:
2447 action.save_required = action.required
2448 action.required = False
2449 for group in self._mutually_exclusive_groups:
2450 group.save_required = group.required
2451 group.required = False
2452 namespace, extras = self.parse_known_args(remaining_args,
2453 namespace)
2454 finally:
2455 # restore parser values before exiting
2456 for action in optionals:
2457 action.required = action.save_required
2458 for group in self._mutually_exclusive_groups:
2459 group.required = group.save_required
2460 finally:
2461 self.usage = save_usage
2462 return namespace, extras
2464 # ========================
2465 # Value conversion methods
2466 # ========================
2467 def _get_values(self, action, arg_strings):
2468 # for everything but PARSER, REMAINDER args, strip out first '--'
2469 if action.nargs not in [PARSER, REMAINDER]:
2470 try:
2471 arg_strings.remove('--')
2472 except ValueError:
2473 pass
2475 # optional argument produces a default when not present
2476 if not arg_strings and action.nargs == OPTIONAL:
2477 if action.option_strings:
2478 value = action.const
2479 else:
2480 value = action.default
2481 if isinstance(value, str):
2482 value = self._get_value(action, value)
2483 self._check_value(action, value)
2485 # when nargs='*' on a positional, if there were no command-line
2486 # args, use the default if it is anything other than None
2487 elif (not arg_strings and action.nargs == ZERO_OR_MORE and
2488 not action.option_strings):
2489 if action.default is not None:
2490 value = action.default
2491 self._check_value(action, value)
2492 else:
2493 # since arg_strings is always [] at this point
2494 # there is no need to use self._check_value(action, value)
2495 value = arg_strings
2497 # single argument or optional argument produces a single value
2498 elif len(arg_strings) == 1 and action.nargs in [None, OPTIONAL]:
2499 arg_string, = arg_strings
2500 value = self._get_value(action, arg_string)
2501 self._check_value(action, value)
2503 # REMAINDER arguments convert all values, checking none
2504 elif action.nargs == REMAINDER:
2505 value = [self._get_value(action, v) for v in arg_strings]
2507 # PARSER arguments convert all values, but check only the first
2508 elif action.nargs == PARSER:
2509 value = [self._get_value(action, v) for v in arg_strings]
2510 self._check_value(action, value[0])
2512 # SUPPRESS argument does not put anything in the namespace
2513 elif action.nargs == SUPPRESS:
2514 value = SUPPRESS
2516 # all other types of nargs produce a list
2517 else:
2518 value = [self._get_value(action, v) for v in arg_strings]
2519 for v in value:
2520 self._check_value(action, v)
2522 # return the converted value
2523 return value
2525 def _get_value(self, action, arg_string):
2526 type_func = self._registry_get('type', action.type, action.type)
2527 if not callable(type_func): 2527 ↛ 2528line 2527 didn't jump to line 2528, because the condition on line 2527 was never true
2528 msg = _('%r is not callable')
2529 raise ArgumentError(action, msg % type_func)
2531 # convert the value to the appropriate type
2532 try:
2533 result = type_func(arg_string)
2535 # ArgumentTypeErrors indicate errors
2536 except ArgumentTypeError as err:
2537 msg = str(err)
2538 raise ArgumentError(action, msg)
2540 # TypeErrors or ValueErrors also indicate errors
2541 except (TypeError, ValueError):
2542 name = getattr(action.type, '__name__', repr(action.type))
2543 args = {'type': name, 'value': arg_string}
2544 msg = _('invalid %(type)s value: %(value)r')
2545 raise ArgumentError(action, msg % args)
2547 # return the converted value
2548 return result
2550 def _check_value(self, action, value):
2551 # converted value must be one of the choices (if specified)
2552 if action.choices is not None and value not in action.choices:
2553 args = {'value': value,
2554 'choices': ', '.join(map(repr, action.choices))}
2555 msg = _('invalid choice: %(value)r (choose from %(choices)s)')
2556 raise ArgumentError(action, msg % args)
2558 # =======================
2559 # Help-formatting methods
2560 # =======================
2561 def format_usage(self):
2562 formatter = self._get_formatter()
2563 formatter.add_usage(self.usage, self._actions,
2564 self._mutually_exclusive_groups)
2565 return formatter.format_help()
2567 def format_help(self):
2568 formatter = self._get_formatter()
2570 # usage
2571 formatter.add_usage(self.usage, self._actions,
2572 self._mutually_exclusive_groups)
2574 # description
2575 formatter.add_text(self.description)
2577 # positionals, optionals and user-defined groups
2578 for action_group in self._action_groups:
2579 formatter.start_section(action_group.title)
2580 formatter.add_text(action_group.description)
2581 formatter.add_arguments(action_group._group_actions)
2582 formatter.end_section()
2584 # epilog
2585 formatter.add_text(self.epilog)
2587 # determine help from format above
2588 return formatter.format_help()
2590 def _get_formatter(self):
2591 return self.formatter_class(prog=self.prog)
2593 # =====================
2594 # Help-printing methods
2595 # =====================
2596 def print_usage(self, file=None):
2597 if file is None:
2598 file = _sys.stdout
2599 self._print_message(self.format_usage(), file)
2601 def print_help(self, file=None):
2602 if file is None:
2603 file = _sys.stdout
2604 self._print_message(self.format_help(), file)
2606 def _print_message(self, message, file=None):
2607 if message:
2608 if file is None: 2608 ↛ 2609line 2608 didn't jump to line 2609, because the condition on line 2608 was never true
2609 file = _sys.stderr
2610 file.write(message)
2612 # ===============
2613 # Exiting methods
2614 # ===============
2615 def exit(self, status=0, message=None):
2616 if message:
2617 self._print_message(message, _sys.stderr)
2618 _sys.exit(status)
2620 def error(self, message):
2621 """error(message: string)
2623 Prints a usage message incorporating the message to stderr and
2624 exits.
2626 If you override this in a subclass, it should not return -- it
2627 should either exit or raise an exception.
2628 """
2629 self.print_usage(_sys.stderr)
2630 args = {'prog': self.prog, 'message': message}
2631 self.exit(2, _('%(prog)s: error: %(message)s\n') % args)