Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Standard Library: Concurrency, Network and Tools

The ast module

Reference for Python's ast module: ast.parse, literal_eval, dump, walk, NodeVisitor and NodeTransformer, unparse, and how to analyze code without running it.

The ast module turns Python source text into an abstract syntax tree: a tree of node objects such as Assign, Call and Name that describe the structure of the code. You can inspect the tree, modify it, turn it back into source, or compile it and run it.

Linters, formatters, test frameworks and documentation tools are built on it. For ordinary programs its most popular function is ast.literal_eval(), a safe way to read Python literals from a string.

Python
import ast

tree = ast.parse("total = price * 2")
print(ast.dump(tree))

Try it

Python Parsing and walking a tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python literal_eval and a NodeTransformer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Syntax

Python
ast.parse(source, filename="<unknown>", mode="exec", *, type_comments=False, feature_version=None)
ast.literal_eval(node_or_string)
ast.dump(node, annotate_fields=True, include_attributes=False, *, indent=None)
ast.unparse(node)
ast.walk(node)
ast.get_docstring(node, clean=True)
ast.fix_missing_locations(node)
Name Description
source Source text (or bytes) to parse.
mode "exec" for a module (default), "eval" for a single expression, "single" for one interactive statement, "func_type" for a type comment signature.
node_or_string A string or an ast expression node containing only literals.
indent Number or string used to pretty-print dump() output on several lines.
clean For get_docstring(): remove common leading indentation.

Return value: parse() returns a Module (or Expression, Interactive) node. literal_eval() returns the Python value. dump() and unparse() return strings; walk() is a generator of every node below the given one; get_docstring() returns a string or None.

Raises: SyntaxError from parse(). ValueError (sometimes TypeError, SyntaxError, MemoryError or RecursionError for odd or huge input) from literal_eval().

Usage notes

  • literal_eval() is not a full sandbox. It accepts strings, bytes, numbers, tuples, lists, dicts, sets, booleans, None and Ellipsis, plus unary minus and simple complex numbers. It never calls functions, so it is a far better choice than eval() for untrusted data, but for very large or deeply nested input it can still use a lot of CPU and memory. Prefer json when you control the format.
  • Two traversal styles. ast.walk() visits every node with no order guarantee beyond breadth-first. NodeVisitor calls visit_<ClassName> methods and descends only if you call self.generic_visit(node).
  • Transformers must return a node. In a NodeTransformer, returning None deletes the node, and returning a list replaces it with several. After editing, call ast.fix_missing_locations() so new nodes get line numbers.
  • Compiling a tree: compile(tree, "<name>", "exec") produces a code object you can run with exec(). The tree must contain a Module for "exec" and an Expression for "eval".
  • ast.unparse() (3.9+) regenerates valid code but not your original formatting or comments, because comments are not part of the tree.
  • The node classes change over time. ast.Constant replaced Num, Str and NameConstant, which were deprecated in 3.8 and removed in 3.14. Newer syntax adds nodes such as Match (3.10) and TypeAlias (3.12), so tools should be tested on each Python version they support.
  • indent= in dump() (3.9+) makes large trees readable. Use include_attributes=True to see line and column numbers.
  • Parsing is safe, running is not. Reading code with ast.parse() never executes it; exec() on the compiled result does.