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.
import ast tree = ast.parse("total = price * 2") print(ast.dump(tree))
Try it
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.
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
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,NoneandEllipsis, plus unary minus and simple complex numbers. It never calls functions, so it is a far better choice thaneval()for untrusted data, but for very large or deeply nested input it can still use a lot of CPU and memory. Preferjsonwhen you control the format.- Two traversal styles.
ast.walk()visits every node with no order guarantee beyond breadth-first.NodeVisitorcallsvisit_<ClassName>methods and descends only if you callself.generic_visit(node). - Transformers must return a node. In a
NodeTransformer, returningNonedeletes the node, and returning a list replaces it with several. After editing, callast.fix_missing_locations()so new nodes get line numbers. - Compiling a tree:
compile(tree, "<name>", "exec")produces a code object you can run withexec(). The tree must contain aModulefor"exec"and anExpressionfor"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.ConstantreplacedNum,StrandNameConstant, which were deprecated in 3.8 and removed in 3.14. Newer syntax adds nodes such asMatch(3.10) andTypeAlias(3.12), so tools should be tested on each Python version they support. indent=indump()(3.9+) makes large trees readable. Useinclude_attributes=Trueto 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.