`ast`

The Python ast module lets you work with Abstract Syntax Trees (ASTs), which represent the structure of Python source code. You can use it for introspection, static analysis, and programmatic code transformations.

Here’s a quick example:

>>> import ast

>>> tree = ast.parse("x = 1")
>>> print(ast.dump(tree, indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='x', ctx=Store())],
            value=Constant(value=1))])

Key Features

Parses Python source code into an Abstract Syntax Tree
Generates ASTs directly from compiled code with the ast.PyCF_ONLY_AST flag
Provides tools for traversing and modifying ASTs
Includes base classes for visiting and transforming nodes
Preserves and updates source-location metadata (line and column information)
Can compile ASTs back into executable code
Can convert ASTs back into Python source code (but not original formatting or comments)

Frequently Used Classes and Functions

Object	Type	Description
`ast.parse()`	Function	Parses source code into an AST
`ast.dump()`	Function	Returns a string representation of an AST
`ast.unparse()`	Function	Converts an AST back to Python source code
`ast.literal_eval()`	Function	Evaluates a string containing only Python literals (doesn’t execute code, but untrusted input can cause denial-of-service)
`ast.walk()`	Function	Recursively yields all descendant nodes
`ast.fix_missing_locations()`	Function	Fills in missing line number and column info
`ast.NodeVisitor`	Class	Provides a base class for traversing AST nodes
`ast.NodeTransformer`	Class	Provides a base class for modifying AST nodes
`ast.Expression`	Class	Represents the root node for single expressions (from `mode='eval'`)

Examples

Modify an AST to change variable names:

>>> import ast

>>> class RenameVariables(ast.NodeTransformer):
...     def visit_Name(self, node):
...         if node.id == "x":
...             node.id = "y"
...         return node
...

>>> tree = ast.parse("x = 2")
>>> new_tree = RenameVariables().visit(tree)
>>> print(ast.dump(new_tree, indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='y', ctx=Store())],
            value=Constant(value=2))])

Compile and execute an AST:

>>> import ast

>>> tree = ast.parse("print(\"Hello, World!\")")
>>> code = compile(tree, filename="<ast>", mode="exec")
>>> exec(code)
Hello, World!

Common Use Cases

The most common tasks for ast include:

Analyzing code for static analysis tools (such as linters and type checkers)
Extracting structure for documentation and dependency analysis (such as imports)
Refactoring code programmatically (such as renaming symbols or rewriting APIs)
Instrumenting code automatically (such as inserting logging or timing)
Generating code from templates or other inputs
Building code formatters, transpilers, and domain-specific languages

Real-World Example

Suppose you want to programmatically rename all occurrences of a variable in a script:

>>> import ast

>>> class VariableRenamer(ast.NodeTransformer):
...     def __init__(self, old_name, new_name):
...         self.old_name = old_name
...         self.new_name = new_name
...     def visit_Name(self, node):
...         if node.id == self.old_name:
...             node.id = self.new_name
...         return node
...

>>> source_code = "x = 1\nprint(x)"
>>> tree = ast.parse(source_code)
>>> renamer = VariableRenamer("x", "y")
>>> new_tree = renamer.visit(tree)
>>> ast.fix_missing_locations(new_tree)
>>> new_code = compile(new_tree, filename="<ast>", mode="exec")
>>> exec(new_code)
1

In this example, the ast module was used to rename a variable in the source code and execute the modified code. Note the use of ast.fix_missing_locations() to ensure the modified AST has proper line number information before compilation.

Tutorial

Your Guide to the CPython Source Code

In this detailed Python tutorial, you'll explore the CPython source code. By following this step-by-step walkthrough, you'll take a deep dive into how the CPython compiler works and how your Python code gets executed.

advanced python

For additional information on related topics, take a look at the following resources: