Python code coverage for Lib/ast.py

#	count	content
1	n/a	"""
2	n/a	ast
3	n/a	~~~
4	n/a
5	n/a	The `ast` module helps Python applications to process trees of the Python
6	n/a	abstract syntax grammar. The abstract syntax itself might change with
7	n/a	each Python release; this module helps to find out programmatically what
8	n/a	the current grammar looks like and allows modifications of it.
9	n/a
10	n/a	An abstract syntax tree can be generated by passing `ast.PyCF_ONLY_AST` as
11	n/a	a flag to the `compile()` builtin function or by using the `parse()`
12	n/a	function from this module. The result will be a tree of objects whose
13	n/a	classes all inherit from `ast.AST`.
14	n/a
15	n/a	A modified abstract syntax tree can be compiled into a Python code object
16	n/a	using the built-in `compile()` function.
17	n/a
18	n/a	Additionally various helper functions are provided that make working with
19	n/a	the trees simpler. The main intention of the helper functions and this
20	n/a	module in general is to provide an easy to use interface for libraries
21	n/a	that work tightly with the python syntax (template engines for example).
22	n/a
23	n/a
24	n/a	:copyright: Copyright 2008 by Armin Ronacher.
25	n/a	:license: Python License.
26	n/a	"""
27	n/a	from _ast import *
28	n/a
29	n/a
30	n/a	def parse(source, filename='<unknown>', mode='exec'):
31	n/a	"""
32	n/a	Parse the source into an AST node.
33	n/a	Equivalent to compile(source, filename, mode, PyCF_ONLY_AST).
34	n/a	"""
35	n/a	return compile(source, filename, mode, PyCF_ONLY_AST)
36	n/a
37	n/a
38	n/a	_NUM_TYPES = (int, float, complex)
39	n/a
40	n/a	def literal_eval(node_or_string):
41	n/a	"""
42	n/a	Safely evaluate an expression node or a string containing a Python
43	n/a	expression. The string or node provided may only consist of the following
44	n/a	Python literal structures: strings, bytes, numbers, tuples, lists, dicts,
45	n/a	sets, booleans, and None.
46	n/a	"""
47	n/a	if isinstance(node_or_string, str):
48	n/a	node_or_string = parse(node_or_string, mode='eval')
49	n/a	if isinstance(node_or_string, Expression):
50	n/a	node_or_string = node_or_string.body
51	n/a	def _convert(node):
52	n/a	if isinstance(node, Constant):
53	n/a	return node.value
54	n/a	elif isinstance(node, (Str, Bytes)):
55	n/a	return node.s
56	n/a	elif isinstance(node, Num):
57	n/a	return node.n
58	n/a	elif isinstance(node, Tuple):
59	n/a	return tuple(map(_convert, node.elts))
60	n/a	elif isinstance(node, List):
61	n/a	return list(map(_convert, node.elts))
62	n/a	elif isinstance(node, Set):
63	n/a	return set(map(_convert, node.elts))
64	n/a	elif isinstance(node, Dict):
65	n/a	return dict((_convert(k), _convert(v)) for k, v
66	n/a	in zip(node.keys, node.values))
67	n/a	elif isinstance(node, NameConstant):
68	n/a	return node.value
69	n/a	elif isinstance(node, UnaryOp) and isinstance(node.op, (UAdd, USub)):
70	n/a	operand = _convert(node.operand)
71	n/a	if isinstance(operand, _NUM_TYPES):
72	n/a	if isinstance(node.op, UAdd):
73	n/a	return + operand
74	n/a	else:
75	n/a	return - operand
76	n/a	elif isinstance(node, BinOp) and isinstance(node.op, (Add, Sub)):
77	n/a	left = _convert(node.left)
78	n/a	right = _convert(node.right)
79	n/a	if isinstance(left, _NUM_TYPES) and isinstance(right, _NUM_TYPES):
80	n/a	if isinstance(node.op, Add):
81	n/a	return left + right
82	n/a	else:
83	n/a	return left - right
84	n/a	raise ValueError('malformed node or string: ' + repr(node))
85	n/a	return _convert(node_or_string)
86	n/a
87	n/a
88	n/a	def dump(node, annotate_fields=True, include_attributes=False):
89	n/a	"""
90	n/a	Return a formatted dump of the tree in node. This is mainly useful for
91	n/a	debugging purposes. The returned string will show the names and the values
92	n/a	for fields. This makes the code impossible to evaluate, so if evaluation is
93	n/a	wanted annotate_fields must be set to False. Attributes such as line
94	n/a	numbers and column offsets are not dumped by default. If this is wanted,
95	n/a	include_attributes can be set to True.
96	n/a	"""
97	n/a	def _format(node):
98	n/a	if isinstance(node, AST):
99	n/a	fields = [(a, _format(b)) for a, b in iter_fields(node)]
100	n/a	rv = '%s(%s' % (node.__class__.__name__, ', '.join(
101	n/a	('%s=%s' % field for field in fields)
102	n/a	if annotate_fields else
103	n/a	(b for a, b in fields)
104	n/a	))
105	n/a	if include_attributes and node._attributes:
106	n/a	rv += fields and ', ' or ' '
107	n/a	rv += ', '.join('%s=%s' % (a, _format(getattr(node, a)))
108	n/a	for a in node._attributes)
109	n/a	return rv + ')'
110	n/a	elif isinstance(node, list):
111	n/a	return '[%s]' % ', '.join(_format(x) for x in node)
112	n/a	return repr(node)
113	n/a	if not isinstance(node, AST):
114	n/a	raise TypeError('expected AST, got %r' % node.__class__.__name__)
115	n/a	return _format(node)
116	n/a
117	n/a
118	n/a	def copy_location(new_node, old_node):
119	n/a	"""
120	n/a	Copy source location (`lineno` and `col_offset` attributes) from
121	n/a	old_node to new_node if possible, and return new_node.
122	n/a	"""
123	n/a	for attr in 'lineno', 'col_offset':
124	n/a	if attr in old_node._attributes and attr in new_node._attributes \
125	n/a	and hasattr(old_node, attr):
126	n/a	setattr(new_node, attr, getattr(old_node, attr))
127	n/a	return new_node
128	n/a
129	n/a
130	n/a	def fix_missing_locations(node):
131	n/a	"""
132	n/a	When you compile a node tree with compile(), the compiler expects lineno and
133	n/a	col_offset attributes for every node that supports them. This is rather
134	n/a	tedious to fill in for generated nodes, so this helper adds these attributes
135	n/a	recursively where not already set, by setting them to the values of the
136	n/a	parent node. It works recursively starting at node.
137	n/a	"""
138	n/a	def _fix(node, lineno, col_offset):
139	n/a	if 'lineno' in node._attributes:
140	n/a	if not hasattr(node, 'lineno'):
141	n/a	node.lineno = lineno
142	n/a	else:
143	n/a	lineno = node.lineno
144	n/a	if 'col_offset' in node._attributes:
145	n/a	if not hasattr(node, 'col_offset'):
146	n/a	node.col_offset = col_offset
147	n/a	else:
148	n/a	col_offset = node.col_offset
149	n/a	for child in iter_child_nodes(node):
150	n/a	_fix(child, lineno, col_offset)
151	n/a	_fix(node, 1, 0)
152	n/a	return node
153	n/a
154	n/a
155	n/a	def increment_lineno(node, n=1):
156	n/a	"""
157	n/a	Increment the line number of each node in the tree starting at node by n.
158	n/a	This is useful to "move code" to a different location in a file.
159	n/a	"""
160	n/a	for child in walk(node):
161	n/a	if 'lineno' in child._attributes:
162	n/a	child.lineno = getattr(child, 'lineno', 0) + n
163	n/a	return node
164	n/a
165	n/a
166	n/a	def iter_fields(node):
167	n/a	"""
168	n/a	Yield a tuple of ``(fieldname, value)`` for each field in ``node._fields``
169	n/a	that is present on node.
170	n/a	"""
171	n/a	for field in node._fields:
172	n/a	try:
173	n/a	yield field, getattr(node, field)
174	n/a	except AttributeError:
175	n/a	pass
176	n/a
177	n/a
178	n/a	def iter_child_nodes(node):
179	n/a	"""
180	n/a	Yield all direct child nodes of node, that is, all fields that are nodes
181	n/a	and all items of fields that are lists of nodes.
182	n/a	"""
183	n/a	for name, field in iter_fields(node):
184	n/a	if isinstance(field, AST):
185	n/a	yield field
186	n/a	elif isinstance(field, list):
187	n/a	for item in field:
188	n/a	if isinstance(item, AST):
189	n/a	yield item
190	n/a
191	n/a
192	n/a	def get_docstring(node, clean=True):
193	n/a	"""
194	n/a	Return the docstring for the given node or None if no docstring can
195	n/a	be found. If the node provided does not have docstrings a TypeError
196	n/a	will be raised.
197	n/a	"""
198	n/a	if not isinstance(node, (AsyncFunctionDef, FunctionDef, ClassDef, Module)):
199	n/a	raise TypeError("%r can't have docstrings" % node.__class__.__name__)
200	n/a	if not(node.body and isinstance(node.body[0], Expr)):
201	n/a	return
202	n/a	node = node.body[0].value
203	n/a	if isinstance(node, Str):
204	n/a	text = node.s
205	n/a	elif isinstance(node, Constant) and isinstance(node.value, str):
206	n/a	text = node.value
207	n/a	else:
208	n/a	return
209	n/a	if clean:
210	n/a	import inspect
211	n/a	text = inspect.cleandoc(text)
212	n/a	return text
213	n/a
214	n/a
215	n/a	def walk(node):
216	n/a	"""
217	n/a	Recursively yield all descendant nodes in the tree starting at node
218	n/a	(including node itself), in no specified order. This is useful if you
219	n/a	only want to modify nodes in place and don't care about the context.
220	n/a	"""
221	n/a	from collections import deque
222	n/a	todo = deque([node])
223	n/a	while todo:
224	n/a	node = todo.popleft()
225	n/a	todo.extend(iter_child_nodes(node))
226	n/a	yield node
227	n/a
228	n/a
229	n/a	class NodeVisitor(object):
230	n/a	"""
231	n/a	A node visitor base class that walks the abstract syntax tree and calls a
232	n/a	visitor function for every node found. This function may return a value
233	n/a	which is forwarded by the `visit` method.
234	n/a
235	n/a	This class is meant to be subclassed, with the subclass adding visitor
236	n/a	methods.
237	n/a
238	n/a	Per default the visitor functions for the nodes are ``'visit_'`` +
239	n/a	class name of the node. So a `TryFinally` node visit function would
240	n/a	be `visit_TryFinally`. This behavior can be changed by overriding
241	n/a	the `visit` method. If no visitor function exists for a node
242	n/a	(return value `None`) the `generic_visit` visitor is used instead.
243	n/a
244	n/a	Don't use the `NodeVisitor` if you want to apply changes to nodes during
245	n/a	traversing. For this a special visitor exists (`NodeTransformer`) that
246	n/a	allows modifications.
247	n/a	"""
248	n/a
249	n/a	def visit(self, node):
250	n/a	"""Visit a node."""
251	n/a	method = 'visit_' + node.__class__.__name__
252	n/a	visitor = getattr(self, method, self.generic_visit)
253	n/a	return visitor(node)
254	n/a
255	n/a	def generic_visit(self, node):
256	n/a	"""Called if no explicit visitor function exists for a node."""
257	n/a	for field, value in iter_fields(node):
258	n/a	if isinstance(value, list):
259	n/a	for item in value:
260	n/a	if isinstance(item, AST):
261	n/a	self.visit(item)
262	n/a	elif isinstance(value, AST):
263	n/a	self.visit(value)
264	n/a
265	n/a
266	n/a	class NodeTransformer(NodeVisitor):
267	n/a	"""
268	n/a	A :class:`NodeVisitor` subclass that walks the abstract syntax tree and
269	n/a	allows modification of nodes.
270	n/a
271	n/a	The `NodeTransformer` will walk the AST and use the return value of the
272	n/a	visitor methods to replace or remove the old node. If the return value of
273	n/a	the visitor method is ``None``, the node will be removed from its location,
274	n/a	otherwise it is replaced with the return value. The return value may be the
275	n/a	original node in which case no replacement takes place.
276	n/a
277	n/a	Here is an example transformer that rewrites all occurrences of name lookups
278	n/a	(``foo``) to ``data['foo']``::
279	n/a
280	n/a	class RewriteName(NodeTransformer):
281	n/a
282	n/a	def visit_Name(self, node):
283	n/a	return copy_location(Subscript(
284	n/a	value=Name(id='data', ctx=Load()),
285	n/a	slice=Index(value=Str(s=node.id)),
286	n/a	ctx=node.ctx
287	n/a	), node)
288	n/a
289	n/a	Keep in mind that if the node you're operating on has child nodes you must
290	n/a	either transform the child nodes yourself or call the :meth:`generic_visit`
291	n/a	method for the node first.
292	n/a
293	n/a	For nodes that were part of a collection of statements (that applies to all
294	n/a	statement nodes), the visitor may also return a list of nodes rather than
295	n/a	just a single node.
296	n/a
297	n/a	Usually you use the transformer like this::
298	n/a
299	n/a	node = YourTransformer().visit(node)
300	n/a	"""
301	n/a
302	n/a	def generic_visit(self, node):
303	n/a	for field, old_value in iter_fields(node):
304	n/a	if isinstance(old_value, list):
305	n/a	new_values = []
306	n/a	for value in old_value:
307	n/a	if isinstance(value, AST):
308	n/a	value = self.visit(value)
309	n/a	if value is None:
310	n/a	continue
311	n/a	elif not isinstance(value, AST):
312	n/a	new_values.extend(value)
313	n/a	continue
314	n/a	new_values.append(value)
315	n/a	old_value[:] = new_values
316	n/a	elif isinstance(old_value, AST):
317	n/a	new_node = self.visit(old_value)
318	n/a	if new_node is None:
319	n/a	delattr(node, field)
320	n/a	else:
321	n/a	setattr(node, field, new_node)
322	n/a	return node