feat(python): add Python bindings for ggsql

.github/workflows/R-CMD-check.yaml

@@ -20,6 +20,14 @@ jobs:
           sudo docker image prune --all --force
           sudo docker builder prune -a
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install tree-sitter-cli
+        run: npm install -g tree-sitter-cli
+
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 

.github/workflows/build.yaml

@@ -21,6 +21,14 @@ jobs:
           sudo docker image prune --all --force
           sudo docker builder prune -a
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install tree-sitter-cli
+        run: npm install -g tree-sitter-cli
+
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 
@@ -39,7 +47,7 @@ jobs:
 
       - name: Run Rust tests
         if: success()
-        run: cargo test
+        run: cargo test --lib --bins
 
       - name: Run Rust formatting check
         if: success()

.github/workflows/publish.yaml

@@ -22,6 +22,14 @@ jobs:
           sudo docker image prune --all --force
           sudo docker builder prune -a
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install tree-sitter-cli
+        run: npm install -g tree-sitter-cli
+
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 

.github/workflows/python.yml

@@ -0,0 +1,72 @@
+name: Python
+
+on:
+  push:
+    paths: ['ggsql-python/**', '.github/workflows/python.yml']
+  pull_request:
+    paths: ['ggsql-python/**', '.github/workflows/python.yml']
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ['3.10', '3.11', '3.12', '3.13']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install tree-sitter-cli
+        run: npm install -g tree-sitter-cli
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: ggsql-python
+          shared-key: ${{ matrix.os }}-python
+
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          working-directory: ggsql-python
+          command: build
+          args: --release
+          sccache: true
+
+      - name: Install wheel and test dependencies
+        shell: bash
+        run: pip install --find-links target/wheels/ ggsql[test]
+
+      - name: Run tests
+        shell: bash
+        run: pytest ggsql-python/tests/ -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install tree-sitter-cli
+        run: npm install -g tree-sitter-cli
+
+      - name: Check Rust formatting
+        run: cargo fmt --package ggsql-python -- --check
+
+      - name: Clippy
+        run: cargo clippy --package ggsql-python -- -D warnings

CLAUDE.md

@@ -790,6 +790,63 @@ When running in Positron IDE, the extension provides enhanced functionality:
 
 ---
 
+### 8. Python Bindings (`ggsql-python/`)
+
+**Responsibility**: Python bindings for ggsql, enabling Python users to render Altair charts using ggsql's VISUALISE syntax.
+
+**Features**:
+
+- PyO3-based Rust bindings compiled to a native Python extension
+- Works with any narwhals-compatible DataFrame (polars, pandas, etc.)
+- LazyFrames are collected automatically
+- Returns native `altair.Chart` objects for easy display and customization
+- Query splitting to separate SQL from VISUALISE portions
+
+**Installation**:
+
+```bash
+# From source (requires Rust toolchain and maturin)
+cd ggsql-python
+pip install maturin
+maturin develop
+```
+
+**API**:
+
+```python
+import ggsql
+import polars as pl
+
+# Split a ggSQL query into SQL and VISUALISE portions
+sql, viz = ggsql.split_query("""
+    SELECT date, revenue FROM sales
+    VISUALISE date AS x, revenue AS y
+    DRAW line
+""")
+
+# Execute SQL and render to Altair chart
+df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
+chart = ggsql.render_altair(df, "VISUALISE x, y DRAW point")
+
+# Display or save
+chart.display()  # In Jupyter
+chart.save("chart.html")
+```
+
+**Functions**:
+
+- `split_query(query: str) -> tuple[str, str]` - Split ggSQL query into SQL and VISUALISE portions
+- `render_altair(df, viz, **kwargs) -> altair.Chart` - Render DataFrame with VISUALISE spec to Altair chart
+
+**Dependencies**:
+
+- Python >= 3.10
+- altair >= 5.0
+- narwhals >= 2.15
+- polars >= 1.0
+
+---
+
 ## Feature Flags and Build Configuration
 
 ggsql uses Cargo feature flags to enable optional functionality and reduce binary size.
@@ -822,9 +879,9 @@ ggsql uses Cargo feature flags to enable optional functionality and reduce binar
   - Includes: `axum`, `tokio`, `tower-http`, `tracing`, `duckdb`, `vegalite`
   - Required for building `ggsql-rest` server
 
-**Future features**:
+**Python bindings**:
 
-- `python` - Python bindings via PyO3 (planned)
+- `ggsql-python` - Python bindings via PyO3 (separate crate, not a feature flag)
 
 ### Building with Custom Features
 
@@ -850,7 +907,7 @@ cargo build --all-features
 - `postgres` → `postgres` crate (future)
 - `sqlite` → `rusqlite` crate (future)
 - `rest-api` → `axum`, `tokio`, `tower-http`, `tracing`, `tracing-subscriber`
-- `python` → `pyo3` crate (future)
+- `ggsql-python` → `pyo3`, `narwhals`, `altair` (separate workspace crate)
 
 ---
 

Cargo.toml

@@ -1,5 +1,13 @@
 [workspace]
 members = [
+    "tree-sitter-ggsql",
+    "src",
+    "ggsql-jupyter",
+    "ggsql-python"
+]
+# ggsql-python is excluded from default builds because it's a PyO3 extension
+# that requires Python dev headers. Build it separately with maturin.
+default-members = [
     "tree-sitter-ggsql",
     "src",
     "ggsql-jupyter"
@@ -21,7 +29,7 @@ tree-sitter = "0.25"
 csscolorparser = "0.8.1"
 
 # Data processing
-polars = { version = "0.52", features = ["lazy", "sql"] }
+polars = { version = "0.52", features = ["lazy", "sql", "ipc"] }
 
 # Readers
 duckdb = { version = "1.1", features = ["bundled"] }

ggsql-python/.gitignore

@@ -0,0 +1,3 @@
+.vscode/
+
+uv.lock

ggsql-python/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "ggsql-python"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+description = "Python bindings for ggsql"
+
+[lib]
+name = "_ggsql"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.26", features = ["extension-module"] }
+polars = { workspace = true, features = ["ipc"] }
+ggsql = { path = "../src", default-features = false, features = ["vegalite"] }
+
+[features]
+default = []