84 lines
3.3 KiB
ReStructuredText
84 lines
3.3 KiB
ReStructuredText
.. _ast:
|
|
|
|
Abstract Syntax Trees
|
|
=====================
|
|
|
|
.. module:: _ast
|
|
:synopsis: Abstract Syntax Tree classes.
|
|
|
|
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
|
|
|
|
|
|
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.
|
|
|
|
An abstract syntax tree can be generated by passing :data:`_ast.PyCF_ONLY_AST`
|
|
as a flag to the :func:`compile` builtin function. The result will be a tree of
|
|
objects whose classes all inherit from :class:`_ast.AST`.
|
|
|
|
A modified abstract syntax tree can be compiled into a Python code object using
|
|
the built-in :func:`compile` function.
|
|
|
|
The actual classes are derived from the ``Parser/Python.asdl`` file, which is
|
|
reproduced below. There is one class defined for each left-hand side symbol in
|
|
the abstract grammar (for example, ``_ast.stmt`` or ``_ast.expr``). In addition,
|
|
there is one class defined for each constructor on the right-hand side; these
|
|
classes inherit from the classes for the left-hand side trees. For example,
|
|
``_ast.BinOp`` inherits from ``_ast.expr``. For production rules with
|
|
alternatives (aka "sums"), the left-hand side class is abstract: only instances
|
|
of specific constructor nodes are ever created.
|
|
|
|
Each concrete class has an attribute ``_fields`` which gives the names of all
|
|
child nodes.
|
|
|
|
Each instance of a concrete class has one attribute for each child node, of the
|
|
type as defined in the grammar. For example, ``_ast.BinOp`` instances have an
|
|
attribute ``left`` of type ``_ast.expr``. Instances of ``_ast.expr`` and
|
|
``_ast.stmt`` subclasses also have lineno and col_offset attributes. The lineno
|
|
is the line number of source text (1 indexed so the first line is line 1) and
|
|
the col_offset is the utf8 byte offset of the first token that generated the
|
|
node. The utf8 offset is recorded because the parser uses utf8 internally.
|
|
|
|
If these attributes are marked as optional in the grammar (using a question
|
|
mark), the value might be ``None``. If the attributes can have zero-or-more
|
|
values (marked with an asterisk), the values are represented as Python lists.
|
|
All possible attributes must be present and have valid values when compiling an
|
|
AST with :func:`compile`.
|
|
|
|
The constructor of a class ``_ast.T`` parses their arguments as follows:
|
|
|
|
* If there are positional arguments, there must be as many as there are items in
|
|
``T._fields``; they will be assigned as attributes of these names.
|
|
* If there are keyword arguments, they will set the attributes of the same names
|
|
to the given values.
|
|
|
|
For example, to create and populate a ``UnaryOp`` node, you could use ::
|
|
|
|
node = _ast.UnaryOp()
|
|
node.op = _ast.USub()
|
|
node.operand = _ast.Num()
|
|
node.operand.n = 5
|
|
node.operand.lineno = 0
|
|
node.operand.col_offset = 0
|
|
node.lineno = 0
|
|
node.col_offset = 0
|
|
|
|
or the more compact ::
|
|
|
|
node = _ast.UnaryOp(_ast.USub(), _ast.Num(5, lineno=0, col_offset=0),
|
|
lineno=0, col_offset=0)
|
|
|
|
|
|
|
|
Abstract Grammar
|
|
----------------
|
|
|
|
The module defines a string constant ``__version__`` which is the decimal
|
|
subversion revision number of the file shown below.
|
|
|
|
The abstract grammar is currently defined as follows:
|
|
|
|
.. literalinclude:: ../../Parser/Python.asdl
|