Introduction to GAST: Python’s Abstract Syntax Tree Library

The GAST library (Generic Abstract Syntax Trees for Python) is a powerful Python module that provides functionality for analyzing, modifying, and transforming Python code structure at the abstract syntax tree (AST) level. If you work in areas such as code analysis, static analysis, tooling development, or program transformation, GAST is indispensable. In this guide, we will dive into dozens of its useful APIs with examples.

What is GAST?

GAST is a Python library that extends the standard Python ast module to handle code in a generic format, making it more versatile and capable of supporting multiple Python versions. It allows you to interact with code at a granular, structural level.

Installing GAST

To get started with GAST, you can easily install it using pip:

  pip install gast

Key APIs of the GAST Library

1. gast.parse()

The gast.parse() function parses Python code into an abstract syntax tree (AST) representation.

Example:

  import gast
  
  code = "x = 42"
  ast_tree = gast.parse(code)
  print(gast.dump(ast_tree))

2. gast.dump()

The gast.dump() function converts an AST back into a string representation, making it easier to inspect.

Example:

  import gast
  
  ast_tree = gast.parse("x = 42")
  ast_structure = gast.dump(ast_tree)
  print(ast_structure)

3. Traversing AST Nodes with gast.NodeVisitor

The gast.NodeVisitor base class allows you to traverse and interact with AST nodes.

Example:

  import gast
  
  class PrintAssignments(gast.NodeVisitor):
      def visit_Assign(self, node):
          print("Assignment detected:", gast.dump(node))
          self.generic_visit(node)
  
  code = "x = 42\ny = x + 1"
  tree = gast.parse(code)
  visitor = PrintAssignments()
  visitor.visit(tree)

4. Modifying AST Nodes with gast.NodeTransformer

The gast.NodeTransformer base class allows you to modify AST nodes dynamically.

Example:

  import gast
  
  class IncrementNumbers(gast.NodeTransformer):
      def visit_Num(self, node):
          node.n += 1
          return node
  
  code = "x = 1 + 2"
  tree = gast.parse(code)
  transformer = IncrementNumbers()
  modified_tree = transformer.visit(tree)
  print(gast.dump(modified_tree))

5. Converting Between AST and GAST

The gast library provides utility functions to convert between Python’s standard ast module and gast nodes.

Example:

  import gast
  import ast
  
  # Python AST to GAST
  python_ast = ast.parse("x = 42")
  gast_ast = gast.ast_to_gast(python_ast)
  print(gast.dump(gast_ast))
  
  # GAST to Python AST
  converted_back = gast.gast_to_ast(gast_ast)
  print(ast.dump(converted_back))

Building a Simple App with GAST

Let’s put everything together and create a small app that analyzes Python code to count the number of function definitions and assignments.

App Example:

  import gast
  
  class CodeAnalyzer(gast.NodeVisitor):
      def __init__(self):
          self.function_count = 0
          self.assignment_count = 0
      
      def visit_FunctionDef(self, node):
          self.function_count += 1
          self.generic_visit(node)
      
      def visit_Assign(self, node):
          self.assignment_count += 1
          self.generic_visit(node)
  
  code = '''
  def foo():
      x = 10
      return x
  
  def bar(y):
      return y + 1
  
  z = foo()
  '''
  
  tree = gast.parse(code)
  analyzer = CodeAnalyzer()
  analyzer.visit(tree)
  
  print(f"Number of functions: {analyzer.function_count}")
  print(f"Number of assignments: {analyzer.assignment_count}")

The output for the above code will be:

  Number of functions: 2
  Number of assignments: 3

Conclusion

GAST is a versatile library that offers tools for working with Python’s abstract syntax trees across multiple Python versions. By leveraging its powerful APIs, you can create syntax-aware applications, perform code analysis, and automate code transformation tasks efficiently.

We hope this guide was helpful in showcasing the capabilities of GAST from basic usage to building a small application. Explore further and unlock new potential in your projects!