Context Navigation

argparse.py

Last change on this file was 391, checked in by dmik, 11 years ago
python: Merge vendor 2.7.6 to trunk.
Property svn:eol-style set to `native`
File size: 86.5 KB

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

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: python/trunk/Lib/argparse.py

Download in other formats: