Reading a Python AST: A Practical Guide

When Python runs your file it doesn't execute the text. It first tokenizes it, then parses those tokens into an abstract syntax tree — a hierarchy of typed nodes (Module, FunctionDef, Assign, Call, Constant…) — and finally compiles that tree to bytecode. The ast module hands you that exact tree.

import os

API_KEY = "sk-live-abc123"

def greet(name):
    msg = f"hello {name}"
    return msg.upper()

print(greet("mithun"))

ast.parse(source) returns the tree; ast.dump(node, indent=2) prints it. Here's the greet function as the parser sees it — note the f-string becomes a JoinedStr of a constant plus a FormattedValue:

FunctionDef(
  name='greet',
  args=arguments(
    args=[
      arg(arg='name')]),
  body=[
    Assign(
      targets=[Name(id='msg', ctx=Store())],
      value=JoinedStr(
        values=[
          Constant(value='hello '),
          FormattedValue(
            value=Name(id='name', ctx=Load()),
            conversion=-1)])),
    Return(
      value=Call(
        func=Attribute(
          value=Name(id='msg', ctx=Load()),
          attr='upper')))])

Every node carries its children and, usually, its lineno/col_offset. That structure is the whole advantage: you're no longer guessing where a string ends or whether upper is a method call — the tree tells you exactly.

ast.walk(tree) yields every node, in no particular order — perfect for "find all X" tasks. Every string and number literal is a Constant node, so pulling every string out of a file is one comprehension:

strings = [n.value for n in ast.walk(tree)
           if isinstance(n, ast.Constant) and isinstance(n.value, str)]

# real output:
['sk-live-abc123', 'hello ', 'mithun']

For anything beyond a flat search, subclass ast.NodeVisitor and define visit_<NodeType> methods. The visitor dispatches each node to the matching method. Here's one that reports every function definition and call site with its line number:

class V(ast.NodeVisitor):
    def visit_FunctionDef(self, node):
        args = [a.arg for a in node.args.args]
        print(f"def {node.name}({', '.join(args)}) @ line {node.lineno}")
        self.generic_visit(node)
    def visit_Call(self, node):
        name = getattr(node.func, 'id', getattr(node.func, 'attr', '?'))
        print(f"call {name}() @ line {node.lineno}")
        self.generic_visit(node)

V().visit(tree)

def greet(name) @ line 5
call upper() @ line 7
call print() @ line 9
call greet() @ line 9

Always call self.generic_visit(node) if you want the walk to continue into a node's children. This is the pattern real linters use to implement rules like "no bare except" or "function too long."

To *change* code, use ast.NodeTransformer — its visit_* methods return a node to replace the original. Then ast.unparse(tree) (Python 3.9+) turns the modified tree back into source. Here's a transformer that redacts every string literal, and the source it produces:

class Redact(ast.NodeTransformer):
    def visit_Constant(self, node):
        if isinstance(node.value, str):
            return ast.copy_location(ast.Constant(value='<redacted>'), node)
        return node

new = ast.fix_missing_locations(Redact().visit(ast.parse(SRC)))
print(ast.unparse(new))

import os
API_KEY = '<redacted>'

def greet(name):
    msg = f'<redacted>{name}'
    return msg.upper()
print(greet('<redacted>'))

This redact-and-unparse loop is, in miniature, exactly how an obfuscator works: it parses to an AST, rewrites nodes (rename identifiers, encrypt string constants, restructure), and unparses the result. Our Python Obfuscator does this at scale — see AST-based obfuscation and protecting Python source code.

• Linters & formatters (Ruff, Black, flake8) parse to an AST to apply rules and reprint code — never regex.
• Obfuscators & minifiers rewrite the tree (rename, encrypt, strip) then unparse.
• Codemods & migrations (e.g. library API upgrades) transform many files reliably via NodeTransformer.
• Security scanners walk the tree to flag dangerous calls or hard-coded secrets.
• Analysis — count complexity, find dead code, map imports.

The fastest way to build intuition is to *see* the tree for your own code. Paste a snippet into our free Python AST Viewer to explore the node structure interactively, and run experiments in the online Python compiler.