Initial.
1 # Author: Steven J. Bethard <steven.bethard@gmail.com>.
3 """Command-line parsing library
5 This module is an optparse-inspired command-line parsing library that:
7 - handles both optional and positional arguments
8 - produces highly informative usage messages
9 - supports parsers that dispatch to sub-parsers
11 The following is a simple usage example that sums integers from the
12 command-line and writes the result to a file::
14 parser = argparse.ArgumentParser(
15 description='sum the integers at the command line')
17 'integers', metavar='int', nargs='+', type=int,
18 help='an integer to be summed')
20 '--log', default=sys.stdout, type=argparse.FileType('w'),
21 help='the file where the sum should be written')
22 args = parser.parse_args()
23 args.log.write('%s' % sum(args.integers))
26 The module contains the following public classes:
28 - ArgumentParser -- The main entry point for command-line parsing. As the
29 example above shows, the add_argument() method is used to populate
30 the parser with actions for optional and positional arguments. Then
31 the parse_args() method is invoked to convert the args at the
32 command-line into an object with attributes.
34 - ArgumentError -- The exception raised by ArgumentParser objects when
35 there are errors with the parser's actions. Errors raised while
36 parsing the command-line are caught by ArgumentParser and emitted
37 as command-line messages.
39 - FileType -- A factory for defining types of files to be created. As the
40 example above shows, instances of FileType are typically passed as
41 the type= argument of add_argument() calls.
43 - Action -- The base class for parser actions. Typically actions are
44 selected by passing strings like 'store_true' or 'append_const' to
45 the action= argument of add_argument(). However, for greater
46 customization of ArgumentParser actions, subclasses of Action may
47 be defined and passed as the action= argument.
49 - HelpFormatter, RawDescriptionHelpFormatter, RawTextHelpFormatter,
50 ArgumentDefaultsHelpFormatter -- Formatter classes which
51 may be passed as the formatter_class= argument to the
52 ArgumentParser constructor. HelpFormatter is the default,
53 RawDescriptionHelpFormatter and RawTextHelpFormatter tell the parser
54 not to change the formatting for help text, and
55 ArgumentDefaultsHelpFormatter adds information about argument defaults
58 All other classes in this module are considered implementation details.
59 (Also note that HelpFormatter and RawDescriptionHelpFormatter are only
60 considered public as object names -- the API of the formatter objects is
61 still considered an implementation detail.)
72 'RawDescriptionHelpFormatter',
73 'RawTextHelpFormatter',
74 'ArgumentDefaultsHelpFormatter',
82 import textwrap as _textwrap
84 from gettext import gettext as _
88 return hasattr(obj, '__call__') or hasattr(obj, '__bases__')
91 SUPPRESS = '==SUPPRESS=='
99 # =============================
100 # Utility functions and classes
101 # =============================
103 class _AttributeHolder(object):
104 """Abstract base class that provides __repr__.
106 The __repr__ method returns a string in the format::
107 ClassName(attr=name, attr=name, ...)
108 The attributes are determined either by a class-level attribute,
109 '_kwarg_names', or by inspecting the instance __dict__.
113 type_name = type(self).__name__
115 for arg in self._get_args():
116 arg_strings.append(repr(arg))
117 for name, value in self._get_kwargs():
118 arg_strings.append('%s=%r' % (name, value))
119 return '%s(%s)' % (type_name, ', '.join(arg_strings))
121 def _get_kwargs(self):
122 return sorted(self.__dict__.items())
128 def _ensure_value(namespace, name, value):
129 if getattr(namespace, name, None) is None:
130 setattr(namespace, name, value)
131 return getattr(namespace, name)
138 class HelpFormatter(object):
139 """Formatter for generating usage messages and argument help strings.
141 Only the name of this class is considered a public API. All the methods
142 provided by the class are considered an implementation detail.
148 max_help_position=24,
151 # default setting for width
154 width = int(_os.environ['COLUMNS'])
155 except (KeyError, ValueError):
160 self._indent_increment = indent_increment
161 self._max_help_position = max_help_position
164 self._current_indent = 0
166 self._action_max_length = 0
168 self._root_section = self._Section(self, None)
169 self._current_section = self._root_section
171 self._whitespace_matcher = _re.compile(r'\s+')
172 self._long_break_matcher = _re.compile(r'\n\n\n+')
174 # ===============================
175 # Section and indentation methods
176 # ===============================
178 self._current_indent += self._indent_increment
182 self._current_indent -= self._indent_increment
183 assert self._current_indent >= 0, 'Indent decreased below 0.'
186 class _Section(object):
188 def __init__(self, formatter, parent, heading=None):
189 self.formatter = formatter
191 self.heading = heading
194 def format_help(self):
195 # format the indented section
196 if self.parent is not None:
197 self.formatter._indent()
198 join = self.formatter._join_parts
199 for func, args in self.items:
201 item_help = join([func(*args) for func, args in self.items])
202 if self.parent is not None:
203 self.formatter._dedent()
205 # return nothing if the section was empty
209 # add the heading if the section was non-empty
210 if self.heading is not SUPPRESS and self.heading is not None:
211 current_indent = self.formatter._current_indent
212 heading = '%*s%s:\n' % (current_indent, '', self.heading)
216 # join the section-initial newline, the heading and the help
217 return join(['\n', heading, item_help, '\n'])
219 def _add_item(self, func, args):
220 self._current_section.items.append((func, args))
222 # ========================
223 # Message building methods
224 # ========================
225 def start_section(self, heading):
227 section = self._Section(self, self._current_section, heading)
228 self._add_item(section.format_help, [])
229 self._current_section = section
231 def end_section(self):
232 self._current_section = self._current_section.parent
235 def add_text(self, text):
236 if text is not SUPPRESS and text is not None:
237 self._add_item(self._format_text, [text])
239 def add_usage(self, usage, actions, groups, prefix=None):
240 if usage is not SUPPRESS:
241 args = usage, actions, groups, prefix
242 self._add_item(self._format_usage, args)
244 def add_argument(self, action):
245 if action.help is not SUPPRESS:
247 # find all invocations
248 get_invocation = self._format_action_invocation
249 invocations = [get_invocation(action)]
250 for subaction in self._iter_indented_subactions(action):
251 invocations.append(get_invocation(subaction))
253 # update the maximum item length
254 invocation_length = max([len(s) for s in invocations])
255 action_length = invocation_length + self._current_indent
256 self._action_max_length = max(self._action_max_length,
259 # add the item to the list
260 self._add_item(self._format_action, [action])
262 def add_arguments(self, actions):
263 for action in actions:
264 self.add_argument(action)
266 # =======================
267 # Help-formatting methods
268 # =======================
269 def format_help(self):
270 help = self._root_section.format_help()
272 help = self._long_break_matcher.sub('\n\n', help)
273 help = help.strip('\n') + '\n'
276 def _join_parts(self, part_strings):
278 for part in part_strings
279 if part and part is not SUPPRESS])
281 def _format_usage(self, usage, actions, groups, prefix):
283 prefix = _('usage: ')
285 # if usage is specified, use that
286 if usage is not None:
287 usage = usage % dict(prog=self._prog)
289 # if no optionals or positionals are available, usage is just prog
290 elif usage is None and not actions:
291 usage = '%(prog)s' % dict(prog=self._prog)
293 # if optionals and positionals are available, calculate usage
295 prog = '%(prog)s' % dict(prog=self._prog)
297 # split optionals from positionals
300 for action in actions:
301 if action.option_strings:
302 optionals.append(action)
304 positionals.append(action)
306 # build full usage string
307 format = self._format_actions_usage
308 action_usage = format(optionals + positionals, groups)
309 usage = ' '.join([s for s in [prog, action_usage] if s])
311 # wrap the usage parts if it's too long
312 text_width = self._width - self._current_indent
313 if len(prefix) + len(usage) > text_width:
315 # break usage into wrappable parts
316 part_regexp = r'\(.*?\)+|\[.*?\]+|\S+'
317 opt_usage = format(optionals, groups)
318 pos_usage = format(positionals, groups)
319 opt_parts = _re.findall(part_regexp, opt_usage)
320 pos_parts = _re.findall(part_regexp, pos_usage)
321 assert ' '.join(opt_parts) == opt_usage
322 assert ' '.join(pos_parts) == pos_usage
324 # helper for wrapping lines
325 def get_lines(parts, indent, prefix=None):
328 if prefix is not None:
329 line_len = len(prefix) - 1
331 line_len = len(indent) - 1
333 if line_len + 1 + len(part) > text_width:
334 lines.append(indent + ' '.join(line))
336 line_len = len(indent) - 1
338 line_len += len(part) + 1
340 lines.append(indent + ' '.join(line))
341 if prefix is not None:
342 lines[0] = lines[0][len(indent):]
345 # if prog is short, follow it with optionals or positionals
346 if len(prefix) + len(prog) <= 0.75 * text_width:
347 indent = ' ' * (len(prefix) + len(prog) + 1)
349 lines = get_lines([prog] + opt_parts, indent, prefix)
350 lines.extend(get_lines(pos_parts, indent))
352 lines = get_lines([prog] + pos_parts, indent, prefix)
356 # if prog is long, put it on its own line
358 indent = ' ' * len(prefix)
359 parts = opt_parts + pos_parts
360 lines = get_lines(parts, indent)
363 lines.extend(get_lines(opt_parts, indent))
364 lines.extend(get_lines(pos_parts, indent))
365 lines = [prog] + lines
367 # join lines into usage
368 usage = '\n'.join(lines)
370 # prefix with 'usage:'
371 return '%s%s\n\n' % (prefix, usage)
373 def _format_actions_usage(self, actions, groups):
374 # find group indices and identify actions in groups
375 group_actions = set()
379 start = actions.index(group._group_actions[0])
383 end = start + len(group._group_actions)
384 if actions[start:end] == group._group_actions:
385 for action in group._group_actions:
386 group_actions.add(action)
387 if not group.required:
393 for i in range(start + 1, end):
396 # collect all actions format strings
398 for i, action in enumerate(actions):
400 # suppressed arguments are marked with None
401 # remove | separators for suppressed arguments
402 if action.help is SUPPRESS:
404 if inserts.get(i) == '|':
406 elif inserts.get(i + 1) == '|':
409 # produce all arg strings
410 elif not action.option_strings:
411 part = self._format_args(action, action.dest)
413 # if it's in a group, strip the outer []
414 if action in group_actions:
415 if part[0] == '[' and part[-1] == ']':
418 # add the action string to the list
421 # produce the first way to invoke the option in brackets
423 option_string = action.option_strings[0]
425 # if the Optional doesn't take a value, format is:
427 if action.nargs == 0:
428 part = '%s' % option_string
430 # if the Optional takes a value, format is:
431 # -s ARGS or --long ARGS
433 default = action.dest.upper()
434 args_string = self._format_args(action, default)
435 part = '%s %s' % (option_string, args_string)
437 # make it look optional if it's not required or in a group
438 if not action.required and action not in group_actions:
441 # add the action string to the list
444 # insert things at the necessary indices
445 for i in sorted(inserts, reverse=True):
446 parts[i:i] = [inserts[i]]
448 # join all the action items with spaces
449 text = ' '.join([item for item in parts if item is not None])
451 # clean up separators for mutually exclusive groups
454 text = _re.sub(r'(%s) ' % open, r'\1', text)
455 text = _re.sub(r' (%s)' % close, r'\1', text)
456 text = _re.sub(r'%s *%s' % (open, close), r'', text)
457 text = _re.sub(r'\(([^|]*)\)', r'\1', text)
463 def _format_text(self, text):
464 if '%(prog)' in text:
465 text = text % dict(prog=self._prog)
466 text_width = self._width - self._current_indent
467 indent = ' ' * self._current_indent
468 return self._fill_text(text, text_width, indent) + '\n\n'
470 def _format_action(self, action):
471 # determine the required width and the entry label
472 help_position = min(self._action_max_length + 2,
473 self._max_help_position)
474 help_width = self._width - help_position
475 action_width = help_position - self._current_indent - 2
476 action_header = self._format_action_invocation(action)
478 # ho nelp; start on same line and add a final newline
480 tup = self._current_indent, '', action_header
481 action_header = '%*s%s\n' % tup
483 # short action name; start on the same line and pad two spaces
484 elif len(action_header) <= action_width:
485 tup = self._current_indent, '', action_width, action_header
486 action_header = '%*s%-*s ' % tup
489 # long action name; start on the next line
491 tup = self._current_indent, '', action_header
492 action_header = '%*s%s\n' % tup
493 indent_first = help_position
495 # collect the pieces of the action help
496 parts = [action_header]
498 # if there was help for the action, add lines of help text
500 help_text = self._expand_help(action)
501 help_lines = self._split_lines(help_text, help_width)
502 parts.append('%*s%s\n' % (indent_first, '', help_lines[0]))
503 for line in help_lines[1:]:
504 parts.append('%*s%s\n' % (help_position, '', line))
506 # or add a newline if the description doesn't end with one
507 elif not action_header.endswith('\n'):
510 # if there are any sub-actions, add their help as well
511 for subaction in self._iter_indented_subactions(action):
512 parts.append(self._format_action(subaction))
514 # return a single string
515 return self._join_parts(parts)
517 def _format_action_invocation(self, action):
518 if not action.option_strings:
519 metavar, = self._metavar_formatter(action, action.dest)(1)
525 # if the Optional doesn't take a value, format is:
527 if action.nargs == 0:
528 parts.extend(action.option_strings)
530 # if the Optional takes a value, format is:
531 # -s ARGS, --long ARGS
533 default = action.dest.upper()
534 args_string = self._format_args(action, default)
535 for option_string in action.option_strings:
536 parts.append('%s %s' % (option_string, args_string))
538 return ', '.join(parts)
540 def _metavar_formatter(self, action, default_metavar):
541 if action.metavar is not None:
542 result = action.metavar
543 elif action.choices is not None:
544 choice_strs = [str(choice) for choice in action.choices]
545 result = '{%s}' % ','.join(choice_strs)
547 result = default_metavar
549 def format(tuple_size):
550 if isinstance(result, tuple):
553 return (result, ) * tuple_size
556 def _format_args(self, action, default_metavar):
557 get_metavar = self._metavar_formatter(action, default_metavar)
558 if action.nargs is None:
559 result = '%s' % get_metavar(1)
560 elif action.nargs == OPTIONAL:
561 result = '[%s]' % get_metavar(1)
562 elif action.nargs == ZERO_OR_MORE:
563 result = '[%s [%s ...]]' % get_metavar(2)
564 elif action.nargs == ONE_OR_MORE:
565 result = '%s [%s ...]' % get_metavar(2)
566 elif action.nargs == REMAINDER:
568 elif action.nargs == PARSER:
569 result = '%s ...' % get_metavar(1)
571 formats = ['%s' for _ in range(action.nargs)]
572 result = ' '.join(formats) % get_metavar(action.nargs)
575 def _expand_help(self, action):
576 params = dict(vars(action), prog=self._prog)
577 for name in list(params):
578 if params[name] is SUPPRESS:
580 for name in list(params):
581 if hasattr(params[name], '__name__'):
582 params[name] = params[name].__name__
583 if params.get('choices') is not None:
584 choices_str = ', '.join([str(c) for c in params['choices']])
585 params['choices'] = choices_str
586 return self._get_help_string(action) % params
588 def _iter_indented_subactions(self, action):
590 get_subactions = action._get_subactions
591 except AttributeError:
595 for subaction in get_subactions():
599 def _split_lines(self, text, width):
600 text = self._whitespace_matcher.sub(' ', text).strip()
601 return _textwrap.wrap(text, width)
603 def _fill_text(self, text, width, indent):
604 text = self._whitespace_matcher.sub(' ', text).strip()
605 return _textwrap.fill(text, width, initial_indent=indent,
606 subsequent_indent=indent)
608 def _get_help_string(self, action):
612 class RawDescriptionHelpFormatter(HelpFormatter):
613 """Help message formatter which retains any formatting in descriptions.
615 Only the name of this class is considered a public API. All the methods
616 provided by the class are considered an implementation detail.
619 def _fill_text(self, text, width, indent):
620 return ''.join([indent + line for line in text.splitlines(True)])
623 class RawTextHelpFormatter(RawDescriptionHelpFormatter):
624 """Help message formatter which retains formatting of all help text.
626 Only the name of this class is considered a public API. All the methods
627 provided by the class are considered an implementation detail.
630 def _split_lines(self, text, width):
631 return text.splitlines()
634 class ArgumentDefaultsHelpFormatter(HelpFormatter):
635 """Help message formatter which adds default values to argument help.
637 Only the name of this class is considered a public API. All the methods
638 provided by the class are considered an implementation detail.
641 def _get_help_string(self, action):
643 if '%(default)' not in action.help:
644 if action.default is not SUPPRESS:
645 defaulting_nargs = [OPTIONAL, ZERO_OR_MORE]
646 if action.option_strings or action.nargs in defaulting_nargs:
647 help += ' (default: %(default)s)'
651 # =====================
652 # Options and Arguments
653 # =====================
655 def _get_action_name(argument):
658 elif argument.option_strings:
659 return '/'.join(argument.option_strings)
660 elif argument.metavar not in (None, SUPPRESS):
661 return argument.metavar
662 elif argument.dest not in (None, SUPPRESS):
668 class ArgumentError(Exception):
669 """An error from creating or using an argument (optional or positional).
671 The string value of this exception is the message, augmented with
672 information about the argument that caused it.
675 def __init__(self, argument, message):
676 self.argument_name = _get_action_name(argument)
677 self.message = message
680 if self.argument_name is None:
681 format = '%(message)s'
683 format = 'argument %(argument_name)s: %(message)s'
684 return format % dict(message=self.message,
685 argument_name=self.argument_name)
688 class ArgumentTypeError(Exception):
689 """An error from trying to convert a command line string to a type."""
697 class Action(_AttributeHolder):
698 """Information about how to convert command line strings to Python objects.
700 Action objects are used by an ArgumentParser to represent the information
701 needed to parse a single argument from one or more strings from the
702 command line. The keyword arguments to the Action constructor are also
703 all attributes of Action instances.
707 - option_strings -- A list of command-line option strings which
708 should be associated with this action.
710 - dest -- The name of the attribute to hold the created object(s)
712 - nargs -- The number of command-line arguments that should be
713 consumed. By default, one argument will be consumed and a single
714 value will be produced. Other values include:
715 - N (an integer) consumes N arguments (and produces a list)
716 - '?' consumes zero or one arguments
717 - '*' consumes zero or more arguments (and produces a list)
718 - '+' consumes one or more arguments (and produces a list)
719 Note that the difference between the default and nargs=1 is that
720 with the default, a single value will be produced, while with
721 nargs=1, a list containing a single value will be produced.
723 - const -- The value to be produced if the option is specified and the
724 option uses an action that takes no values.
726 - default -- The value to be produced if the option is not specified.
728 - type -- The type which the command-line arguments should be converted
729 to, should be one of 'string', 'int', 'float', 'complex' or a
730 callable object that accepts a single string argument. If None,
733 - choices -- A container of values that should be allowed. If not None,
734 after a command-line argument has been converted to the appropriate
735 type, an exception will be raised if it is not a member of this
738 - required -- True if the action must always be specified at the
739 command line. This is only meaningful for optional command-line
742 - help -- The help string describing the argument.
744 - metavar -- The name to be used for the option's argument with the
745 help string. If None, the 'dest' value will be used as the name.
759 self.option_strings = option_strings
763 self.default = default
765 self.choices = choices
766 self.required = required
768 self.metavar = metavar
770 def _get_kwargs(self):
782 return [(name, getattr(self, name)) for name in names]
784 def __call__(self, parser, namespace, values, option_string=None):
785 raise NotImplementedError(_('.__call__() not defined'))
788 class _StoreAction(Action):
802 raise ValueError('nargs for store actions must be > 0; if you '
803 'have nothing to store, actions such as store '
804 'true or store const may be more appropriate')
805 if const is not None and nargs != OPTIONAL:
806 raise ValueError('nargs must be %r to supply const' % OPTIONAL)
807 super(_StoreAction, self).__init__(
808 option_strings=option_strings,
819 def __call__(self, parser, namespace, values, option_string=None):
820 setattr(namespace, self.dest, values)
823 class _StoreConstAction(Action):
833 super(_StoreConstAction, self).__init__(
834 option_strings=option_strings,
842 def __call__(self, parser, namespace, values, option_string=None):
843 setattr(namespace, self.dest, self.const)
846 class _StoreTrueAction(_StoreConstAction):
854 super(_StoreTrueAction, self).__init__(
855 option_strings=option_strings,
863 class _StoreFalseAction(_StoreConstAction):
871 super(_StoreFalseAction, self).__init__(
872 option_strings=option_strings,
880 class _AppendAction(Action):
894 raise ValueError('nargs for append actions must be > 0; if arg '
895 'strings are not supplying the value to append, '
896 'the append const action may be more appropriate')
897 if const is not None and nargs != OPTIONAL:
898 raise ValueError('nargs must be %r to supply const' % OPTIONAL)
899 super(_AppendAction, self).__init__(
900 option_strings=option_strings,
911 def __call__(self, parser, namespace, values, option_string=None):
912 items = _copy.copy(_ensure_value(namespace, self.dest, []))
914 setattr(namespace, self.dest, items)
917 class _AppendConstAction(Action):
927 super(_AppendConstAction, self).__init__(
928 option_strings=option_strings,
937 def __call__(self, parser, namespace, values, option_string=None):
938 items = _copy.copy(_ensure_value(namespace, self.dest, []))
939 items.append(self.const)
940 setattr(namespace, self.dest, items)
943 class _CountAction(Action):
951 super(_CountAction, self).__init__(
952 option_strings=option_strings,
959 def __call__(self, parser, namespace, values, option_string=None):
960 new_count = _ensure_value(namespace, self.dest, 0) + 1
961 setattr(namespace, self.dest, new_count)
964 class _HelpAction(Action):
971 super(_HelpAction, self).__init__(
972 option_strings=option_strings,
978 def __call__(self, parser, namespace, values, option_string=None):
983 class _VersionAction(Action):
990 help="show program's version number and exit"):
991 super(_VersionAction, self).__init__(
992 option_strings=option_strings,
997 self.version = version
999 def __call__(self, parser, namespace, values, option_string=None):
1000 version = self.version
1002 version = parser.version
1003 formatter = parser._get_formatter()
1004 formatter.add_text(version)
1005 parser.exit(message=formatter.format_help())
1008 class _SubParsersAction(Action):
1010 class _ChoicesPseudoAction(Action):
1012 def __init__(self, name, help):
1013 sup = super(_SubParsersAction._ChoicesPseudoAction, self)
1014 sup.__init__(option_strings=[], dest=name, help=help)
1024 self._prog_prefix = prog
1025 self._parser_class = parser_class
1026 self._name_parser_map = {}
1027 self._choices_actions = []
1029 super(_SubParsersAction, self).__init__(
1030 option_strings=option_strings,
1033 choices=self._name_parser_map,
1037 def add_parser(self, name, **kwargs):
1038 # set prog from the existing prefix
1039 if kwargs.get('prog') is None:
1040 kwargs['prog'] = '%s %s' % (self._prog_prefix, name)
1042 # create a pseudo-action to hold the choice help
1043 if 'help' in kwargs:
1044 help = kwargs.pop('help')
1045 choice_action = self._ChoicesPseudoAction(name, help)
1046 self._choices_actions.append(choice_action)
1048 # create the parser and add it to the map
1049 parser = self._parser_class(**kwargs)
1050 self._name_parser_map[name] = parser
1053 def _get_subactions(self):
1054 return self._choices_actions
1056 def __call__(self, parser, namespace, values, option_string=None):
1057 parser_name = values[0]
1058 arg_strings = values[1:]
1060 # set the parser name if requested
1061 if self.dest is not SUPPRESS:
1062 setattr(namespace, self.dest, parser_name)
1066 parser = self._name_parser_map[parser_name]
1068 tup = parser_name, ', '.join(self._name_parser_map)
1069 msg = _('unknown parser %r (choices: %s)' % tup)
1070 raise ArgumentError(self, msg)
1072 # parse all the remaining options into the namespace
1073 parser.parse_args(arg_strings, namespace)
1080 class FileType(object):
1081 """Factory for creating file object types
1083 Instances of FileType are typically passed as type= arguments to the
1084 ArgumentParser add_argument() method.
1087 - mode -- A string indicating how the file is to be opened. Accepts the
1088 same values as the builtin open() function.
1089 - bufsize -- The file's desired buffer size. Accepts the same values as
1090 the builtin open() function.
1093 def __init__(self, mode='r', bufsize=None):
1095 self._bufsize = bufsize
1097 def __call__(self, string):
1098 # the special argument "-" means sys.std{in,out}
1100 if 'r' in self._mode:
1102 elif 'w' in self._mode:
1105 msg = _('argument "-" with mode %r' % self._mode)
1106 raise ValueError(msg)
1108 # all other arguments are used as file names
1110 return open(string, self._mode, self._bufsize)
1112 return open(string, self._mode)
1115 args = [self._mode, self._bufsize]
1116 args_str = ', '.join([repr(arg) for arg in args if arg is not None])
1117 return '%s(%s)' % (type(self).__name__, args_str)
1119 # ===========================
1120 # Optional and Positional Parsing
1121 # ===========================
1123 class Namespace(_AttributeHolder):
1124 """Simple object for storing attributes.
1126 Implements equality by attribute names and values, and provides a simple
1127 string representation.
1130 def __init__(self, **kwargs):
1132 setattr(self, name, kwargs[name])
1134 def __eq__(self, other):
1135 return vars(self) == vars(other)
1137 def __ne__(self, other):
1138 return not (self == other)
1140 def __contains__(self, key):
1141 return key in self.__dict__
1144 class _ActionsContainer(object):
1151 super(_ActionsContainer, self).__init__()
1153 self.description = description
1154 self.argument_default = argument_default
1155 self.prefix_chars = prefix_chars
1156 self.conflict_handler = conflict_handler
1159 self._registries = {}
1162 self.register('action', None, _StoreAction)
1163 self.register('action', 'store', _StoreAction)
1164 self.register('action', 'store_const', _StoreConstAction)
1165 self.register('action', 'store_true', _StoreTrueAction)
1166 self.register('action', 'store_false', _StoreFalseAction)
1167 self.register('action', 'append', _AppendAction)
1168 self.register('action', 'append_const', _AppendConstAction)
1169 self.register('action', 'count', _CountAction)
1170 self.register('action', 'help', _HelpAction)
1171 self.register('action', 'version', _VersionAction)
1172 self.register('action', 'parsers', _SubParsersAction)
1174 # raise an exception if the conflict handler is invalid
1179 self._option_string_actions = {}
1182 self._action_groups = []
1183 self._mutually_exclusive_groups = []
1188 # determines whether an "option" looks like a negative number
1189 self._negative_number_matcher = _re.compile(r'^-\d+$|^-\d*\.\d+$')
1191 # whether or not there are any optionals that look like negative
1192 # numbers -- uses a list so it can be shared and edited
1193 self._has_negative_number_optionals = []
1195 # ====================
1196 # Registration methods
1197 # ====================
1198 def register(self, registry_name, value, object):
1199 registry = self._registries.setdefault(registry_name, {})
1200 registry[value] = object
1202 def _registry_get(self, registry_name, value, default=None):
1203 return self._registries[registry_name].get(value, default)
1205 # ==================================
1206 # Namespace default accessor methods
1207 # ==================================
1208 def set_defaults(self, **kwargs):
1209 self._defaults.update(kwargs)
1211 # if these defaults match any existing arguments, replace
1212 # the previous default on the object with the new one
1213 for action in self._actions:
1214 if action.dest in kwargs:
1215 action.default = kwargs[action.dest]
1217 def get_default(self, dest):
1218 for action in self._actions:
1219 if action.dest == dest and action.default is not None:
1220 return action.default
1221 return self._defaults.get(dest, None)
1224 # =======================
1225 # Adding argument actions
1226 # =======================
1227 def add_argument(self, *args, **kwargs):
1229 add_argument(dest, ..., name=value, ...)
1230 add_argument(option_string, option_string, ..., name=value, ...)
1233 # if no positional args are supplied or only one is supplied and
1234 # it doesn't look like an option string, parse a positional
1236 chars = self.prefix_chars
1237 if not args or len(args) == 1 and args[0][0] not in chars:
1238 if args and 'dest' in kwargs:
1239 raise ValueError('dest supplied twice for positional argument')
1240 kwargs = self._get_positional_kwargs(*args, **kwargs)
1242 # otherwise, we're adding an optional argument
1244 kwargs = self._get_optional_kwargs(*args, **kwargs)
1246 # if no default was supplied, use the parser-level default
1247 if 'default' not in kwargs:
1248 dest = kwargs['dest']
1249 if dest in self._defaults:
1250 kwargs['default'] = self._defaults[dest]
1251 elif self.argument_default is not None:
1252 kwargs['default'] = self.argument_default
1254 # create the action object, and add it to the parser
1255 action_class = self._pop_action_class(kwargs)
1256 if not _callable(action_class):
1257 raise ValueError('unknown action "%s"' % action_class)
1258 action = action_class(**kwargs)
1260 # raise an error if the action type is not callable
1261 type_func = self._registry_get('type', action.type, action.type)
1262 if not _callable(type_func):
1263 raise ValueError('%r is not callable' % type_func)
1265 return self._add_action(action)
1267 def add_argument_group(self, *args, **kwargs):
1268 group = _ArgumentGroup(self, *args, **kwargs)
1269 self._action_groups.append(group)
1272 def add_mutually_exclusive_group(self, **kwargs):
1273 group = _MutuallyExclusiveGroup(self, **kwargs)
1274 self._mutually_exclusive_groups.append(group)
1277 def _add_action(self, action):
1278 # resolve any conflicts
1279 self._check_conflict(action)
1281 # add to actions list
1282 self._actions.append(action)
1283 action.container = self
1285 # index the action by any option strings it has
1286 for option_string in action.option_strings:
1287 self._option_string_actions[option_string] = action
1289 # set the flag if any option strings look like negative numbers
1290 for option_string in action.option_strings:
1291 if self._negative_number_matcher.match(option_string):
1292 if not self._has_negative_number_optionals:
1293 self._has_negative_number_optionals.append(True)
1295 # return the created action
1298 def _remove_action(self, action):
1299 self._actions.remove(action)
1301 def _add_container_actions(self, container):
1302 # collect groups by titles
1303 title_group_map = {}
1304 for group in self._action_groups:
1305 if group.title in title_group_map:
1306 msg = _('cannot merge actions - two groups are named %r')
1307 raise ValueError(msg % (group.title))
1308 title_group_map[group.title] = group
1310 # map each action to its group
1312 for group in container._action_groups:
1314 # if a group with the title exists, use that, otherwise
1315 # create a new group matching the container's group
1316 if group.title not in title_group_map:
1317 title_group_map[group.title] = self.add_argument_group(
1319 description=group.description,
1320 conflict_handler=group.conflict_handler)
1322 # map the actions to their new group
1323 for action in group._group_actions:
1324 group_map[action] = title_group_map[group.title]
1326 # add container's mutually exclusive groups
1327 # NOTE: if add_mutually_exclusive_group ever gains title= and
1328 # description= then this code will need to be expanded as above
1329 for group in container._mutually_exclusive_groups:
1330 mutex_group = self.add_mutually_exclusive_group(
1331 required=group.required)
1333 # map the actions to their new mutex group
1334 for action in group._group_actions:
1335 group_map[action] = mutex_group
1337 # add all actions to this container or their group
1338 for action in container._actions:
1339 group_map.get(action, self)._add_action(action)
1341 def _get_positional_kwargs(self, dest, **kwargs):
1342 # make sure required is not specified
1343 if 'required' in kwargs:
1344 msg = _("'required' is an invalid argument for positionals")
1345 raise TypeError(msg)
1347 # mark positional arguments as required if at least one is
1349 if kwargs.get('nargs') not in [OPTIONAL, ZERO_OR_MORE]:
1350 kwargs['required'] = True
1351 if kwargs.get('nargs') == ZERO_OR_MORE and 'default' not in kwargs:
1352 kwargs['required'] = True
1354 # return the keyword arguments with no option strings
1355 return dict(kwargs, dest=dest, option_strings=[])
1357 def _get_optional_kwargs(self, *args, **kwargs):
1358 # determine short and long option strings
1360 long_option_strings = []
1361 for option_string in args:
1362 # error on strings that don't start with an appropriate prefix
1363 if not option_string[0] in self.prefix_chars:
1364 msg = _('invalid option string %r: '
1365 'must start with a character %r')
1366 tup = option_string, self.prefix_chars
1367 raise ValueError(msg % tup)
1369 # strings starting with two prefix characters are long options
1370 option_strings.append(option_string)
1371 if option_string[0] in self.prefix_chars:
1372 if len(option_string) > 1:
1373 if option_string[1] in self.prefix_chars:
1374 long_option_strings.append(option_string)
1376 # infer destination, '--foo-bar' -> 'foo_bar' and '-x' -> 'x'
1377 dest = kwargs.pop('dest', None)
1379 if long_option_strings:
1380 dest_option_string = long_option_strings[0]
1382 dest_option_string = option_strings[0]
1383 dest = dest_option_string.lstrip(self.prefix_chars)
1385 msg = _('dest= is required for options like %r')
1386 raise ValueError(msg % option_string)
1387 dest = dest.replace('-', '_')
1389 # return the updated keyword arguments
1390 return dict(kwargs, dest=dest, option_strings=option_strings)
1392 def _pop_action_class(self, kwargs, default=None):
1393 action = kwargs.pop('action', default)
1394 return self._registry_get('action', action, action)
1396 def _get_handler(self):
1397 # determine function from conflict handler string
1398 handler_func_name = '_handle_conflict_%s' % self.conflict_handler
1400 return getattr(self, handler_func_name)
1401 except AttributeError:
1402 msg = _('invalid conflict_resolution value: %r')
1403 raise ValueError(msg % self.conflict_handler)
1405 def _check_conflict(self, action):
1407 # find all options that conflict with this option
1408 confl_optionals = []
1409 for option_string in action.option_strings:
1410 if option_string in self._option_string_actions:
1411 confl_optional = self._option_string_actions[option_string]
1412 confl_optionals.append((option_string, confl_optional))
1414 # resolve any conflicts
1416 conflict_handler = self._get_handler()
1417 conflict_handler(action, confl_optionals)
1419 def _handle_conflict_error(self, action, conflicting_actions):
1420 message = _('conflicting option string(s): %s')
1421 conflict_string = ', '.join([option_string
1422 for option_string, action
1423 in conflicting_actions])
1424 raise ArgumentError(action, message % conflict_string)
1426 def _handle_conflict_resolve(self, action, conflicting_actions):
1428 # remove all conflicting options
1429 for option_string, action in conflicting_actions:
1431 # remove the conflicting option
1432 action.option_strings.remove(option_string)
1433 self._option_string_actions.pop(option_string, None)
1435 # if the option now has no option string, remove it from the
1436 # container holding it
1437 if not action.option_strings:
1438 action.container._remove_action(action)
1441 class _ArgumentGroup(_ActionsContainer):
1443 def __init__(self, container, title=None, description=None, **kwargs):
1444 # add any missing keyword arguments by checking the container
1445 update = kwargs.setdefault
1446 update('conflict_handler', container.conflict_handler)
1447 update('prefix_chars', container.prefix_chars)
1448 update('argument_default', container.argument_default)
1449 super_init = super(_ArgumentGroup, self).__init__
1450 super_init(description=description, **kwargs)
1454 self._group_actions = []
1456 # share most attributes with the container
1457 self._registries = container._registries
1458 self._actions = container._actions
1459 self._option_string_actions = container._option_string_actions
1460 self._defaults = container._defaults
1461 self._has_negative_number_optionals = \
1462 container._has_negative_number_optionals
1464 def _add_action(self, action):
1465 action = super(_ArgumentGroup, self)._add_action(action)
1466 self._group_actions.append(action)
1469 def _remove_action(self, action):
1470 super(_ArgumentGroup, self)._remove_action(action)
1471 self._group_actions.remove(action)
1474 class _MutuallyExclusiveGroup(_ArgumentGroup):
1476 def __init__(self, container, required=False):
1477 super(_MutuallyExclusiveGroup, self).__init__(container)
1478 self.required = required
1479 self._container = container
1481 def _add_action(self, action):
1483 msg = _('mutually exclusive arguments must be optional')
1484 raise ValueError(msg)
1485 action = self._container._add_action(action)
1486 self._group_actions.append(action)
1489 def _remove_action(self, action):
1490 self._container._remove_action(action)
1491 self._group_actions.remove(action)
1494 class ArgumentParser(_AttributeHolder, _ActionsContainer):
1495 """Object for parsing command line strings into Python objects.
1498 - prog -- The name of the program (default: sys.argv[0])
1499 - usage -- A usage message (default: auto-generated from arguments)
1500 - description -- A description of what the program does
1501 - epilog -- Text following the argument descriptions
1502 - parents -- Parsers whose arguments should be copied into this one
1503 - formatter_class -- HelpFormatter class for printing help messages
1504 - prefix_chars -- Characters that prefix optional arguments
1505 - fromfile_prefix_chars -- Characters that prefix files containing
1506 additional arguments
1507 - argument_default -- The default value for all arguments
1508 - conflict_handler -- String indicating how to handle conflicts
1509 - add_help -- Add a -h/-help option
1519 formatter_class=HelpFormatter,
1521 fromfile_prefix_chars=None,
1522 argument_default=None,
1523 conflict_handler='error',
1526 if version is not None:
1529 """The "version" argument to ArgumentParser is deprecated. """
1531 """"add_argument(..., action='version', version="N", ...)" """
1532 """instead""", DeprecationWarning)
1534 superinit = super(ArgumentParser, self).__init__
1535 superinit(description=description,
1536 prefix_chars=prefix_chars,
1537 argument_default=argument_default,
1538 conflict_handler=conflict_handler)
1540 # default setting for prog
1542 prog = _os.path.basename(_sys.argv[0])
1546 self.epilog = epilog
1547 self.version = version
1548 self.formatter_class = formatter_class
1549 self.fromfile_prefix_chars = fromfile_prefix_chars
1550 self.add_help = add_help
1552 add_group = self.add_argument_group
1553 self._positionals = add_group(_('positional arguments'))
1554 self._optionals = add_group(_('optional arguments'))
1555 self._subparsers = None
1558 def identity(string):
1560 self.register('type', None, identity)
1562 # add help and version arguments if necessary
1563 # (using explicit default to override global argument_default)
1564 default_prefix = '-' if '-' in prefix_chars else prefix_chars[0]
1567 default_prefix+'h', default_prefix*2+'help',
1568 action='help', default=SUPPRESS,
1569 help=_('show this help message and exit'))
1572 default_prefix+'v', default_prefix*2+'version',
1573 action='version', default=SUPPRESS,
1574 version=self.version,
1575 help=_("show program's version number and exit"))
1577 # add parent arguments and defaults
1578 for parent in parents:
1579 self._add_container_actions(parent)
1581 defaults = parent._defaults
1582 except AttributeError:
1585 self._defaults.update(defaults)
1587 # =======================
1588 # Pretty __repr__ methods
1589 # =======================
1590 def _get_kwargs(self):
1600 return [(name, getattr(self, name)) for name in names]
1602 # ==================================
1603 # Optional/Positional adding methods
1604 # ==================================
1605 def add_subparsers(self, **kwargs):
1606 if self._subparsers is not None:
1607 self.error(_('cannot have multiple subparser arguments'))
1609 # add the parser class to the arguments if it's not present
1610 kwargs.setdefault('parser_class', type(self))
1612 if 'title' in kwargs or 'description' in kwargs:
1613 title = _(kwargs.pop('title', 'subcommands'))
1614 description = _(kwargs.pop('description', None))
1615 self._subparsers = self.add_argument_group(title, description)
1617 self._subparsers = self._positionals
1619 # prog defaults to the usage message of this parser, skipping
1620 # optional arguments and with no "usage:" prefix
1621 if kwargs.get('prog') is None:
1622 formatter = self._get_formatter()
1623 positionals = self._get_positional_actions()
1624 groups = self._mutually_exclusive_groups
1625 formatter.add_usage(self.usage, positionals, groups, '')
1626 kwargs['prog'] = formatter.format_help().strip()
1628 # create the parsers action and add it to the positionals list
1629 parsers_class = self._pop_action_class(kwargs, 'parsers')
1630 action = parsers_class(option_strings=[], **kwargs)
1631 self._subparsers._add_action(action)
1633 # return the created parsers action
1636 def _add_action(self, action):
1637 if action.option_strings:
1638 self._optionals._add_action(action)
1640 self._positionals._add_action(action)
1643 def _get_optional_actions(self):
1645 for action in self._actions
1646 if action.option_strings]
1648 def _get_positional_actions(self):
1650 for action in self._actions
1651 if not action.option_strings]
1653 # =====================================
1654 # Command line argument parsing methods
1655 # =====================================
1656 def parse_args(self, args=None, namespace=None):
1657 args, argv = self.parse_known_args(args, namespace)
1659 msg = _('unrecognized arguments: %s')
1660 self.error(msg % ' '.join(argv))
1663 def parse_known_args(self, args=None, namespace=None):
1664 # args default to the system args
1666 args = _sys.argv[1:]
1668 # default Namespace built from parser defaults
1669 if namespace is None:
1670 namespace = Namespace()
1672 # add any action defaults that aren't present
1673 for action in self._actions:
1674 if action.dest is not SUPPRESS:
1675 if not hasattr(namespace, action.dest):
1676 if action.default is not SUPPRESS:
1677 default = action.default
1678 if isinstance(action.default, str):
1679 default = self._get_value(action, default)
1680 setattr(namespace, action.dest, default)
1682 # add any parser defaults that aren't present
1683 for dest in self._defaults:
1684 if not hasattr(namespace, dest):
1685 setattr(namespace, dest, self._defaults[dest])
1687 # parse the arguments and exit if there are any errors
1689 return self._parse_known_args(args, namespace)
1690 except ArgumentError:
1691 err = _sys.exc_info()[1]
1692 self.error(str(err))
1694 def _parse_known_args(self, arg_strings, namespace):
1695 # replace arg strings that are file references
1696 if self.fromfile_prefix_chars is not None:
1697 arg_strings = self._read_args_from_files(arg_strings)
1699 # map all mutually exclusive arguments to the other arguments
1700 # they can't occur with
1701 action_conflicts = {}
1702 for mutex_group in self._mutually_exclusive_groups:
1703 group_actions = mutex_group._group_actions
1704 for i, mutex_action in enumerate(mutex_group._group_actions):
1705 conflicts = action_conflicts.setdefault(mutex_action, [])
1706 conflicts.extend(group_actions[:i])
1707 conflicts.extend(group_actions[i + 1:])
1709 # find all option indices, and determine the arg_string_pattern
1710 # which has an 'O' if there is an option at an index,
1711 # an 'A' if there is an argument, or a '-' if there is a '--'
1712 option_string_indices = {}
1713 arg_string_pattern_parts = []
1714 arg_strings_iter = iter(arg_strings)
1715 for i, arg_string in enumerate(arg_strings_iter):
1717 # all args after -- are non-options
1718 if arg_string == '--':
1719 arg_string_pattern_parts.append('-')
1720 for arg_string in arg_strings_iter:
1721 arg_string_pattern_parts.append('A')
1723 # otherwise, add the arg to the arg strings
1724 # and note the index if it was an option
1726 option_tuple = self._parse_optional(arg_string)
1727 if option_tuple is None:
1730 option_string_indices[i] = option_tuple
1732 arg_string_pattern_parts.append(pattern)
1734 # join the pieces together to form the pattern
1735 arg_strings_pattern = ''.join(arg_string_pattern_parts)
1737 # converts arg strings to the appropriate and then takes the action
1738 seen_actions = set()
1739 seen_non_default_actions = set()
1741 def take_action(action, argument_strings, option_string=None):
1742 seen_actions.add(action)
1743 argument_values = self._get_values(action, argument_strings)
1745 # error if this argument is not allowed with other previously
1746 # seen arguments, assuming that actions that use the default
1747 # value don't really count as "present"
1748 if argument_values is not action.default:
1749 seen_non_default_actions.add(action)
1750 for conflict_action in action_conflicts.get(action, []):
1751 if conflict_action in seen_non_default_actions:
1752 msg = _('not allowed with argument %s')
1753 action_name = _get_action_name(conflict_action)
1754 raise ArgumentError(action, msg % action_name)
1756 # take the action if we didn't receive a SUPPRESS value
1757 # (e.g. from a default)
1758 if argument_values is not SUPPRESS:
1759 action(self, namespace, argument_values, option_string)
1761 # function to convert arg_strings into an optional action
1762 def consume_optional(start_index):
1764 # get the optional identified at this index
1765 option_tuple = option_string_indices[start_index]
1766 action, option_string, explicit_arg = option_tuple
1768 # identify additional optionals in the same arg string
1769 # (e.g. -xyz is the same as -x -y -z if no args are required)
1770 match_argument = self._match_argument
1774 # if we found no optional action, skip it
1776 extras.append(arg_strings[start_index])
1777 return start_index + 1
1779 # if there is an explicit argument, try to match the
1780 # optional's string arguments to only this
1781 if explicit_arg is not None:
1782 arg_count = match_argument(action, 'A')
1784 # if the action is a single-dash option and takes no
1785 # arguments, try to parse more single-dash options out
1786 # of the tail of the option string
1787 chars = self.prefix_chars
1788 if arg_count == 0 and option_string[1] not in chars:
1789 action_tuples.append((action, [], option_string))
1790 for char in self.prefix_chars:
1791 option_string = char + explicit_arg[0]
1792 explicit_arg = explicit_arg[1:] or None
1793 optionals_map = self._option_string_actions
1794 if option_string in optionals_map:
1795 action = optionals_map[option_string]
1798 msg = _('ignored explicit argument %r')
1799 raise ArgumentError(action, msg % explicit_arg)
1801 # if the action expect exactly one argument, we've
1802 # successfully matched the option; exit the loop
1803 elif arg_count == 1:
1804 stop = start_index + 1
1805 args = [explicit_arg]
1806 action_tuples.append((action, args, option_string))
1809 # error if a double-dash option did not use the
1812 msg = _('ignored explicit argument %r')
1813 raise ArgumentError(action, msg % explicit_arg)
1815 # if there is no explicit argument, try to match the
1816 # optional's string arguments with the following strings
1817 # if successful, exit the loop
1819 start = start_index + 1
1820 selected_patterns = arg_strings_pattern[start:]
1821 arg_count = match_argument(action, selected_patterns)
1822 stop = start + arg_count
1823 args = arg_strings[start:stop]
1824 action_tuples.append((action, args, option_string))
1827 # add the Optional to the list and return the index at which
1828 # the Optional's string args stopped
1829 assert action_tuples
1830 for action, args, option_string in action_tuples:
1831 take_action(action, args, option_string)
1834 # the list of Positionals left to be parsed; this is modified
1835 # by consume_positionals()
1836 positionals = self._get_positional_actions()
1838 # function to convert arg_strings into positional actions
1839 def consume_positionals(start_index):
1840 # match as many Positionals as possible
1841 match_partial = self._match_arguments_partial
1842 selected_pattern = arg_strings_pattern[start_index:]
1843 arg_counts = match_partial(positionals, selected_pattern)
1845 # slice off the appropriate arg strings for each Positional
1846 # and add the Positional and its args to the list
1847 for action, arg_count in zip(positionals, arg_counts):
1848 args = arg_strings[start_index: start_index + arg_count]
1849 start_index += arg_count
1850 take_action(action, args)
1852 # slice off the Positionals that we just parsed and return the
1853 # index at which the Positionals' string args stopped
1854 positionals[:] = positionals[len(arg_counts):]
1857 # consume Positionals and Optionals alternately, until we have
1858 # passed the last option string
1861 if option_string_indices:
1862 max_option_string_index = max(option_string_indices)
1864 max_option_string_index = -1
1865 while start_index <= max_option_string_index:
1867 # consume any Positionals preceding the next option
1868 next_option_string_index = min([
1870 for index in option_string_indices
1871 if index >= start_index])
1872 if start_index != next_option_string_index:
1873 positionals_end_index = consume_positionals(start_index)
1875 # only try to parse the next optional if we didn't consume
1876 # the option string during the positionals parsing
1877 if positionals_end_index > start_index:
1878 start_index = positionals_end_index
1881 start_index = positionals_end_index
1883 # if we consumed all the positionals we could and we're not
1884 # at the index of an option string, there were extra arguments
1885 if start_index not in option_string_indices:
1886 strings = arg_strings[start_index:next_option_string_index]
1887 extras.extend(strings)
1888 start_index = next_option_string_index
1890 # consume the next optional and any arguments for it
1891 start_index = consume_optional(start_index)
1893 # consume any positionals following the last Optional
1894 stop_index = consume_positionals(start_index)
1896 # if we didn't consume all the argument strings, there were extras
1897 extras.extend(arg_strings[stop_index:])
1899 # if we didn't use all the Positional objects, there were too few
1900 # arg strings supplied.
1902 self.error(_('too few arguments'))
1904 # make sure all required actions were present
1905 for action in self._actions:
1907 if action not in seen_actions:
1908 name = _get_action_name(action)
1909 self.error(_('argument %s is required') % name)
1911 # make sure all required groups had one option present
1912 for group in self._mutually_exclusive_groups:
1914 for action in group._group_actions:
1915 if action in seen_non_default_actions:
1918 # if no actions were used, report the error
1920 names = [_get_action_name(action)
1921 for action in group._group_actions
1922 if action.help is not SUPPRESS]
1923 msg = _('one of the arguments %s is required')
1924 self.error(msg % ' '.join(names))
1926 # return the updated namespace and the extra arguments
1927 return namespace, extras
1929 def _read_args_from_files(self, arg_strings):
1930 # expand arguments referencing files
1931 new_arg_strings = []
1932 for arg_string in arg_strings:
1934 # for regular arguments, just add them back into the list
1935 if arg_string[0] not in self.fromfile_prefix_chars:
1936 new_arg_strings.append(arg_string)
1938 # replace arguments referencing files with the file content
1941 args_file = open(arg_string[1:])
1944 for arg_line in args_file.read().splitlines():
1945 for arg in self.convert_arg_line_to_args(arg_line):
1946 arg_strings.append(arg)
1947 arg_strings = self._read_args_from_files(arg_strings)
1948 new_arg_strings.extend(arg_strings)
1952 err = _sys.exc_info()[1]
1953 self.error(str(err))
1955 # return the modified argument list
1956 return new_arg_strings
1958 def convert_arg_line_to_args(self, arg_line):
1961 def _match_argument(self, action, arg_strings_pattern):
1962 # match the pattern for this action to the arg strings
1963 nargs_pattern = self._get_nargs_pattern(action)
1964 match = _re.match(nargs_pattern, arg_strings_pattern)
1966 # raise an exception if we weren't able to find a match
1969 None: _('expected one argument'),
1970 OPTIONAL: _('expected at most one argument'),
1971 ONE_OR_MORE: _('expected at least one argument'),
1973 default = _('expected %s argument(s)') % action.nargs
1974 msg = nargs_errors.get(action.nargs, default)
1975 raise ArgumentError(action, msg)
1977 # return the number of arguments matched
1978 return len(match.group(1))
1980 def _match_arguments_partial(self, actions, arg_strings_pattern):
1981 # progressively shorten the actions list by slicing off the
1982 # final actions until we find a match
1984 for i in range(len(actions), 0, -1):
1985 actions_slice = actions[:i]
1986 pattern = ''.join([self._get_nargs_pattern(action)
1987 for action in actions_slice])
1988 match = _re.match(pattern, arg_strings_pattern)
1989 if match is not None:
1990 result.extend([len(string) for string in match.groups()])
1993 # return the list of arg string counts
1996 def _parse_optional(self, arg_string):
1997 # if it's an empty string, it was meant to be a positional
2001 # if it doesn't start with a prefix, it was meant to be positional
2002 if not arg_string[0] in self.prefix_chars:
2005 # if the option string is present in the parser, return the action
2006 if arg_string in self._option_string_actions:
2007 action = self._option_string_actions[arg_string]
2008 return action, arg_string, None
2010 # if it's just a single character, it was meant to be positional
2011 if len(arg_string) == 1:
2014 # if the option string before the "=" is present, return the action
2015 if '=' in arg_string:
2016 option_string, explicit_arg = arg_string.split('=', 1)
2017 if option_string in self._option_string_actions:
2018 action = self._option_string_actions[option_string]
2019 return action, option_string, explicit_arg
2021 # search through all possible prefixes of the option string
2022 # and all actions in the parser for possible interpretations
2023 option_tuples = self._get_option_tuples(arg_string)
2025 # if multiple actions match, the option string was ambiguous
2026 if len(option_tuples) > 1:
2027 options = ', '.join([option_string
2028 for action, option_string, explicit_arg in option_tuples])
2029 tup = arg_string, options
2030 self.error(_('ambiguous option: %s could match %s') % tup)
2032 # if exactly one action matched, this segmentation is good,
2033 # so return the parsed action
2034 elif len(option_tuples) == 1:
2035 option_tuple, = option_tuples
2038 # if it was not found as an option, but it looks like a negative
2039 # number, it was meant to be positional
2040 # unless there are negative-number-like options
2041 if self._negative_number_matcher.match(arg_string):
2042 if not self._has_negative_number_optionals:
2045 # if it contains a space, it was meant to be a positional
2046 if ' ' in arg_string:
2049 # it was meant to be an optional but there is no such option
2050 # in this parser (though it might be a valid option in a subparser)
2051 return None, arg_string, None
2053 def _get_option_tuples(self, option_string):
2056 # option strings starting with two prefix characters are only
2058 chars = self.prefix_chars
2059 if option_string[0] in chars and option_string[1] in chars:
2060 if '=' in option_string:
2061 option_prefix, explicit_arg = option_string.split('=', 1)
2063 option_prefix = option_string
2065 for option_string in self._option_string_actions:
2066 if option_string.startswith(option_prefix):
2067 action = self._option_string_actions[option_string]
2068 tup = action, option_string, explicit_arg
2071 # single character options can be concatenated with their arguments
2072 # but multiple character options always have to have their argument
2074 elif option_string[0] in chars and option_string[1] not in chars:
2075 option_prefix = option_string
2077 short_option_prefix = option_string[:2]
2078 short_explicit_arg = option_string[2:]
2080 for option_string in self._option_string_actions:
2081 if option_string == short_option_prefix:
2082 action = self._option_string_actions[option_string]
2083 tup = action, option_string, short_explicit_arg
2085 elif option_string.startswith(option_prefix):
2086 action = self._option_string_actions[option_string]
2087 tup = action, option_string, explicit_arg
2090 # shouldn't ever get here
2092 self.error(_('unexpected option string: %s') % option_string)
2094 # return the collected option tuples
2097 def _get_nargs_pattern(self, action):
2098 # in all examples below, we have to allow for '--' args
2099 # which are represented as '-' in the pattern
2100 nargs = action.nargs
2102 # the default (None) is assumed to be a single argument
2104 nargs_pattern = '(-*A-*)'
2106 # allow zero or one arguments
2107 elif nargs == OPTIONAL:
2108 nargs_pattern = '(-*A?-*)'
2110 # allow zero or more arguments
2111 elif nargs == ZERO_OR_MORE:
2112 nargs_pattern = '(-*[A-]*)'
2114 # allow one or more arguments
2115 elif nargs == ONE_OR_MORE:
2116 nargs_pattern = '(-*A[A-]*)'
2118 # allow any number of options or arguments
2119 elif nargs == REMAINDER:
2120 nargs_pattern = '([-AO]*)'
2122 # allow one argument followed by any number of options or arguments
2123 elif nargs == PARSER:
2124 nargs_pattern = '(-*A[-AO]*)'
2126 # all others should be integers
2128 nargs_pattern = '(-*%s-*)' % '-*'.join('A' * nargs)
2130 # if this is an optional action, -- is not allowed
2131 if action.option_strings:
2132 nargs_pattern = nargs_pattern.replace('-*', '')
2133 nargs_pattern = nargs_pattern.replace('-', '')
2135 # return the pattern
2136 return nargs_pattern
2138 # ========================
2139 # Value conversion methods
2140 # ========================
2141 def _get_values(self, action, arg_strings):
2142 # for everything but PARSER args, strip out '--'
2143 if action.nargs not in [PARSER, REMAINDER]:
2144 arg_strings = [s for s in arg_strings if s != '--']
2146 # optional argument produces a default when not present
2147 if not arg_strings and action.nargs == OPTIONAL:
2148 if action.option_strings:
2149 value = action.const
2151 value = action.default
2152 if isinstance(value, str):
2153 value = self._get_value(action, value)
2154 self._check_value(action, value)
2156 # when nargs='*' on a positional, if there were no command-line
2157 # args, use the default if it is anything other than None
2158 elif (not arg_strings and action.nargs == ZERO_OR_MORE and
2159 not action.option_strings):
2160 if action.default is not None:
2161 value = action.default
2164 self._check_value(action, value)
2166 # single argument or optional argument produces a single value
2167 elif len(arg_strings) == 1 and action.nargs in [None, OPTIONAL]:
2168 arg_string, = arg_strings
2169 value = self._get_value(action, arg_string)
2170 self._check_value(action, value)
2172 # REMAINDER arguments convert all values, checking none
2173 elif action.nargs == REMAINDER:
2174 value = [self._get_value(action, v) for v in arg_strings]
2176 # PARSER arguments convert all values, but check only the first
2177 elif action.nargs == PARSER:
2178 value = [self._get_value(action, v) for v in arg_strings]
2179 self._check_value(action, value[0])
2181 # all other types of nargs produce a list
2183 value = [self._get_value(action, v) for v in arg_strings]
2185 self._check_value(action, v)
2187 # return the converted value
2190 def _get_value(self, action, arg_string):
2191 type_func = self._registry_get('type', action.type, action.type)
2192 if not _callable(type_func):
2193 msg = _('%r is not callable')
2194 raise ArgumentError(action, msg % type_func)
2196 # convert the value to the appropriate type
2198 result = type_func(arg_string)
2200 # ArgumentTypeErrors indicate errors
2201 except ArgumentTypeError:
2202 name = getattr(action.type, '__name__', repr(action.type))
2203 msg = str(_sys.exc_info()[1])
2204 raise ArgumentError(action, msg)
2206 # TypeErrors or ValueErrors also indicate errors
2207 except (TypeError, ValueError):
2208 name = getattr(action.type, '__name__', repr(action.type))
2209 msg = _('invalid %s value: %r')
2210 raise ArgumentError(action, msg % (name, arg_string))
2212 # return the converted value
2215 def _check_value(self, action, value):
2216 # converted value must be one of the choices (if specified)
2217 if action.choices is not None and value not in action.choices:
2218 tup = value, ', '.join(map(repr, action.choices))
2219 msg = _('invalid choice: %r (choose from %s)') % tup
2220 raise ArgumentError(action, msg)
2222 # =======================
2223 # Help-formatting methods
2224 # =======================
2225 def format_usage(self):
2226 formatter = self._get_formatter()
2227 formatter.add_usage(self.usage, self._actions,
2228 self._mutually_exclusive_groups)
2229 return formatter.format_help()
2231 def format_help(self):
2232 formatter = self._get_formatter()
2235 formatter.add_usage(self.usage, self._actions,
2236 self._mutually_exclusive_groups)
2239 formatter.add_text(self.description)
2241 # positionals, optionals and user-defined groups
2242 for action_group in self._action_groups:
2243 formatter.start_section(action_group.title)
2244 formatter.add_text(action_group.description)
2245 formatter.add_arguments(action_group._group_actions)
2246 formatter.end_section()
2249 formatter.add_text(self.epilog)
2251 # determine help from format above
2252 return formatter.format_help()
2254 def format_version(self):
2257 'The format_version method is deprecated -- the "version" '
2258 'argument to ArgumentParser is no longer supported.',
2260 formatter = self._get_formatter()
2261 formatter.add_text(self.version)
2262 return formatter.format_help()
2264 def _get_formatter(self):
2265 return self.formatter_class(prog=self.prog)
2267 # =====================
2268 # Help-printing methods
2269 # =====================
2270 def print_usage(self, file=None):
2273 self._print_message(self.format_usage(), file)
2275 def print_help(self, file=None):
2278 self._print_message(self.format_help(), file)
2280 def print_version(self, file=None):
2283 'The print_version method is deprecated -- the "version" '
2284 'argument to ArgumentParser is no longer supported.',
2286 self._print_message(self.format_version(), file)
2288 def _print_message(self, message, file=None):
2297 def exit(self, status=0, message=None):
2299 self._print_message(message, _sys.stderr)
2302 def error(self, message):
2303 """error(message: string)
2305 Prints a usage message incorporating the message to stderr and
2308 If you override this in a subclass, it should not return -- it
2309 should either exit or raise an exception.
2311 self.print_usage(_sys.stderr)
2312 self.exit(2, _('%s: error: %s\n') % (self.prog, message))