Python code coverage for Lib/distutils/fancy_getopt.py

#	count	content
1	n/a	"""distutils.fancy_getopt
2	n/a
3	n/a	Wrapper around the standard getopt module that provides the following
4	n/a	additional features:
5	n/a	* short and long options are tied together
6	n/a	* options have help strings, so fancy_getopt could potentially
7	n/a	create a complete usage summary
8	n/a	* options set attributes of a passed-in object
9	n/a	"""
10	n/a
11	n/a	import sys, string, re
12	n/a	import getopt
13	n/a	from distutils.errors import *
14	n/a
15	n/a	# Much like command_re in distutils.core, this is close to but not quite
16	n/a	# the same as a Python NAME -- except, in the spirit of most GNU
17	n/a	# utilities, we use '-' in place of '_'. (The spirit of LISP lives on!)
18	n/a	# The similarities to NAME are again not a coincidence...
19	n/a	longopt_pat = r'[a-zA-Z](?:[a-zA-Z0-9-]*)'
20	n/a	longopt_re = re.compile(r'^%s$' % longopt_pat)
21	n/a
22	n/a	# For recognizing "negative alias" options, eg. "quiet=!verbose"
23	n/a	neg_alias_re = re.compile("^(%s)=!(%s)$" % (longopt_pat, longopt_pat))
24	n/a
25	n/a	# This is used to translate long options to legitimate Python identifiers
26	n/a	# (for use as attributes of some object).
27	n/a	longopt_xlate = str.maketrans('-', '_')
28	n/a
29	n/a	class FancyGetopt:
30	n/a	"""Wrapper around the standard 'getopt()' module that provides some
31	n/a	handy extra functionality:
32	n/a	* short and long options are tied together
33	n/a	* options have help strings, and help text can be assembled
34	n/a	from them
35	n/a	* options set attributes of a passed-in object
36	n/a	* boolean options can have "negative aliases" -- eg. if
37	n/a	--quiet is the "negative alias" of --verbose, then "--quiet"
38	n/a	on the command line sets 'verbose' to false
39	n/a	"""
40	n/a
41	n/a	def __init__(self, option_table=None):
42	n/a	# The option table is (currently) a list of tuples. The
43	n/a	# tuples may have 3 or four values:
44	n/a	# (long_option, short_option, help_string [, repeatable])
45	n/a	# if an option takes an argument, its long_option should have '='
46	n/a	# appended; short_option should just be a single character, no ':'
47	n/a	# in any case. If a long_option doesn't have a corresponding
48	n/a	# short_option, short_option should be None. All option tuples
49	n/a	# must have long options.
50	n/a	self.option_table = option_table
51	n/a
52	n/a	# 'option_index' maps long option names to entries in the option
53	n/a	# table (ie. those 3-tuples).
54	n/a	self.option_index = {}
55	n/a	if self.option_table:
56	n/a	self._build_index()
57	n/a
58	n/a	# 'alias' records (duh) alias options; {'foo': 'bar'} means
59	n/a	# --foo is an alias for --bar
60	n/a	self.alias = {}
61	n/a
62	n/a	# 'negative_alias' keeps track of options that are the boolean
63	n/a	# opposite of some other option
64	n/a	self.negative_alias = {}
65	n/a
66	n/a	# These keep track of the information in the option table. We
67	n/a	# don't actually populate these structures until we're ready to
68	n/a	# parse the command-line, since the 'option_table' passed in here
69	n/a	# isn't necessarily the final word.
70	n/a	self.short_opts = []
71	n/a	self.long_opts = []
72	n/a	self.short2long = {}
73	n/a	self.attr_name = {}
74	n/a	self.takes_arg = {}
75	n/a
76	n/a	# And 'option_order' is filled up in 'getopt()'; it records the
77	n/a	# original order of options (and their values) on the command-line,
78	n/a	# but expands short options, converts aliases, etc.
79	n/a	self.option_order = []
80	n/a
81	n/a	def _build_index(self):
82	n/a	self.option_index.clear()
83	n/a	for option in self.option_table:
84	n/a	self.option_index[option[0]] = option
85	n/a
86	n/a	def set_option_table(self, option_table):
87	n/a	self.option_table = option_table
88	n/a	self._build_index()
89	n/a
90	n/a	def add_option(self, long_option, short_option=None, help_string=None):
91	n/a	if long_option in self.option_index:
92	n/a	raise DistutilsGetoptError(
93	n/a	"option conflict: already an option '%s'" % long_option)
94	n/a	else:
95	n/a	option = (long_option, short_option, help_string)
96	n/a	self.option_table.append(option)
97	n/a	self.option_index[long_option] = option
98	n/a
99	n/a	def has_option(self, long_option):
100	n/a	"""Return true if the option table for this parser has an
101	n/a	option with long name 'long_option'."""
102	n/a	return long_option in self.option_index
103	n/a
104	n/a	def get_attr_name(self, long_option):
105	n/a	"""Translate long option name 'long_option' to the form it
106	n/a	has as an attribute of some object: ie., translate hyphens
107	n/a	to underscores."""
108	n/a	return long_option.translate(longopt_xlate)
109	n/a
110	n/a	def _check_alias_dict(self, aliases, what):
111	n/a	assert isinstance(aliases, dict)
112	n/a	for (alias, opt) in aliases.items():
113	n/a	if alias not in self.option_index:
114	n/a	raise DistutilsGetoptError(("invalid %s '%s': "
115	n/a	"option '%s' not defined") % (what, alias, alias))
116	n/a	if opt not in self.option_index:
117	n/a	raise DistutilsGetoptError(("invalid %s '%s': "
118	n/a	"aliased option '%s' not defined") % (what, alias, opt))
119	n/a
120	n/a	def set_aliases(self, alias):
121	n/a	"""Set the aliases for this option parser."""
122	n/a	self._check_alias_dict(alias, "alias")
123	n/a	self.alias = alias
124	n/a
125	n/a	def set_negative_aliases(self, negative_alias):
126	n/a	"""Set the negative aliases for this option parser.
127	n/a	'negative_alias' should be a dictionary mapping option names to
128	n/a	option names, both the key and value must already be defined
129	n/a	in the option table."""
130	n/a	self._check_alias_dict(negative_alias, "negative alias")
131	n/a	self.negative_alias = negative_alias
132	n/a
133	n/a	def _grok_option_table(self):
134	n/a	"""Populate the various data structures that keep tabs on the
135	n/a	option table. Called by 'getopt()' before it can do anything
136	n/a	worthwhile.
137	n/a	"""
138	n/a	self.long_opts = []
139	n/a	self.short_opts = []
140	n/a	self.short2long.clear()
141	n/a	self.repeat = {}
142	n/a
143	n/a	for option in self.option_table:
144	n/a	if len(option) == 3:
145	n/a	long, short, help = option
146	n/a	repeat = 0
147	n/a	elif len(option) == 4:
148	n/a	long, short, help, repeat = option
149	n/a	else:
150	n/a	# the option table is part of the code, so simply
151	n/a	# assert that it is correct
152	n/a	raise ValueError("invalid option tuple: %r" % (option,))
153	n/a
154	n/a	# Type- and value-check the option names
155	n/a	if not isinstance(long, str) or len(long) < 2:
156	n/a	raise DistutilsGetoptError(("invalid long option '%s': "
157	n/a	"must be a string of length >= 2") % long)
158	n/a
159	n/a	if (not ((short is None) or
160	n/a	(isinstance(short, str) and len(short) == 1))):
161	n/a	raise DistutilsGetoptError("invalid short option '%s': "
162	n/a	"must a single character or None" % short)
163	n/a
164	n/a	self.repeat[long] = repeat
165	n/a	self.long_opts.append(long)
166	n/a
167	n/a	if long[-1] == '=': # option takes an argument?
168	n/a	if short: short = short + ':'
169	n/a	long = long[0:-1]
170	n/a	self.takes_arg[long] = 1
171	n/a	else:
172	n/a	# Is option is a "negative alias" for some other option (eg.
173	n/a	# "quiet" == "!verbose")?
174	n/a	alias_to = self.negative_alias.get(long)
175	n/a	if alias_to is not None:
176	n/a	if self.takes_arg[alias_to]:
177	n/a	raise DistutilsGetoptError(
178	n/a	"invalid negative alias '%s': "
179	n/a	"aliased option '%s' takes a value"
180	n/a	% (long, alias_to))
181	n/a
182	n/a	self.long_opts[-1] = long # XXX redundant?!
183	n/a	self.takes_arg[long] = 0
184	n/a
185	n/a	# If this is an alias option, make sure its "takes arg" flag is
186	n/a	# the same as the option it's aliased to.
187	n/a	alias_to = self.alias.get(long)
188	n/a	if alias_to is not None:
189	n/a	if self.takes_arg[long] != self.takes_arg[alias_to]:
190	n/a	raise DistutilsGetoptError(
191	n/a	"invalid alias '%s': inconsistent with "
192	n/a	"aliased option '%s' (one of them takes a value, "
193	n/a	"the other doesn't"
194	n/a	% (long, alias_to))
195	n/a
196	n/a	# Now enforce some bondage on the long option name, so we can
197	n/a	# later translate it to an attribute name on some object. Have
198	n/a	# to do this a bit late to make sure we've removed any trailing
199	n/a	# '='.
200	n/a	if not longopt_re.match(long):
201	n/a	raise DistutilsGetoptError(
202	n/a	"invalid long option name '%s' "
203	n/a	"(must be letters, numbers, hyphens only" % long)
204	n/a
205	n/a	self.attr_name[long] = self.get_attr_name(long)
206	n/a	if short:
207	n/a	self.short_opts.append(short)
208	n/a	self.short2long[short[0]] = long
209	n/a
210	n/a	def getopt(self, args=None, object=None):
211	n/a	"""Parse command-line options in args. Store as attributes on object.
212	n/a
213	n/a	If 'args' is None or not supplied, uses 'sys.argv[1:]'. If
214	n/a	'object' is None or not supplied, creates a new OptionDummy
215	n/a	object, stores option values there, and returns a tuple (args,
216	n/a	object). If 'object' is supplied, it is modified in place and
217	n/a	'getopt()' just returns 'args'; in both cases, the returned
218	n/a	'args' is a modified copy of the passed-in 'args' list, which
219	n/a	is left untouched.
220	n/a	"""
221	n/a	if args is None:
222	n/a	args = sys.argv[1:]
223	n/a	if object is None:
224	n/a	object = OptionDummy()
225	n/a	created_object = True
226	n/a	else:
227	n/a	created_object = False
228	n/a
229	n/a	self._grok_option_table()
230	n/a
231	n/a	short_opts = ' '.join(self.short_opts)
232	n/a	try:
233	n/a	opts, args = getopt.getopt(args, short_opts, self.long_opts)
234	n/a	except getopt.error as msg:
235	n/a	raise DistutilsArgError(msg)
236	n/a
237	n/a	for opt, val in opts:
238	n/a	if len(opt) == 2 and opt[0] == '-': # it's a short option
239	n/a	opt = self.short2long[opt[1]]
240	n/a	else:
241	n/a	assert len(opt) > 2 and opt[:2] == '--'
242	n/a	opt = opt[2:]
243	n/a
244	n/a	alias = self.alias.get(opt)
245	n/a	if alias:
246	n/a	opt = alias
247	n/a
248	n/a	if not self.takes_arg[opt]: # boolean option?
249	n/a	assert val == '', "boolean option can't have value"
250	n/a	alias = self.negative_alias.get(opt)
251	n/a	if alias:
252	n/a	opt = alias
253	n/a	val = 0
254	n/a	else:
255	n/a	val = 1
256	n/a
257	n/a	attr = self.attr_name[opt]
258	n/a	# The only repeating option at the moment is 'verbose'.
259	n/a	# It has a negative option -q quiet, which should set verbose = 0.
260	n/a	if val and self.repeat.get(attr) is not None:
261	n/a	val = getattr(object, attr, 0) + 1
262	n/a	setattr(object, attr, val)
263	n/a	self.option_order.append((opt, val))
264	n/a
265	n/a	# for opts
266	n/a	if created_object:
267	n/a	return args, object
268	n/a	else:
269	n/a	return args
270	n/a
271	n/a	def get_option_order(self):
272	n/a	"""Returns the list of (option, value) tuples processed by the
273	n/a	previous run of 'getopt()'. Raises RuntimeError if
274	n/a	'getopt()' hasn't been called yet.
275	n/a	"""
276	n/a	if self.option_order is None:
277	n/a	raise RuntimeError("'getopt()' hasn't been called yet")
278	n/a	else:
279	n/a	return self.option_order
280	n/a
281	n/a	def generate_help(self, header=None):
282	n/a	"""Generate help text (a list of strings, one per suggested line of
283	n/a	output) from the option table for this FancyGetopt object.
284	n/a	"""
285	n/a	# Blithely assume the option table is good: probably wouldn't call
286	n/a	# 'generate_help()' unless you've already called 'getopt()'.
287	n/a
288	n/a	# First pass: determine maximum length of long option names
289	n/a	max_opt = 0
290	n/a	for option in self.option_table:
291	n/a	long = option[0]
292	n/a	short = option[1]
293	n/a	l = len(long)
294	n/a	if long[-1] == '=':
295	n/a	l = l - 1
296	n/a	if short is not None:
297	n/a	l = l + 5 # " (-x)" where short == 'x'
298	n/a	if l > max_opt:
299	n/a	max_opt = l
300	n/a
301	n/a	opt_width = max_opt + 2 + 2 + 2 # room for indent + dashes + gutter
302	n/a
303	n/a	# Typical help block looks like this:
304	n/a	# --foo controls foonabulation
305	n/a	# Help block for longest option looks like this:
306	n/a	# --flimflam set the flim-flam level
307	n/a	# and with wrapped text:
308	n/a	# --flimflam set the flim-flam level (must be between
309	n/a	# 0 and 100, except on Tuesdays)
310	n/a	# Options with short names will have the short name shown (but
311	n/a	# it doesn't contribute to max_opt):
312	n/a	# --foo (-f) controls foonabulation
313	n/a	# If adding the short option would make the left column too wide,
314	n/a	# we push the explanation off to the next line
315	n/a	# --flimflam (-l)
316	n/a	# set the flim-flam level
317	n/a	# Important parameters:
318	n/a	# - 2 spaces before option block start lines
319	n/a	# - 2 dashes for each long option name
320	n/a	# - min. 2 spaces between option and explanation (gutter)
321	n/a	# - 5 characters (incl. space) for short option name
322	n/a
323	n/a	# Now generate lines of help text. (If 80 columns were good enough
324	n/a	# for Jesus, then 78 columns are good enough for me!)
325	n/a	line_width = 78
326	n/a	text_width = line_width - opt_width
327	n/a	big_indent = ' ' * opt_width
328	n/a	if header:
329	n/a	lines = [header]
330	n/a	else:
331	n/a	lines = ['Option summary:']
332	n/a
333	n/a	for option in self.option_table:
334	n/a	long, short, help = option[:3]
335	n/a	text = wrap_text(help, text_width)
336	n/a	if long[-1] == '=':
337	n/a	long = long[0:-1]
338	n/a
339	n/a	# Case 1: no short option at all (makes life easy)
340	n/a	if short is None:
341	n/a	if text:
342	n/a	lines.append(" --%-*s %s" % (max_opt, long, text[0]))
343	n/a	else:
344	n/a	lines.append(" --%-*s " % (max_opt, long))
345	n/a
346	n/a	# Case 2: we have a short option, so we have to include it
347	n/a	# just after the long option
348	n/a	else:
349	n/a	opt_names = "%s (-%s)" % (long, short)
350	n/a	if text:
351	n/a	lines.append(" --%-*s %s" %
352	n/a	(max_opt, opt_names, text[0]))
353	n/a	else:
354	n/a	lines.append(" --%-*s" % opt_names)
355	n/a
356	n/a	for l in text[1:]:
357	n/a	lines.append(big_indent + l)
358	n/a	return lines
359	n/a
360	n/a	def print_help(self, header=None, file=None):
361	n/a	if file is None:
362	n/a	file = sys.stdout
363	n/a	for line in self.generate_help(header):
364	n/a	file.write(line + "\n")
365	n/a
366	n/a
367	n/a	def fancy_getopt(options, negative_opt, object, args):
368	n/a	parser = FancyGetopt(options)
369	n/a	parser.set_negative_aliases(negative_opt)
370	n/a	return parser.getopt(args, object)
371	n/a
372	n/a
373	n/a	WS_TRANS = {ord(_wschar) : ' ' for _wschar in string.whitespace}
374	n/a
375	n/a	def wrap_text(text, width):
376	n/a	"""wrap_text(text : string, width : int) -> [string]
377	n/a
378	n/a	Split 'text' into multiple lines of no more than 'width' characters
379	n/a	each, and return the list of strings that results.
380	n/a	"""
381	n/a	if text is None:
382	n/a	return []
383	n/a	if len(text) <= width:
384	n/a	return [text]
385	n/a
386	n/a	text = text.expandtabs()
387	n/a	text = text.translate(WS_TRANS)
388	n/a	chunks = re.split(r'( +\|-+)', text)
389	n/a	chunks = [ch for ch in chunks if ch] # ' - ' results in empty strings
390	n/a	lines = []
391	n/a
392	n/a	while chunks:
393	n/a	cur_line = [] # list of chunks (to-be-joined)
394	n/a	cur_len = 0 # length of current line
395	n/a
396	n/a	while chunks:
397	n/a	l = len(chunks[0])
398	n/a	if cur_len + l <= width: # can squeeze (at least) this chunk in
399	n/a	cur_line.append(chunks[0])
400	n/a	del chunks[0]
401	n/a	cur_len = cur_len + l
402	n/a	else: # this line is full
403	n/a	# drop last chunk if all space
404	n/a	if cur_line and cur_line[-1][0] == ' ':
405	n/a	del cur_line[-1]
406	n/a	break
407	n/a
408	n/a	if chunks: # any chunks left to process?
409	n/a	# if the current line is still empty, then we had a single
410	n/a	# chunk that's too big too fit on a line -- so we break
411	n/a	# down and break it up at the line width
412	n/a	if cur_len == 0:
413	n/a	cur_line.append(chunks[0][0:width])
414	n/a	chunks[0] = chunks[0][width:]
415	n/a
416	n/a	# all-whitespace chunks at the end of a line can be discarded
417	n/a	# (and we know from the re.split above that if a chunk has
418	n/a	# any whitespace, it is all whitespace)
419	n/a	if chunks[0][0] == ' ':
420	n/a	del chunks[0]
421	n/a
422	n/a	# and store this line in the list-of-all-lines -- as a single
423	n/a	# string, of course!
424	n/a	lines.append(''.join(cur_line))
425	n/a
426	n/a	return lines
427	n/a
428	n/a
429	n/a	def translate_longopt(opt):
430	n/a	"""Convert a long option name to a valid Python identifier by
431	n/a	changing "-" to "_".
432	n/a	"""
433	n/a	return opt.translate(longopt_xlate)
434	n/a
435	n/a
436	n/a	class OptionDummy:
437	n/a	"""Dummy class just used as a place to hold command-line option
438	n/a	values as instance attributes."""
439	n/a
440	n/a	def __init__(self, options=[]):
441	n/a	"""Create a new OptionDummy instance. The attributes listed in
442	n/a	'options' will be initialized to None."""
443	n/a	for opt in options:
444	n/a	setattr(self, opt, None)
445	n/a
446	n/a
447	n/a	if __name__ == "__main__":
448	n/a	text = """\
449	n/a	Tra-la-la, supercalifragilisticexpialidocious.
450	n/a	How do you spell that odd word, anyways?
451	n/a	(Someone ask Mary -- she'll know [or she'll
452	n/a	say, "How should I know?"].)"""
453	n/a
454	n/a	for w in (10, 20, 30, 40):
455	n/a	print("width: %d" % w)
456	n/a	print("\n".join(wrap_text(text, w)))
457	n/a	print()