AST Tools

Common errors

• ModuleNotFoundError: No module named 'ast_tools.mutable_ast'

  cause Attempting to import a class or function directly from the top-level `ast_tools` package when it resides in a submodule.
  fix Always use the full submodule path, e.g., `from ast_tools.mutable_ast import MutableAST` instead of `from ast_tools import MutableAST`.

• AttributeError: 'FunctionDef' object has no attribute 'lineno' (or similar for 'col_offset', 'end_lineno')

  cause Attempting to `compile()` or `eval()` an AST where newly created or modified `ast` nodes lack `lineno` and `col_offset` attributes. This is common when manually creating nodes without `ast.fix_missing_locations`.
  fix After any manual creation or significant modification of AST nodes, apply `ast.fix_missing_locations(your_root_ast_node)` to automatically populate these attributes before attempting to compile or evaluate the AST.

Warnings

• gotcha ast-tools builds upon Python's standard `ast` module. A solid understanding of the `ast` module, AST node types, and AST traversal/manipulation patterns is highly recommended for effective use of ast-tools.
  Fix: Familiarize yourself with the `ast` module documentation and common AST manipulation techniques.
• gotcha When manually constructing or heavily modifying `ast` nodes (e.g., creating new `ast.Constant` or `ast.Name` nodes), you may need to call `ast.fix_missing_locations(node)` to ensure that line numbers and column offsets are correctly set. Without this, compiling the AST can lead to errors.
  Fix: Always run `ast.fix_missing_locations(your_modified_ast_root)` on any AST that you've manually constructed or altered significantly, before passing it to `compile()` or `eval_ast`.
• deprecated The project shows infrequent updates. While functional, it might not track the absolute latest Python AST changes or receive new features frequently. For critical projects, evaluate its long-term maintenance status.
  Fix: Monitor the GitHub repository for activity and consider contributing or forking if specific modern Python features require AST support not present. For critical applications, ensure thorough testing.

Install

• pip install ast-tools Install stable version

Imports

• MutableAST
  wrong:

  from ast_tools import MutableAST

  correct:

  from ast_tools.mutable_ast import MutableAST

  Classes are in specific submodules, not directly under the top-level package.
• function_to_ast
  wrong:

  from ast_tools import function_to_ast

  correct:

  from ast_tools.common import function_to_ast

  Helper functions like function_to_ast and eval_ast reside in the 'common' submodule.
• Visitor
  wrong:

  from ast_tools.visitor import Visitor

  correct:

  from ast_tools.stack_vm import Visitor

  The AST Visitor class is part of the 'stack_vm' submodule, which might not be immediately intuitive.

Quickstart

This quickstart demonstrates converting a Python function to a mutable AST, modifying a binary operation within it, and then executing the transformed AST as a new function. It highlights the use of `MutableAST` for in-place modifications and `function_to_ast` / `eval_ast` for conversion.

import ast
from ast_tools.mutable_ast import MutableAST
from ast_tools.common import function_to_ast, eval_ast

def add_func(a, b):
    c = a + b
    return c

# Convert a Python function to a mutable AST representation
m = MutableAST(add_func)

# Example transformation: change '+' to '-' in the binary operation
for node in m.body:
    if isinstance(node, ast.Assign):
        if isinstance(node.value, ast.BinOp) and isinstance(node.value.op, ast.Add):
            node.value.op = ast.Sub()
            break # Assuming only one assignment in this simple example

# Convert the modified AST back into a runnable function
sub_func = eval_ast(m.ast)

# Test the transformed function
result = sub_func(10, 5)
print(f"Original function output (if run directly): {add_func(10, 5)}")
print(f"Transformed function output: {result}") # Expected: 5