GritQL

0.2.0 verified Fri May 01 auth: no python

GritQL is a query language for searching and transforming code. The `gritql` package provides Python bindings to run GritQL queries programmatically. Version 0.2.0 is experimental and under active development.

pip install gritql

Common errors

error FileNotFoundError: [Errno 2] No such file or directory: 'grit' ↓

cause The Python bindings call the `grit` binary under the hood. If it's not installed or not on PATH, this error occurs.

fix

Install the GritQL CLI by running the install script or downloading the binary and adding it to your PATH.

error ModuleNotFoundError: No module named 'gritql' ↓

cause The `gritql` package is not installed in the current Python environment.

fix

Run pip install gritql to install the package.

Warnings

breaking API instability: The Python API is still experimental (0.x) and may change without notice. Expect breaking changes in minor versions. ↓

fix Pin to exact version: `pip install gritql==0.2.0`. Check changelog before upgrading.

gotcha Query result is boolean only: `run()` returns `True` if the pattern matched, not a match object or location info. To get detailed matches, you may need to use the CLI or Rust API. ↓

fix If you need match metadata, consider using the GritQL CLI tool directly with subprocess.

gotcha Requires installed GritQL binary: The Python bindings expect a `grit` binary on PATH. Without it, import succeeds but `GritQuery()` will fail at runtime with a `FileNotFoundError`. ↓

fix Install the GritQL CLI: `curl -fsSL https://docs.grit.io/install | bash` or download from GitHub releases.

Imports

GritQuery
```
from gritql import GritQuery
```
The library exposes a single class `GritQuery` for compiling and executing queries.

Quickstart

Basic usage: compile a GritQL pattern and run it against a string or file.

from gritql import GritQuery

# Compile a simple query
query = GritQuery('`console.log`')

# Run against a code snippet (returns True if matched)
result = query.run('console.log("hello")')
print(result)  # True

# With file path
result = query.run('console.log("hello")', path='test.js')
print(result)  # True