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