{"id":9495,"library":"ast-tools","title":"AST Tools","description":"ast-tools is a Python library providing a toolbox for working with and transforming Python Abstract Syntax Trees (ASTs). It offers utilities like `MutableAST` for in-place modifications and a `Visitor` for traversing ASTs, simplifying complex AST manipulations. The current version is 0.1.8, and its release cadence is infrequent, with the last release in June 2022.","status":"active","version":"0.1.8","language":"en","source_language":"en","source_url":"https://github.com/leonardt/ast_tools","tags":["ast","abstract syntax tree","code generation","metaprogramming","code transformation"],"install":[{"cmd":"pip install ast-tools","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Classes are in specific submodules, not directly under the top-level package.","wrong":"from ast_tools import MutableAST","symbol":"MutableAST","correct":"from ast_tools.mutable_ast import MutableAST"},{"note":"Helper functions like function_to_ast and eval_ast reside in the 'common' submodule.","wrong":"from ast_tools import function_to_ast","symbol":"function_to_ast","correct":"from ast_tools.common import function_to_ast"},{"note":"The AST Visitor class is part of the 'stack_vm' submodule, which might not be immediately intuitive.","wrong":"from ast_tools.visitor import Visitor","symbol":"Visitor","correct":"from ast_tools.stack_vm import Visitor"}],"quickstart":{"code":"import ast\nfrom ast_tools.mutable_ast import MutableAST\nfrom ast_tools.common import function_to_ast, eval_ast\n\ndef add_func(a, b):\n    c = a + b\n    return c\n\n# Convert a Python function to a mutable AST representation\nm = MutableAST(add_func)\n\n# Example transformation: change '+' to '-' in the binary operation\nfor node in m.body:\n    if isinstance(node, ast.Assign):\n        if isinstance(node.value, ast.BinOp) and isinstance(node.value.op, ast.Add):\n            node.value.op = ast.Sub()\n            break # Assuming only one assignment in this simple example\n\n# Convert the modified AST back into a runnable function\nsub_func = eval_ast(m.ast)\n\n# Test the transformed function\nresult = sub_func(10, 5)\nprint(f\"Original function output (if run directly): {add_func(10, 5)}\")\nprint(f\"Transformed function output: {result}\") # Expected: 5\n","lang":"python","description":"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."},"warnings":[{"fix":"Familiarize yourself with the `ast` module documentation and common AST manipulation techniques.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"0.1.x and potentially future versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Always use the full submodule path, e.g., `from ast_tools.mutable_ast import MutableAST` instead of `from ast_tools import MutableAST`.","cause":"Attempting to import a class or function directly from the top-level `ast_tools` package when it resides in a submodule.","error":"ModuleNotFoundError: No module named 'ast_tools.mutable_ast'"},{"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.","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`.","error":"AttributeError: 'FunctionDef' object has no attribute 'lineno' (or similar for 'col_offset', 'end_lineno')"}]}