Gitiles
Code Review Sign In
gerrit.onosproject.org / OnosSystemTest / 016dce254e4c4a3b478dd177a366cef9d7766e06 / . / TestON / Documentation / TestON_Document / TestON.core.ast-module.html
blob: 737671729af4750d878d797cbf21ed4abf2fa570 [file] [log] [blame]
adminbae64d82013-08-01 10:50:15 -0700[diff] [blame]1<?xml version="1.0" encoding="ascii"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "DTD/xhtml1-transitional.dtd">
4<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5<head>
6 <title>TestON.core.ast</title>
7 <link rel="stylesheet" href="epydoc.css" type="text/css" />
8 <script type="text/javascript" src="epydoc.js"></script>
9</head>
10
11<body bgcolor="white" text="black" link="blue" vlink="#204080"
12 alink="#204080">
13<!-- ==================== NAVIGATION BAR ==================== -->
14<table class="navbar" border="0" width="100%" cellpadding="0"
15 bgcolor="#a0c0ff" cellspacing="0">
16 <tr valign="middle">
17 <!-- Home link -->
18 <th>&nbsp;&nbsp;&nbsp;<a
19 href="TestON-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
20
21 <!-- Tree link -->
22 <th>&nbsp;&nbsp;&nbsp;<a
23 href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
24
25 <!-- Index link -->
26 <th>&nbsp;&nbsp;&nbsp;<a
27 href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
28
29 <!-- Help link -->
30 <th>&nbsp;&nbsp;&nbsp;<a
31 href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
32
33 <th class="navbar" width="100%"></th>
34 </tr>
35</table>
36<table width="100%" cellpadding="0" cellspacing="0">
37 <tr valign="top">
38 <td width="100%">
39 <span class="breadcrumbs">
40 <a href="TestON-module.html">Package&nbsp;TestON</a> ::
41 <a href="TestON.core-module.html">Package&nbsp;core</a> ::
42 Module&nbsp;ast
43 </span>
44 </td>
45 <td>
46 <table cellpadding="0" cellspacing="0">
47 <!-- hide/show private -->
48 <tr><td align="right"><span class="options">[<a href="javascript:void(0);" class="privatelink"
49 onclick="toggle_private();">hide&nbsp;private</a>]</span></td></tr>
50 <tr><td align="right"><span class="options"
51 >[<a href="frames.html" target="_top">frames</a
52 >]&nbsp;|&nbsp;<a href="TestON.core.ast-module.html"
53 target="_top">no&nbsp;frames</a>]</span></td></tr>
54 </table>
55 </td>
56 </tr>
57</table>
58<!-- ==================== MODULE DESCRIPTION ==================== -->
59<h1 class="epydoc">Module ast</h1><p class="nomargin-top"><span class="codelink"><a href="TestON.core.ast-pysrc.html">source&nbsp;code</a></span></p>
60<pre class="literalblock">
61
62ast
63~~~
64
65The `ast` module helps Python applications to process trees of the Python
66abstract syntax grammar. The abstract syntax itself might change with
67each Python release; this module helps to find out programmatically what
68the current grammar looks like and allows modifications of it.
69
70An abstract syntax tree can be generated by passing `ast.PyCF_ONLY_AST` as
71a flag to the `compile()` builtin function or by using the `parse()`
72function from this module. The result will be a tree of objects whose
73classes all inherit from `ast.AST`.
74
75A modified abstract syntax tree can be compiled into a Python code object
76using the built-in `compile()` function.
77
78Additionally various helper functions are provided that make working with
79the trees simpler. The main intention of the helper functions and this
80module in general is to provide an easy to use interface for libraries
81that work tightly with the python syntax (template engines for example).
82
83
84:copyright: Copyright 2008 by Armin Ronacher.
85:license: Python License.
86
87</pre>
88
89<!-- ==================== CLASSES ==================== -->
90<a name="section-Classes"></a>
91<table class="summary" border="1" cellpadding="3"
92 cellspacing="0" width="100%" bgcolor="white">
93<tr bgcolor="#70b0f0" class="table-header">
94 <td colspan="2" class="table-header">
95 <table border="0" cellpadding="0" cellspacing="0" width="100%">
96 <tr valign="top">
97 <td align="left"><span class="table-header">Classes</span></td>
98 <td align="right" valign="top"
99 ><span class="options">[<a href="#section-Classes"
100 class="privatelink" onclick="toggle_private();"
101 >hide private</a>]</span></td>
102 </tr>
103 </table>
104 </td>
105</tr>
106<tr>
107 <td width="15%" align="right" valign="top" class="summary">
108 <span class="summary-type">&nbsp;</span>
109 </td><td class="summary">
110 <a href="TestON.core.ast.NodeVisitor-class.html" class="summary-name">NodeVisitor</a><br />
111 A node visitor base class that walks the abstract syntax tree and
112 calls a visitor function for every node found.
113 </td>
114 </tr>
115<tr>
116 <td width="15%" align="right" valign="top" class="summary">
117 <span class="summary-type">&nbsp;</span>
118 </td><td class="summary">
119 <a href="TestON.core.ast.NodeTransformer-class.html" class="summary-name">NodeTransformer</a><br />
120 A :class:`NodeVisitor` subclass that walks the abstract syntax tree
121 and allows modification of nodes.
122 </td>
123 </tr>
124</table>
125<!-- ==================== FUNCTIONS ==================== -->
126<a name="section-Functions"></a>
127<table class="summary" border="1" cellpadding="3"
128 cellspacing="0" width="100%" bgcolor="white">
129<tr bgcolor="#70b0f0" class="table-header">
130 <td colspan="2" class="table-header">
131 <table border="0" cellpadding="0" cellspacing="0" width="100%">
132 <tr valign="top">
133 <td align="left"><span class="table-header">Functions</span></td>
134 <td align="right" valign="top"
135 ><span class="options">[<a href="#section-Functions"
136 class="privatelink" onclick="toggle_private();"
137 >hide private</a>]</span></td>
138 </tr>
139 </table>
140 </td>
141</tr>
142<tr>
143 <td width="15%" align="right" valign="top" class="summary">
144 <span class="summary-type">&nbsp;</span>
145 </td><td class="summary">
146 <table width="100%" cellpadding="0" cellspacing="0" border="0">
147 <tr>
148 <td><span class="summary-sig"><a href="TestON.core.ast-module.html#parse" class="summary-sig-name">parse</a>(<span class="summary-sig-arg">source</span>,
149 <span class="summary-sig-arg">filename</span>=<span class="summary-sig-default">'&lt;unknown&gt;'</span>,
150 <span class="summary-sig-arg">mode</span>=<span class="summary-sig-default">'exec'</span>)</span><br />
151 Parse the source into an AST node.</td>
152 <td align="right" valign="top">
153 <span class="codelink"><a href="TestON.core.ast-pysrc.html#parse">source&nbsp;code</a></span>
154
155 </td>
156 </tr>
157 </table>
158
159 </td>
160 </tr>
161<tr>
162 <td width="15%" align="right" valign="top" class="summary">
163 <span class="summary-type">&nbsp;</span>
164 </td><td class="summary">
165 <table width="100%" cellpadding="0" cellspacing="0" border="0">
166 <tr>
167 <td><span class="summary-sig"><a href="TestON.core.ast-module.html#literal_eval" class="summary-sig-name">literal_eval</a>(<span class="summary-sig-arg">node_or_string</span>)</span><br />
168 Safely evaluate an expression node or a string containing a Python
169 expression.</td>
170 <td align="right" valign="top">
171 <span class="codelink"><a href="TestON.core.ast-pysrc.html#literal_eval">source&nbsp;code</a></span>
172
173 </td>
174 </tr>
175 </table>
176
177 </td>
178 </tr>
179<tr>
180 <td width="15%" align="right" valign="top" class="summary">
181 <span class="summary-type">&nbsp;</span>
182 </td><td class="summary">
183 <table width="100%" cellpadding="0" cellspacing="0" border="0">
184 <tr>
185 <td><span class="summary-sig"><a href="TestON.core.ast-module.html#dump" class="summary-sig-name">dump</a>(<span class="summary-sig-arg">node</span>,
186 <span class="summary-sig-arg">annotate_fields</span>=<span class="summary-sig-default">True</span>,
187 <span class="summary-sig-arg">include_attributes</span>=<span class="summary-sig-default">False</span>)</span><br />
188 Return a formatted dump of the tree in *node*.</td>
189 <td align="right" valign="top">
190 <span class="codelink"><a href="TestON.core.ast-pysrc.html#dump">source&nbsp;code</a></span>
191
192 </td>
193 </tr>
194 </table>
195
196 </td>
197 </tr>
198<tr>
199 <td width="15%" align="right" valign="top" class="summary">
200 <span class="summary-type">&nbsp;</span>
201 </td><td class="summary">
202 <table width="100%" cellpadding="0" cellspacing="0" border="0">
203 <tr>
204 <td><span class="summary-sig"><a name="copy_location"></a><span class="summary-sig-name">copy_location</span>(<span class="summary-sig-arg">new_node</span>,
205 <span class="summary-sig-arg">old_node</span>)</span><br />
206 Copy source location (`lineno` and `col_offset` attributes) from
207 *old_node* to *new_node* if possible, and return *new_node*.</td>
208 <td align="right" valign="top">
209 <span class="codelink"><a href="TestON.core.ast-pysrc.html#copy_location">source&nbsp;code</a></span>
210
211 </td>
212 </tr>
213 </table>
214
215 </td>
216 </tr>
217<tr>
218 <td width="15%" align="right" valign="top" class="summary">
219 <span class="summary-type">&nbsp;</span>
220 </td><td class="summary">
221 <table width="100%" cellpadding="0" cellspacing="0" border="0">
222 <tr>
223 <td><span class="summary-sig"><a href="TestON.core.ast-module.html#fix_missing_locations" class="summary-sig-name">fix_missing_locations</a>(<span class="summary-sig-arg">node</span>)</span><br />
224 When you compile a node tree with compile(), the compiler expects
225 lineno and col_offset attributes for every node that supports them.</td>
226 <td align="right" valign="top">
227 <span class="codelink"><a href="TestON.core.ast-pysrc.html#fix_missing_locations">source&nbsp;code</a></span>
228
229 </td>
230 </tr>
231 </table>
232
233 </td>
234 </tr>
235<tr>
236 <td width="15%" align="right" valign="top" class="summary">
237 <span class="summary-type">&nbsp;</span>
238 </td><td class="summary">
239 <table width="100%" cellpadding="0" cellspacing="0" border="0">
240 <tr>
241 <td><span class="summary-sig"><a href="TestON.core.ast-module.html#increment_lineno" class="summary-sig-name">increment_lineno</a>(<span class="summary-sig-arg">node</span>,
242 <span class="summary-sig-arg">n</span>=<span class="summary-sig-default">1</span>)</span><br />
243 Increment the line number of each node in the tree starting at *node*
244 by *n*.</td>
245 <td align="right" valign="top">
246 <span class="codelink"><a href="TestON.core.ast-pysrc.html#increment_lineno">source&nbsp;code</a></span>
247
248 </td>
249 </tr>
250 </table>
251
252 </td>
253 </tr>
254<tr>
255 <td width="15%" align="right" valign="top" class="summary">
256 <span class="summary-type">&nbsp;</span>
257 </td><td class="summary">
258 <table width="100%" cellpadding="0" cellspacing="0" border="0">
259 <tr>
260 <td><span class="summary-sig"><a name="iter_fields"></a><span class="summary-sig-name">iter_fields</span>(<span class="summary-sig-arg">node</span>)</span><br />
261 Yield a tuple of ``(fieldname, value)`` for each field in
262 ``node._fields`` that is present on *node*.</td>
263 <td align="right" valign="top">
264 <span class="codelink"><a href="TestON.core.ast-pysrc.html#iter_fields">source&nbsp;code</a></span>
265
266 </td>
267 </tr>
268 </table>
269
270 </td>
271 </tr>
272<tr>
273 <td width="15%" align="right" valign="top" class="summary">
274 <span class="summary-type">&nbsp;</span>
275 </td><td class="summary">
276 <table width="100%" cellpadding="0" cellspacing="0" border="0">
277 <tr>
278 <td><span class="summary-sig"><a name="iter_child_nodes"></a><span class="summary-sig-name">iter_child_nodes</span>(<span class="summary-sig-arg">node</span>)</span><br />
279 Yield all direct child nodes of *node*, that is, all fields that are
280 nodes and all items of fields that are lists of nodes.</td>
281 <td align="right" valign="top">
282 <span class="codelink"><a href="TestON.core.ast-pysrc.html#iter_child_nodes">source&nbsp;code</a></span>
283
284 </td>
285 </tr>
286 </table>
287
288 </td>
289 </tr>
290<tr>
291 <td width="15%" align="right" valign="top" class="summary">
292 <span class="summary-type">&nbsp;</span>
293 </td><td class="summary">
294 <table width="100%" cellpadding="0" cellspacing="0" border="0">
295 <tr>
296 <td><span class="summary-sig"><a href="TestON.core.ast-module.html#get_docstring" class="summary-sig-name">get_docstring</a>(<span class="summary-sig-arg">node</span>,
297 <span class="summary-sig-arg">clean</span>=<span class="summary-sig-default">True</span>)</span><br />
298 Return the docstring for the given node or None if no docstring can
299 be found.</td>
300 <td align="right" valign="top">
301 <span class="codelink"><a href="TestON.core.ast-pysrc.html#get_docstring">source&nbsp;code</a></span>
302
303 </td>
304 </tr>
305 </table>
306
307 </td>
308 </tr>
309<tr>
310 <td width="15%" align="right" valign="top" class="summary">
311 <span class="summary-type">&nbsp;</span>
312 </td><td class="summary">
313 <table width="100%" cellpadding="0" cellspacing="0" border="0">
314 <tr>
315 <td><span class="summary-sig"><a href="TestON.core.ast-module.html#walk" class="summary-sig-name">walk</a>(<span class="summary-sig-arg">node</span>)</span><br />
316 Recursively yield all descendant nodes in the tree starting at *node*
317 (including *node* itself), in no specified order.</td>
318 <td align="right" valign="top">
319 <span class="codelink"><a href="TestON.core.ast-pysrc.html#walk">source&nbsp;code</a></span>
320
321 </td>
322 </tr>
323 </table>
324
325 </td>
326 </tr>
327</table>
328<!-- ==================== FUNCTION DETAILS ==================== -->
329<a name="section-FunctionDetails"></a>
330<table class="details" border="1" cellpadding="3"
331 cellspacing="0" width="100%" bgcolor="white">
332<tr bgcolor="#70b0f0" class="table-header">
333 <td colspan="2" class="table-header">
334 <table border="0" cellpadding="0" cellspacing="0" width="100%">
335 <tr valign="top">
336 <td align="left"><span class="table-header">Function Details</span></td>
337 <td align="right" valign="top"
338 ><span class="options">[<a href="#section-FunctionDetails"
339 class="privatelink" onclick="toggle_private();"
340 >hide private</a>]</span></td>
341 </tr>
342 </table>
343 </td>
344</tr>
345</table>
346<a name="parse"></a>
347<div>
348<table class="details" border="1" cellpadding="3"
349 cellspacing="0" width="100%" bgcolor="white">
350<tr><td>
351 <table width="100%" cellpadding="0" cellspacing="0" border="0">
352 <tr valign="top"><td>
353 <h3 class="epydoc"><span class="sig"><span class="sig-name">parse</span>(<span class="sig-arg">source</span>,
354 <span class="sig-arg">filename</span>=<span class="sig-default">'&lt;unknown&gt;'</span>,
355 <span class="sig-arg">mode</span>=<span class="sig-default">'exec'</span>)</span>
356 </h3>
357 </td><td align="right" valign="top"
358 ><span class="codelink"><a href="TestON.core.ast-pysrc.html#parse">source&nbsp;code</a></span>&nbsp;
359 </td>
360 </tr></table>
361
362 <p>Parse the source into an AST node. Equivalent to compile(source,
363 filename, mode, PyCF_ONLY_AST).</p>
364 <dl class="fields">
365 </dl>
366</td></tr></table>
367</div>
368<a name="literal_eval"></a>
369<div>
370<table class="details" border="1" cellpadding="3"
371 cellspacing="0" width="100%" bgcolor="white">
372<tr><td>
373 <table width="100%" cellpadding="0" cellspacing="0" border="0">
374 <tr valign="top"><td>
375 <h3 class="epydoc"><span class="sig"><span class="sig-name">literal_eval</span>(<span class="sig-arg">node_or_string</span>)</span>
376 </h3>
377 </td><td align="right" valign="top"
378 ><span class="codelink"><a href="TestON.core.ast-pysrc.html#literal_eval">source&nbsp;code</a></span>&nbsp;
379 </td>
380 </tr></table>
381
382 <p>Safely evaluate an expression node or a string containing a Python
383 expression. The string or node provided may only consist of the
384 following Python literal structures: strings, numbers, tuples, lists,
385 dicts, booleans, and None.</p>
386 <dl class="fields">
387 </dl>
388</td></tr></table>
389</div>
390<a name="dump"></a>
391<div>
392<table class="details" border="1" cellpadding="3"
393 cellspacing="0" width="100%" bgcolor="white">
394<tr><td>
395 <table width="100%" cellpadding="0" cellspacing="0" border="0">
396 <tr valign="top"><td>
397 <h3 class="epydoc"><span class="sig"><span class="sig-name">dump</span>(<span class="sig-arg">node</span>,
398 <span class="sig-arg">annotate_fields</span>=<span class="sig-default">True</span>,
399 <span class="sig-arg">include_attributes</span>=<span class="sig-default">False</span>)</span>
400 </h3>
401 </td><td align="right" valign="top"
402 ><span class="codelink"><a href="TestON.core.ast-pysrc.html#dump">source&nbsp;code</a></span>&nbsp;
403 </td>
404 </tr></table>
405
406 <p>Return a formatted dump of the tree in *node*. This is mainly useful
407 for debugging purposes. The returned string will show the names and the
408 values for fields. This makes the code impossible to evaluate, so if
409 evaluation is wanted *annotate_fields* must be set to False. Attributes
410 such as line numbers and column offsets are not dumped by default. If
411 this is wanted, *include_attributes* can be set to True.</p>
412 <dl class="fields">
413 </dl>
414</td></tr></table>
415</div>
416<a name="fix_missing_locations"></a>
417<div>
418<table class="details" border="1" cellpadding="3"
419 cellspacing="0" width="100%" bgcolor="white">
420<tr><td>
421 <table width="100%" cellpadding="0" cellspacing="0" border="0">
422 <tr valign="top"><td>
423 <h3 class="epydoc"><span class="sig"><span class="sig-name">fix_missing_locations</span>(<span class="sig-arg">node</span>)</span>
424 </h3>
425 </td><td align="right" valign="top"
426 ><span class="codelink"><a href="TestON.core.ast-pysrc.html#fix_missing_locations">source&nbsp;code</a></span>&nbsp;
427 </td>
428 </tr></table>
429
430 <p>When you compile a node tree with compile(), the compiler expects
431 lineno and col_offset attributes for every node that supports them. This
432 is rather tedious to fill in for generated nodes, so this helper adds
433 these attributes recursively where not already set, by setting them to
434 the values of the parent node. It works recursively starting at
435 *node*.</p>
436 <dl class="fields">
437 </dl>
438</td></tr></table>
439</div>
440<a name="increment_lineno"></a>
441<div>
442<table class="details" border="1" cellpadding="3"
443 cellspacing="0" width="100%" bgcolor="white">
444<tr><td>
445 <table width="100%" cellpadding="0" cellspacing="0" border="0">
446 <tr valign="top"><td>
447 <h3 class="epydoc"><span class="sig"><span class="sig-name">increment_lineno</span>(<span class="sig-arg">node</span>,
448 <span class="sig-arg">n</span>=<span class="sig-default">1</span>)</span>
449 </h3>
450 </td><td align="right" valign="top"
451 ><span class="codelink"><a href="TestON.core.ast-pysrc.html#increment_lineno">source&nbsp;code</a></span>&nbsp;
452 </td>
453 </tr></table>
454
455 <p>Increment the line number of each node in the tree starting at *node*
456 by *n*. This is useful to &quot;move code&quot; to a different location
457 in a file.</p>
458 <dl class="fields">
459 </dl>
460</td></tr></table>
461</div>
462<a name="get_docstring"></a>
463<div>
464<table class="details" border="1" cellpadding="3"
465 cellspacing="0" width="100%" bgcolor="white">
466<tr><td>
467 <table width="100%" cellpadding="0" cellspacing="0" border="0">
468 <tr valign="top"><td>
469 <h3 class="epydoc"><span class="sig"><span class="sig-name">get_docstring</span>(<span class="sig-arg">node</span>,
470 <span class="sig-arg">clean</span>=<span class="sig-default">True</span>)</span>
471 </h3>
472 </td><td align="right" valign="top"
473 ><span class="codelink"><a href="TestON.core.ast-pysrc.html#get_docstring">source&nbsp;code</a></span>&nbsp;
474 </td>
475 </tr></table>
476
477 <p>Return the docstring for the given node or None if no docstring can be
478 found. If the node provided does not have docstrings a TypeError will be
479 raised.</p>
480 <dl class="fields">
481 </dl>
482</td></tr></table>
483</div>
484<a name="walk"></a>
485<div>
486<table class="details" border="1" cellpadding="3"
487 cellspacing="0" width="100%" bgcolor="white">
488<tr><td>
489 <table width="100%" cellpadding="0" cellspacing="0" border="0">
490 <tr valign="top"><td>
491 <h3 class="epydoc"><span class="sig"><span class="sig-name">walk</span>(<span class="sig-arg">node</span>)</span>
492 </h3>
493 </td><td align="right" valign="top"
494 ><span class="codelink"><a href="TestON.core.ast-pysrc.html#walk">source&nbsp;code</a></span>&nbsp;
495 </td>
496 </tr></table>
497
498 <p>Recursively yield all descendant nodes in the tree starting at *node*
499 (including *node* itself), in no specified order. This is useful if you
500 only want to modify nodes in place and don't care about the context.</p>
501 <dl class="fields">
502 </dl>
503</td></tr></table>
504</div>
505<br />
506<!-- ==================== NAVIGATION BAR ==================== -->
507<table class="navbar" border="0" width="100%" cellpadding="0"
508 bgcolor="#a0c0ff" cellspacing="0">
509 <tr valign="middle">
510 <!-- Home link -->
511 <th>&nbsp;&nbsp;&nbsp;<a
512 href="TestON-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
513
514 <!-- Tree link -->
515 <th>&nbsp;&nbsp;&nbsp;<a
516 href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
517
518 <!-- Index link -->
519 <th>&nbsp;&nbsp;&nbsp;<a
520 href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
521
522 <!-- Help link -->
523 <th>&nbsp;&nbsp;&nbsp;<a
524 href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
525
526 <th class="navbar" width="100%"></th>
527 </tr>
528</table>
529<table border="0" cellpadding="0" cellspacing="0" width="100%%">
530 <tr>
531 <td align="left" class="footer">
532 Generated by Epydoc 3.0.1 on Mon Mar 11 12:56:26 2013
533 </td>
534 <td align="right" class="footer">
535 <a target="mainFrame" href="http://epydoc.sourceforge.net"
536 >http://epydoc.sourceforge.net</a>
537 </td>
538 </tr>
539</table>
540
541<script type="text/javascript">
542 <!--
543 // Private objects are initially displayed (because if
544 // javascript is turned off then we want them to be
545 // visible); but by default, we want to hide them. So hide
546 // them unless we have a cookie that says to show them.
547 checkCookie();
548 // -->
549</script>
550</body>
551</html>