Doc/library/_ast.rst

   1 .. _ast:
   2
   3 Abstract Syntax Trees
   4 =====================
   5
   6 .. module:: _ast
   7    :synopsis: Abstract Syntax Tree classes.
   8
   9 .. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
  10
  11
  12 .. versionadded:: 2.5
  13
  14 The ``_ast`` module helps Python applications to process trees of the Python
  15 abstract syntax grammar.  The abstract syntax itself might change with each
  16 Python release; this module helps to find out programmatically what the current
  17 grammar looks like.
  18
  19 An abstract syntax tree can be generated by passing :data:`_ast.PyCF_ONLY_AST`
  20 as a flag to the :func:`compile` builtin function. The result will be a tree of
  21 objects whose classes all inherit from :class:`_ast.AST`.
  22
  23 A modified abstract syntax tree can be compiled into a Python code object using
  24 the built-in :func:`compile` function.
  25
  26 The actual classes are derived from the ``Parser/Python.asdl`` file, which is
  27 reproduced below. There is one class defined for each left-hand side symbol in
  28 the abstract grammar (for example, ``_ast.stmt`` or ``_ast.expr``). In addition,
  29 there is one class defined for each constructor on the right-hand side; these
  30 classes inherit from the classes for the left-hand side trees. For example,
  31 ``_ast.BinOp`` inherits from ``_ast.expr``. For production rules with
  32 alternatives (aka "sums"), the left-hand side class is abstract: only instances
  33 of specific constructor nodes are ever created.
  34
  35 Each concrete class has an attribute ``_fields`` which gives the names of all
  36 child nodes.
  37
  38 Each instance of a concrete class has one attribute for each child node, of the
  39 type as defined in the grammar. For example, ``_ast.BinOp`` instances have an
  40 attribute ``left`` of type ``_ast.expr``.   Instances of ``_ast.expr`` and
  41 ``_ast.stmt`` subclasses also have lineno and col_offset attributes.  The lineno
  42 is the line number of source text (1 indexed so the first line is line 1) and
  43 the col_offset is the utf8 byte offset of the first token that generated the
  44 node.  The utf8 offset is recorded because the parser uses utf8 internally.
  45
  46 If these attributes are marked as optional in the grammar (using a question
  47 mark), the value might be ``None``. If the attributes can have zero-or-more
  48 values (marked with an asterisk), the values are represented as Python lists.
  49 All possible attributes must be present and have valid values when compiling an
  50 AST with :func:`compile`.
  51
  52 The constructor of a class ``_ast.T`` parses their arguments as follows:
  53
  54 * If there are positional arguments, there must be as many as there are items in
  55   ``T._fields``; they will be assigned as attributes of these names.
  56 * If there are keyword arguments, they will set the attributes of the same names
  57   to the given values.
  58
  59 For example, to create and populate a ``UnaryOp`` node, you could use ::
  60
  61    node = _ast.UnaryOp()
  62    node.op = _ast.USub()
  63    node.operand = _ast.Num()
  64    node.operand.n = 5
  65    node.operand.lineno = 0
  66    node.operand.col_offset = 0
  67    node.lineno = 0
  68    node.col_offset = 0
  69
  70 or the more compact ::
  71
  72    node = _ast.UnaryOp(_ast.USub(), _ast.Num(5, lineno=0, col_offset=0),
  73                        lineno=0, col_offset=0)
  74
  75
  76
  77 Abstract Grammar
  78 ----------------
  79
  80 The module defines a string constant ``__version__`` which is the decimal
  81 subversion revision number of the file shown below.
  82
  83 The abstract grammar is currently defined as follows:
  84
  85 .. literalinclude:: ../../Parser/Python.asdl