Back to index

python3.2  3.2.2
Classes | Functions
ast Namespace Reference

Classes

class  NodeVisitor
class  NodeTransformer

Functions

def parse
def literal_eval
def dump
def copy_location
def fix_missing_locations
def increment_lineno
def iter_fields
def iter_child_nodes
def get_docstring
def walk

Detailed Description

    ast
    ~~~

    The `ast` module helps Python applications to process trees of the Python
    abstract syntax grammar.  The abstract syntax itself might change with
    each Python release; this module helps to find out programmatically what
    the current grammar looks like and allows modifications of it.

    An abstract syntax tree can be generated by passing `ast.PyCF_ONLY_AST` as
    a flag to the `compile()` builtin function or by using the `parse()`
    function from this module.  The result will be a tree of objects whose
    classes all inherit from `ast.AST`.

    A modified abstract syntax tree can be compiled into a Python code object
    using the built-in `compile()` function.

    Additionally various helper functions are provided that make working with
    the trees simpler.  The main intention of the helper functions and this
    module in general is to provide an easy to use interface for libraries
    that work tightly with the python syntax (template engines for example).


    :copyright: Copyright 2008 by Armin Ronacher.
    :license: Python License.

Function Documentation

def ast.copy_location (   new_node,
  old_node 
)
Copy source location (`lineno` and `col_offset` attributes) from
*old_node* to *new_node* if possible, and return *new_node*.

Definition at line 120 of file ast.py.

00120 
00121 def copy_location(new_node, old_node):
00122     """
00123     Copy source location (`lineno` and `col_offset` attributes) from
00124     *old_node* to *new_node* if possible, and return *new_node*.
00125     """
00126     for attr in 'lineno', 'col_offset':
00127         if attr in old_node._attributes and attr in new_node._attributes \
00128            and hasattr(old_node, attr):
00129             setattr(new_node, attr, getattr(old_node, attr))
00130     return new_node
00131 

Here is the call graph for this function:

Here is the caller graph for this function:

def ast.dump (   node,
  annotate_fields = True,
  include_attributes = False 
)
Return a formatted dump of the tree in *node*.  This is mainly useful for
debugging purposes.  The returned string will show the names and the values
for fields.  This makes the code impossible to evaluate, so if evaluation is
wanted *annotate_fields* must be set to False.  Attributes such as line
numbers and column offsets are not dumped by default.  If this is wanted,
*include_attributes* can be set to True.

Definition at line 90 of file ast.py.

00090 
00091 def dump(node, annotate_fields=True, include_attributes=False):
00092     """
00093     Return a formatted dump of the tree in *node*.  This is mainly useful for
00094     debugging purposes.  The returned string will show the names and the values
00095     for fields.  This makes the code impossible to evaluate, so if evaluation is
00096     wanted *annotate_fields* must be set to False.  Attributes such as line
00097     numbers and column offsets are not dumped by default.  If this is wanted,
00098     *include_attributes* can be set to True.
00099     """
00100     def _format(node):
00101         if isinstance(node, AST):
00102             fields = [(a, _format(b)) for a, b in iter_fields(node)]
00103             rv = '%s(%s' % (node.__class__.__name__, ', '.join(
00104                 ('%s=%s' % field for field in fields)
00105                 if annotate_fields else
00106                 (b for a, b in fields)
00107             ))
00108             if include_attributes and node._attributes:
00109                 rv += fields and ', ' or ' '
00110                 rv += ', '.join('%s=%s' % (a, _format(getattr(node, a)))
00111                                 for a in node._attributes)
00112             return rv + ')'
00113         elif isinstance(node, list):
00114             return '[%s]' % ', '.join(_format(x) for x in node)
00115         return repr(node)
00116     if not isinstance(node, AST):
00117         raise TypeError('expected AST, got %r' % node.__class__.__name__)
00118     return _format(node)
00119 

Here is the call graph for this function:

Here is the caller graph for this function:

def ast.fix_missing_locations (   node)
When you compile a node tree with compile(), the compiler expects lineno and
col_offset attributes for every node that supports them.  This is rather
tedious to fill in for generated nodes, so this helper adds these attributes
recursively where not already set, by setting them to the values of the
parent node.  It works recursively starting at *node*.

Definition at line 132 of file ast.py.

00132 
00133 def fix_missing_locations(node):
00134     """
00135     When you compile a node tree with compile(), the compiler expects lineno and
00136     col_offset attributes for every node that supports them.  This is rather
00137     tedious to fill in for generated nodes, so this helper adds these attributes
00138     recursively where not already set, by setting them to the values of the
00139     parent node.  It works recursively starting at *node*.
00140     """
00141     def _fix(node, lineno, col_offset):
00142         if 'lineno' in node._attributes:
00143             if not hasattr(node, 'lineno'):
00144                 node.lineno = lineno
00145             else:
00146                 lineno = node.lineno
00147         if 'col_offset' in node._attributes:
00148             if not hasattr(node, 'col_offset'):
00149                 node.col_offset = col_offset
00150             else:
00151                 col_offset = node.col_offset
00152         for child in iter_child_nodes(node):
00153             _fix(child, lineno, col_offset)
00154     _fix(node, 1, 0)
00155     return node
00156 

Here is the call graph for this function:

Here is the caller graph for this function:

def ast.get_docstring (   node,
  clean = True 
)
Return the docstring for the given node or None if no docstring can
be found.  If the node provided does not have docstrings a TypeError
will be raised.

Definition at line 194 of file ast.py.

00194 
00195 def get_docstring(node, clean=True):
00196     """
00197     Return the docstring for the given node or None if no docstring can
00198     be found.  If the node provided does not have docstrings a TypeError
00199     will be raised.
00200     """
00201     if not isinstance(node, (FunctionDef, ClassDef, Module)):
00202         raise TypeError("%r can't have docstrings" % node.__class__.__name__)
00203     if node.body and isinstance(node.body[0], Expr) and \
00204        isinstance(node.body[0].value, Str):
00205         if clean:
00206             import inspect
00207             return inspect.cleandoc(node.body[0].value.s)
00208         return node.body[0].value.s
00209 

Here is the call graph for this function:

Here is the caller graph for this function:

def ast.increment_lineno (   node,
  n = 1 
)
Increment the line number of each node in the tree starting at *node* by *n*.
This is useful to "move code" to a different location in a file.

Definition at line 157 of file ast.py.

00157 
00158 def increment_lineno(node, n=1):
00159     """
00160     Increment the line number of each node in the tree starting at *node* by *n*.
00161     This is useful to "move code" to a different location in a file.
00162     """
00163     for child in walk(node):
00164         if 'lineno' in child._attributes:
00165             child.lineno = getattr(child, 'lineno', 0) + n
00166     return node
00167 

Here is the call graph for this function:

Here is the caller graph for this function:

def ast.iter_child_nodes (   node)
Yield all direct child nodes of *node*, that is, all fields that are nodes
and all items of fields that are lists of nodes.

Definition at line 180 of file ast.py.

00180 
00181 def iter_child_nodes(node):
00182     """
00183     Yield all direct child nodes of *node*, that is, all fields that are nodes
00184     and all items of fields that are lists of nodes.
00185     """
00186     for name, field in iter_fields(node):
00187         if isinstance(field, AST):
00188             yield field
00189         elif isinstance(field, list):
00190             for item in field:
00191                 if isinstance(item, AST):
00192                     yield item
00193 

Here is the call graph for this function:

Here is the caller graph for this function:

def ast.iter_fields (   node)
Yield a tuple of ``(fieldname, value)`` for each field in ``node._fields``
that is present on *node*.

Definition at line 168 of file ast.py.

00168 
00169 def iter_fields(node):
00170     """
00171     Yield a tuple of ``(fieldname, value)`` for each field in ``node._fields``
00172     that is present on *node*.
00173     """
00174     for field in node._fields:
00175         try:
00176             yield field, getattr(node, field)
00177         except AttributeError:
00178             pass
00179 

Here is the call graph for this function:

Here is the caller graph for this function:

def ast.literal_eval (   node_or_string)
Safely evaluate an expression node or a string containing a Python
expression.  The string or node provided may only consist of the following
Python literal structures: strings, bytes, numbers, tuples, lists, dicts,
sets, booleans, and None.

Definition at line 39 of file ast.py.

00039 
00040 def literal_eval(node_or_string):
00041     """
00042     Safely evaluate an expression node or a string containing a Python
00043     expression.  The string or node provided may only consist of the following
00044     Python literal structures: strings, bytes, numbers, tuples, lists, dicts,
00045     sets, booleans, and None.
00046     """
00047     _safe_names = {'None': None, 'True': True, 'False': False}
00048     if isinstance(node_or_string, str):
00049         node_or_string = parse(node_or_string, mode='eval')
00050     if isinstance(node_or_string, Expression):
00051         node_or_string = node_or_string.body
00052     def _convert(node):
00053         if isinstance(node, (Str, Bytes)):
00054             return node.s
00055         elif isinstance(node, Num):
00056             return node.n
00057         elif isinstance(node, Tuple):
00058             return tuple(map(_convert, node.elts))
00059         elif isinstance(node, List):
00060             return list(map(_convert, node.elts))
00061         elif isinstance(node, Set):
00062             return set(map(_convert, node.elts))
00063         elif isinstance(node, Dict):
00064             return dict((_convert(k), _convert(v)) for k, v
00065                         in zip(node.keys, node.values))
00066         elif isinstance(node, Name):
00067             if node.id in _safe_names:
00068                 return _safe_names[node.id]
00069         elif isinstance(node, UnaryOp) and \
00070              isinstance(node.op, (UAdd, USub)) and \
00071              isinstance(node.operand, (Num, UnaryOp, BinOp)):
00072             operand = _convert(node.operand)
00073             if isinstance(node.op, UAdd):
00074                 return + operand
00075             else:
00076                 return - operand
00077         elif isinstance(node, BinOp) and \
00078              isinstance(node.op, (Add, Sub)) and \
00079              isinstance(node.right, (Num, UnaryOp, BinOp)) and \
00080              isinstance(node.left, (Num, UnaryOp, BinOp)):
00081             left = _convert(node.left)
00082             right = _convert(node.right)
00083             if isinstance(node.op, Add):
00084                 return left + right
00085             else:
00086                 return left - right
00087         raise ValueError('malformed node or string: ' + repr(node))
00088     return _convert(node_or_string)
00089 

Here is the call graph for this function:

Here is the caller graph for this function:

def ast.parse (   source,
  filename = '<unknown>',
  mode = 'exec' 
)
Parse the source into an AST node.
Equivalent to compile(source, filename, mode, PyCF_ONLY_AST).

Definition at line 31 of file ast.py.

00031 
00032 def parse(source, filename='<unknown>', mode='exec'):
00033     """
00034     Parse the source into an AST node.
00035     Equivalent to compile(source, filename, mode, PyCF_ONLY_AST).
00036     """
00037     return compile(source, filename, mode, PyCF_ONLY_AST)
00038 

Here is the call graph for this function:

Here is the caller graph for this function:

def ast.walk (   node)
Recursively yield all descendant nodes in the tree starting at *node*
(including *node* itself), in no specified order.  This is useful if you
only want to modify nodes in place and don't care about the context.

Definition at line 210 of file ast.py.

00210 
00211 def walk(node):
00212     """
00213     Recursively yield all descendant nodes in the tree starting at *node*
00214     (including *node* itself), in no specified order.  This is useful if you
00215     only want to modify nodes in place and don't care about the context.
00216     """
00217     from collections import deque
00218     todo = deque([node])
00219     while todo:
00220         node = todo.popleft()
00221         todo.extend(iter_child_nodes(node))
00222         yield node
00223 

Here is the call graph for this function:

Here is the caller graph for this function: