Python code coverage for Lib/lib2to3/fixer_util.py

#	count	content
1	n/a	"""Utility functions, node construction macros, etc."""
2	n/a	# Author: Collin Winter
3	n/a
4	n/a	# Local imports
5	n/a	from .pgen2 import token
6	n/a	from .pytree import Leaf, Node
7	n/a	from .pygram import python_symbols as syms
8	n/a	from . import patcomp
9	n/a
10	n/a
11	n/a	###########################################################
12	n/a	### Common node-construction "macros"
13	n/a	###########################################################
14	n/a
15	n/a	def KeywordArg(keyword, value):
16	n/a	return Node(syms.argument,
17	n/a	[keyword, Leaf(token.EQUAL, "="), value])
18	n/a
19	n/a	def LParen():
20	n/a	return Leaf(token.LPAR, "(")
21	n/a
22	n/a	def RParen():
23	n/a	return Leaf(token.RPAR, ")")
24	n/a
25	n/a	def Assign(target, source):
26	n/a	"""Build an assignment statement"""
27	n/a	if not isinstance(target, list):
28	n/a	target = [target]
29	n/a	if not isinstance(source, list):
30	n/a	source.prefix = " "
31	n/a	source = [source]
32	n/a
33	n/a	return Node(syms.atom,
34	n/a	target + [Leaf(token.EQUAL, "=", prefix=" ")] + source)
35	n/a
36	n/a	def Name(name, prefix=None):
37	n/a	"""Return a NAME leaf"""
38	n/a	return Leaf(token.NAME, name, prefix=prefix)
39	n/a
40	n/a	def Attr(obj, attr):
41	n/a	"""A node tuple for obj.attr"""
42	n/a	return [obj, Node(syms.trailer, [Dot(), attr])]
43	n/a
44	n/a	def Comma():
45	n/a	"""A comma leaf"""
46	n/a	return Leaf(token.COMMA, ",")
47	n/a
48	n/a	def Dot():
49	n/a	"""A period (.) leaf"""
50	n/a	return Leaf(token.DOT, ".")
51	n/a
52	n/a	def ArgList(args, lparen=LParen(), rparen=RParen()):
53	n/a	"""A parenthesised argument list, used by Call()"""
54	n/a	node = Node(syms.trailer, [lparen.clone(), rparen.clone()])
55	n/a	if args:
56	n/a	node.insert_child(1, Node(syms.arglist, args))
57	n/a	return node
58	n/a
59	n/a	def Call(func_name, args=None, prefix=None):
60	n/a	"""A function call"""
61	n/a	node = Node(syms.power, [func_name, ArgList(args)])
62	n/a	if prefix is not None:
63	n/a	node.prefix = prefix
64	n/a	return node
65	n/a
66	n/a	def Newline():
67	n/a	"""A newline literal"""
68	n/a	return Leaf(token.NEWLINE, "\n")
69	n/a
70	n/a	def BlankLine():
71	n/a	"""A blank line"""
72	n/a	return Leaf(token.NEWLINE, "")
73	n/a
74	n/a	def Number(n, prefix=None):
75	n/a	return Leaf(token.NUMBER, n, prefix=prefix)
76	n/a
77	n/a	def Subscript(index_node):
78	n/a	"""A numeric or string subscript"""
79	n/a	return Node(syms.trailer, [Leaf(token.LBRACE, "["),
80	n/a	index_node,
81	n/a	Leaf(token.RBRACE, "]")])
82	n/a
83	n/a	def String(string, prefix=None):
84	n/a	"""A string leaf"""
85	n/a	return Leaf(token.STRING, string, prefix=prefix)
86	n/a
87	n/a	def ListComp(xp, fp, it, test=None):
88	n/a	"""A list comprehension of the form [xp for fp in it if test].
89	n/a
90	n/a	If test is None, the "if test" part is omitted.
91	n/a	"""
92	n/a	xp.prefix = ""
93	n/a	fp.prefix = " "
94	n/a	it.prefix = " "
95	n/a	for_leaf = Leaf(token.NAME, "for")
96	n/a	for_leaf.prefix = " "
97	n/a	in_leaf = Leaf(token.NAME, "in")
98	n/a	in_leaf.prefix = " "
99	n/a	inner_args = [for_leaf, fp, in_leaf, it]
100	n/a	if test:
101	n/a	test.prefix = " "
102	n/a	if_leaf = Leaf(token.NAME, "if")
103	n/a	if_leaf.prefix = " "
104	n/a	inner_args.append(Node(syms.comp_if, [if_leaf, test]))
105	n/a	inner = Node(syms.listmaker, [xp, Node(syms.comp_for, inner_args)])
106	n/a	return Node(syms.atom,
107	n/a	[Leaf(token.LBRACE, "["),
108	n/a	inner,
109	n/a	Leaf(token.RBRACE, "]")])
110	n/a
111	n/a	def FromImport(package_name, name_leafs):
112	n/a	""" Return an import statement in the form:
113	n/a	from package import name_leafs"""
114	n/a	# XXX: May not handle dotted imports properly (eg, package_name='foo.bar')
115	n/a	#assert package_name == '.' or '.' not in package_name, "FromImport has "\
116	n/a	# "not been tested with dotted package names -- use at your own "\
117	n/a	# "peril!"
118	n/a
119	n/a	for leaf in name_leafs:
120	n/a	# Pull the leaves out of their old tree
121	n/a	leaf.remove()
122	n/a
123	n/a	children = [Leaf(token.NAME, "from"),
124	n/a	Leaf(token.NAME, package_name, prefix=" "),
125	n/a	Leaf(token.NAME, "import", prefix=" "),
126	n/a	Node(syms.import_as_names, name_leafs)]
127	n/a	imp = Node(syms.import_from, children)
128	n/a	return imp
129	n/a
130	n/a	def ImportAndCall(node, results, names):
131	n/a	"""Returns an import statement and calls a method
132	n/a	of the module:
133	n/a
134	n/a	import module
135	n/a	module.name()"""
136	n/a	obj = results["obj"].clone()
137	n/a	if obj.type == syms.arglist:
138	n/a	newarglist = obj.clone()
139	n/a	else:
140	n/a	newarglist = Node(syms.arglist, [obj.clone()])
141	n/a	after = results["after"]
142	n/a	if after:
143	n/a	after = [n.clone() for n in after]
144	n/a	new = Node(syms.power,
145	n/a	Attr(Name(names[0]), Name(names[1])) +
146	n/a	[Node(syms.trailer,
147	n/a	[results["lpar"].clone(),
148	n/a	newarglist,
149	n/a	results["rpar"].clone()])] + after)
150	n/a	new.prefix = node.prefix
151	n/a	return new
152	n/a
153	n/a
154	n/a	###########################################################
155	n/a	### Determine whether a node represents a given literal
156	n/a	###########################################################
157	n/a
158	n/a	def is_tuple(node):
159	n/a	"""Does the node represent a tuple literal?"""
160	n/a	if isinstance(node, Node) and node.children == [LParen(), RParen()]:
161	n/a	return True
162	n/a	return (isinstance(node, Node)
163	n/a	and len(node.children) == 3
164	n/a	and isinstance(node.children[0], Leaf)
165	n/a	and isinstance(node.children[1], Node)
166	n/a	and isinstance(node.children[2], Leaf)
167	n/a	and node.children[0].value == "("
168	n/a	and node.children[2].value == ")")
169	n/a
170	n/a	def is_list(node):
171	n/a	"""Does the node represent a list literal?"""
172	n/a	return (isinstance(node, Node)
173	n/a	and len(node.children) > 1
174	n/a	and isinstance(node.children[0], Leaf)
175	n/a	and isinstance(node.children[-1], Leaf)
176	n/a	and node.children[0].value == "["
177	n/a	and node.children[-1].value == "]")
178	n/a
179	n/a
180	n/a	###########################################################
181	n/a	### Misc
182	n/a	###########################################################
183	n/a
184	n/a	def parenthesize(node):
185	n/a	return Node(syms.atom, [LParen(), node, RParen()])
186	n/a
187	n/a
188	n/a	consuming_calls = {"sorted", "list", "set", "any", "all", "tuple", "sum",
189	n/a	"min", "max", "enumerate"}
190	n/a
191	n/a	def attr_chain(obj, attr):
192	n/a	"""Follow an attribute chain.
193	n/a
194	n/a	If you have a chain of objects where a.foo -> b, b.foo-> c, etc,
195	n/a	use this to iterate over all objects in the chain. Iteration is
196	n/a	terminated by getattr(x, attr) is None.
197	n/a
198	n/a	Args:
199	n/a	obj: the starting object
200	n/a	attr: the name of the chaining attribute
201	n/a
202	n/a	Yields:
203	n/a	Each successive object in the chain.
204	n/a	"""
205	n/a	next = getattr(obj, attr)
206	n/a	while next:
207	n/a	yield next
208	n/a	next = getattr(next, attr)
209	n/a
210	n/a	p0 = """for_stmt< 'for' any 'in' node=any ':' any* >
211	n/a	\| comp_for< 'for' any 'in' node=any any* >
212	n/a	"""
213	n/a	p1 = """
214	n/a	power<
215	n/a	( 'iter' \| 'list' \| 'tuple' \| 'sorted' \| 'set' \| 'sum' \|
216	n/a	'any' \| 'all' \| 'enumerate' \| (any* trailer< '.' 'join' >) )
217	n/a	trailer< '(' node=any ')' >
218	n/a	any*
219	n/a	>
220	n/a	"""
221	n/a	p2 = """
222	n/a	power<
223	n/a	( 'sorted' \| 'enumerate' )
224	n/a	trailer< '(' arglist<node=any any*> ')' >
225	n/a	any*
226	n/a	>
227	n/a	"""
228	n/a	pats_built = False
229	n/a	def in_special_context(node):
230	n/a	""" Returns true if node is in an environment where all that is required
231	n/a	of it is being iterable (ie, it doesn't matter if it returns a list
232	n/a	or an iterator).
233	n/a	See test_map_nochange in test_fixers.py for some examples and tests.
234	n/a	"""
235	n/a	global p0, p1, p2, pats_built
236	n/a	if not pats_built:
237	n/a	p0 = patcomp.compile_pattern(p0)
238	n/a	p1 = patcomp.compile_pattern(p1)
239	n/a	p2 = patcomp.compile_pattern(p2)
240	n/a	pats_built = True
241	n/a	patterns = [p0, p1, p2]
242	n/a	for pattern, parent in zip(patterns, attr_chain(node, "parent")):
243	n/a	results = {}
244	n/a	if pattern.match(parent, results) and results["node"] is node:
245	n/a	return True
246	n/a	return False
247	n/a
248	n/a	def is_probably_builtin(node):
249	n/a	"""
250	n/a	Check that something isn't an attribute or function name etc.
251	n/a	"""
252	n/a	prev = node.prev_sibling
253	n/a	if prev is not None and prev.type == token.DOT:
254	n/a	# Attribute lookup.
255	n/a	return False
256	n/a	parent = node.parent
257	n/a	if parent.type in (syms.funcdef, syms.classdef):
258	n/a	return False
259	n/a	if parent.type == syms.expr_stmt and parent.children[0] is node:
260	n/a	# Assignment.
261	n/a	return False
262	n/a	if parent.type == syms.parameters or \
263	n/a	(parent.type == syms.typedargslist and (
264	n/a	(prev is not None and prev.type == token.COMMA) or
265	n/a	parent.children[0] is node
266	n/a	)):
267	n/a	# The name of an argument.
268	n/a	return False
269	n/a	return True
270	n/a
271	n/a	def find_indentation(node):
272	n/a	"""Find the indentation of node."""
273	n/a	while node is not None:
274	n/a	if node.type == syms.suite and len(node.children) > 2:
275	n/a	indent = node.children[1]
276	n/a	if indent.type == token.INDENT:
277	n/a	return indent.value
278	n/a	node = node.parent
279	n/a	return ""
280	n/a
281	n/a	###########################################################
282	n/a	### The following functions are to find bindings in a suite
283	n/a	###########################################################
284	n/a
285	n/a	def make_suite(node):
286	n/a	if node.type == syms.suite:
287	n/a	return node
288	n/a	node = node.clone()
289	n/a	parent, node.parent = node.parent, None
290	n/a	suite = Node(syms.suite, [node])
291	n/a	suite.parent = parent
292	n/a	return suite
293	n/a
294	n/a	def find_root(node):
295	n/a	"""Find the top level namespace."""
296	n/a	# Scamper up to the top level namespace
297	n/a	while node.type != syms.file_input:
298	n/a	node = node.parent
299	n/a	if not node:
300	n/a	raise ValueError("root found before file_input node was found.")
301	n/a	return node
302	n/a
303	n/a	def does_tree_import(package, name, node):
304	n/a	""" Returns true if name is imported from package at the
305	n/a	top level of the tree which node belongs to.
306	n/a	To cover the case of an import like 'import foo', use
307	n/a	None for the package and 'foo' for the name. """
308	n/a	binding = find_binding(name, find_root(node), package)
309	n/a	return bool(binding)
310	n/a
311	n/a	def is_import(node):
312	n/a	"""Returns true if the node is an import statement."""
313	n/a	return node.type in (syms.import_name, syms.import_from)
314	n/a
315	n/a	def touch_import(package, name, node):
316	n/a	""" Works like `does_tree_import` but adds an import statement
317	n/a	if it was not imported. """
318	n/a	def is_import_stmt(node):
319	n/a	return (node.type == syms.simple_stmt and node.children and
320	n/a	is_import(node.children[0]))
321	n/a
322	n/a	root = find_root(node)
323	n/a
324	n/a	if does_tree_import(package, name, root):
325	n/a	return
326	n/a
327	n/a	# figure out where to insert the new import. First try to find
328	n/a	# the first import and then skip to the last one.
329	n/a	insert_pos = offset = 0
330	n/a	for idx, node in enumerate(root.children):
331	n/a	if not is_import_stmt(node):
332	n/a	continue
333	n/a	for offset, node2 in enumerate(root.children[idx:]):
334	n/a	if not is_import_stmt(node2):
335	n/a	break
336	n/a	insert_pos = idx + offset
337	n/a	break
338	n/a
339	n/a	# if there are no imports where we can insert, find the docstring.
340	n/a	# if that also fails, we stick to the beginning of the file
341	n/a	if insert_pos == 0:
342	n/a	for idx, node in enumerate(root.children):
343	n/a	if (node.type == syms.simple_stmt and node.children and
344	n/a	node.children[0].type == token.STRING):
345	n/a	insert_pos = idx + 1
346	n/a	break
347	n/a
348	n/a	if package is None:
349	n/a	import_ = Node(syms.import_name, [
350	n/a	Leaf(token.NAME, "import"),
351	n/a	Leaf(token.NAME, name, prefix=" ")
352	n/a	])
353	n/a	else:
354	n/a	import_ = FromImport(package, [Leaf(token.NAME, name, prefix=" ")])
355	n/a
356	n/a	children = [import_, Newline()]
357	n/a	root.insert_child(insert_pos, Node(syms.simple_stmt, children))
358	n/a
359	n/a
360	n/a	_def_syms = {syms.classdef, syms.funcdef}
361	n/a	def find_binding(name, node, package=None):
362	n/a	""" Returns the node which binds variable name, otherwise None.
363	n/a	If optional argument package is supplied, only imports will
364	n/a	be returned.
365	n/a	See test cases for examples."""
366	n/a	for child in node.children:
367	n/a	ret = None
368	n/a	if child.type == syms.for_stmt:
369	n/a	if _find(name, child.children[1]):
370	n/a	return child
371	n/a	n = find_binding(name, make_suite(child.children[-1]), package)
372	n/a	if n: ret = n
373	n/a	elif child.type in (syms.if_stmt, syms.while_stmt):
374	n/a	n = find_binding(name, make_suite(child.children[-1]), package)
375	n/a	if n: ret = n
376	n/a	elif child.type == syms.try_stmt:
377	n/a	n = find_binding(name, make_suite(child.children[2]), package)
378	n/a	if n:
379	n/a	ret = n
380	n/a	else:
381	n/a	for i, kid in enumerate(child.children[3:]):
382	n/a	if kid.type == token.COLON and kid.value == ":":
383	n/a	# i+3 is the colon, i+4 is the suite
384	n/a	n = find_binding(name, make_suite(child.children[i+4]), package)
385	n/a	if n: ret = n
386	n/a	elif child.type in _def_syms and child.children[1].value == name:
387	n/a	ret = child
388	n/a	elif _is_import_binding(child, name, package):
389	n/a	ret = child
390	n/a	elif child.type == syms.simple_stmt:
391	n/a	ret = find_binding(name, child, package)
392	n/a	elif child.type == syms.expr_stmt:
393	n/a	if _find(name, child.children[0]):
394	n/a	ret = child
395	n/a
396	n/a	if ret:
397	n/a	if not package:
398	n/a	return ret
399	n/a	if is_import(ret):
400	n/a	return ret
401	n/a	return None
402	n/a
403	n/a	_block_syms = {syms.funcdef, syms.classdef, syms.trailer}
404	n/a	def _find(name, node):
405	n/a	nodes = [node]
406	n/a	while nodes:
407	n/a	node = nodes.pop()
408	n/a	if node.type > 256 and node.type not in _block_syms:
409	n/a	nodes.extend(node.children)
410	n/a	elif node.type == token.NAME and node.value == name:
411	n/a	return node
412	n/a	return None
413	n/a
414	n/a	def _is_import_binding(node, name, package=None):
415	n/a	""" Will reuturn node if node will import name, or node
416	n/a	will import * from package. None is returned otherwise.
417	n/a	See test cases for examples. """
418	n/a
419	n/a	if node.type == syms.import_name and not package:
420	n/a	imp = node.children[1]
421	n/a	if imp.type == syms.dotted_as_names:
422	n/a	for child in imp.children:
423	n/a	if child.type == syms.dotted_as_name:
424	n/a	if child.children[2].value == name:
425	n/a	return node
426	n/a	elif child.type == token.NAME and child.value == name:
427	n/a	return node
428	n/a	elif imp.type == syms.dotted_as_name:
429	n/a	last = imp.children[-1]
430	n/a	if last.type == token.NAME and last.value == name:
431	n/a	return node
432	n/a	elif imp.type == token.NAME and imp.value == name:
433	n/a	return node
434	n/a	elif node.type == syms.import_from:
435	n/a	# str(...) is used to make life easier here, because
436	n/a	# from a.b import parses to ['import', ['a', '.', 'b'], ...]
437	n/a	if package and str(node.children[1]).strip() != package:
438	n/a	return None
439	n/a	n = node.children[3]
440	n/a	if package and _find("as", n):
441	n/a	# See test_from_import_as for explanation
442	n/a	return None
443	n/a	elif n.type == syms.import_as_names and _find(name, n):
444	n/a	return node
445	n/a	elif n.type == syms.import_as_name:
446	n/a	child = n.children[2]
447	n/a	if child.type == token.NAME and child.value == name:
448	n/a	return node
449	n/a	elif n.type == token.NAME and n.value == name:
450	n/a	return node
451	n/a	elif package and n.type == token.STAR:
452	n/a	return node
453	n/a	return None