Context Navigation

source: flexpart.git/flexpart-testing/check/argparse.py @ dfb516e

FPv9.3.1FPv9.3.2fp9.3.1-20161214-nc4grib2nc4_repair

Last change on this file since dfb516e was dfb516e, checked in by Don Morton <Don.Morton@…>, 8 years ago
Minor additions to FPv9.3.1 testing and compilation environments
Property mode set to `100644`
File size: 87.0 KB

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

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

Download in other formats: