{"id":4435,"library":"ast-grep-py","title":"AST Grep Python Bindings","description":"ast-grep-py provides Python bindings for ast-grep, a powerful structural code search and rewrite engine. It enables developers to query and transform code using abstract syntax tree (AST) patterns, supporting multiple programming languages. The current version is 0.42.1, and the library maintains a rapid release cadence with frequent minor and patch updates, often multiple times a month.","status":"active","version":"0.42.1","language":"en","source_language":"en","source_url":"https://github.com/ast-grep/ast-grep","tags":["ast","code-analysis","refactoring","static-analysis","code-transformation","pattern-matching"],"install":[{"cmd":"pip install ast-grep-py","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"symbol":"SgRoot","correct":"from ast_grep_py import SgRoot"},{"symbol":"SgNode","correct":"from ast_grep_py import SgNode"},{"symbol":"SgMatch","correct":"from ast_grep_py import SgMatch"},{"symbol":"SgPattern","correct":"from ast_grep_py import SgPattern"}],"quickstart":{"code":"from ast_grep_py import SgRoot\n\npython_code = \"\"\"\ndef my_function(a, b):\n    result = a + b\n    print(f\"Result: {result}\")\n    return result\n\"\"\"\n\n# Create an SgRoot instance. Language defaults to Python.\nroot = SgRoot(code=python_code)\n\n# Find all function definitions using an ast-grep pattern\n# '$FUN' and '$$$' are metavariables matching identifiers and multiple statements/expressions respectively.\nmatches = root.find_all(\"def $FUN($$$):\")\n\nprint(\"Found functions:\")\nfor m in matches:\n    print(f\"- {m.text()}\")\n\n# Replace print statements with a logger.info call\n# SgRoot.replace returns a new SgRoot instance with the changes.\nnew_code_root = root.replace(\n    pattern='print($$$)',\n    replacement='logger.info($$$)'\n)\n\nprint(\"\\nCode after replacement:\")\nprint(new_code_root.text())","lang":"python","description":"Initialize an `SgRoot` with Python code, find patterns like function definitions, and replace `print()` calls with `logger.info()` using ast-grep's pattern matching syntax. Note that `replace()` returns a new `SgRoot` object."},"warnings":[{"fix":"Refer to the official ast-grep pattern documentation at https://ast-grep.github.io/ast-grep/guide/pattern.html","message":"The pattern matching syntax used by ast-grep-py (e.g., `$VAR`, `$$$`) is specific to ast-grep and differs significantly from standard regular expressions or typical AST traversal libraries. Users must learn this syntax to effectively utilize the library.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always pass the `lang` argument for non-Python code to ensure correct parsing and pattern matching.","message":"When analyzing code written in languages other than Python, it is crucial to explicitly specify the `lang` parameter during `SgRoot` initialization (e.g., `SgRoot(code=my_js_code, lang='javascript')`). The default language is Python.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always assign the result of `replace()` or similar modification methods to a new variable or reassign to the original variable to capture the changes.","message":"Methods like `SgRoot.replace()` do not modify the original `SgRoot` instance in-place. Instead, they return a *new* `SgRoot` object containing the modified code. Users expecting mutable behavior might inadvertently ignore the returned value.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Benchmark critical operations on representative codebases. Consider direct use of the ast-grep CLI for maximum performance if the Python binding overhead is unacceptable.","message":"While ast-grep is implemented in Rust for performance, the Python bindings introduce a layer of overhead. For extremely large codebases or highly performance-critical scenarios involving frequent AST operations, users should benchmark the Python bindings against the native Rust CLI to ensure it meets their performance requirements.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}