ast-grep-py

What it is and what it does

ast-grep-py exposes ast-grep's code search and rewriting engine to Python programs. It lets you define patterns that match code structure—not just text—and then find, analyze, or transform matching code at scale. The package is a native Rust binding compiled to wheels, so it has no Python runtime dependencies and runs efficiently on modern Python versions.

You would use this when you need to perform structural code analysis or refactoring that text regex cannot handle: finding all calls to a deprecated function across a codebase, rewriting patterns to use a new API, or enforcing code style rules based on syntax tree shape. The API is programmatic, so you integrate it into scripts, linters, or CI pipelines rather than using a command-line tool.

Use it for:

• Search for and refactor all uses of a deprecated API across a large codebase in one pass.
• Enforce custom code style rules by matching specific AST patterns and flagging violations.
• Automate codemod tasks—e.g., migrate from one library to another—by pattern-matching and rewriting code structure.
• Build custom linters that detect anti-patterns or security issues based on syntax tree shape.
• Analyze code structure programmatically to gather metrics or generate reports on code patterns.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

ast-grep-py is a Python binding for ast-grep, a tool that searches, lints, and rewrites code using precise abstract syntax tree patterns.

Yes, if you need structural code search or rewriting beyond regex. The package is actively maintained, has no security vulnerabilities, uses a permissive MIT license, and is well-distributed across platforms. Medium install friction is acceptable for a compiled tool. Start with the official API guide to confirm the pattern syntax and API surface fit your use case.

Install

ast-grep-py on PyPI

pip install ast-grep-py

uv add ast-grep-py

poetry add ast-grep-py

Installing ast-grep-py

Before you install

Medium install friction due to compiled wheels, but well-supported across multiple Python versions on Linux, macOS, and Windows. Active maintenance with a release 7 days old and 15516 repository stars.

License in practice

MIT license is permissive; you may use, modify, and distribute this package freely in commercial or private projects with minimal restrictions.

Quickstart

pip install ast-grep-py

# See https://ast-grep.github.io/guide/api-usage.html for pattern and search examples

Requires Python 3.8 or later; prebuilt wheels are available for common platforms, but installation may require a Rust toolchain if building from source.

Verify before relying

• Whether the package provides a high-level convenience API or requires deep familiarity with AST and pattern syntax to be productive.
• Performance characteristics when searching or rewriting large codebases.
• Availability of pattern libraries or templates for common refactoring tasks.
• Concrete example of how to invoke the binding's main entry points after import.

Package facts

Evidence: ast_grep_py-0.45.1-cp310-cp310-manylinux_2_28_aarch64.whl; ast_grep_py-0.45.1-cp310-cp310-manylinux_2_28_x86_64.whl; ast_grep_py-0.45.1-cp310-cp310-win32.whl; ast_grep_py-0.45.1-cp310-cp310-win_amd64.whl; ast_grep_py-0.45.1-cp311-cp311-macosx_10_12_x86_64.whl; ast_grep_py-0.45.1-cp311-cp311-macosx_11_0_arm64.whl; ast_grep_py-0.45.1-cp311-cp311-manylinux_2_28_aarch64.whl; ast_grep_py-0.45.1-cp311-cp311-manylinux_2_28_x86_64.whl; ast_grep_py-0.45.1-cp311-cp311-win32.whl; ast_grep_py-0.45.1-cp311-cp311-win_amd64.whl; ast_grep_py-0.45.1-cp312-cp312-macosx_10_12_x86_64.whl; ast_grep_py-0.45.1-cp312-cp312-macosx_11_0_arm64.whl; ast_grep_py-0.45.1-cp312-cp312-manylinux_2_28_aarch64.whl; ast_grep_py-0.45.1-cp312-cp312-manylinux_2_28_x86_64.whl; ast_grep_py-0.45.1-cp312-cp312-win32.whl; ast_grep_py-0.45.1-cp312-cp312-win_amd64.whl; ast_grep_py-0.45.1-cp313-cp313-macosx_10_12_x86_64.whl; ast_grep_py-0.45.1-cp313-cp313-macosx_11_0_arm64.whl; ast_grep_py-0.45.1-cp313-cp313-manylinux_2_28_aarch64.whl; ast_grep_py-0.45.1-cp313-cp313-manylinux_2_28_x86_64.whl

Keywords: ast, pattern, codemod, structural search, rewrite

Tags

More Software Development packages