feat(python): add Python bindings for ggsql

[cpsievert]

This PR introduces ggsql-python, a new Python package providing PyO3 bindings for the ggsql crate. The package enables Python users to render Altair charts from DataFrames using ggsql's VISUALISE syntax.

• Add ggsql-python package with PyO3 bindings exposing split_query() and render_altair() functions
• render_altair() returns an altair.Chart directly for easy display and customization
• Support any narwhals-compatible DataFrame (polars, pandas, etc.) with automatic LazyFrame collection
• Add CI workflow testing across Python 3.10-3.13 on Linux, macOS, and Windows
• Commit tree-sitter generated files to enable Windows CI builds without tree-sitter CLI

Key Features

API:

import ggsql
import duckdb

# Split a ggsql query into SQL and VISUALISE portions
sql, viz = ggsql.split_query("""
    SELECT date, revenue, region FROM sales
    WHERE year = 2024
    VISUALISE date AS x, revenue AS y, region AS color
    DRAW line
    LABEL title => 'Sales by Region'
""")

# Execute SQL with a Python package like duckdb, polars, sqlalchemy, etc
df = duckdb.sql(sql).pl()

# Render DataFrame + VISUALISE spec to Altair chart
chart = ggsql.render_altair(df, viz)

# Display or save the chart
chart.display()  # In Jupyter
chart.save("chart.html")  # Save to file

DataFrame Support:

• Polars DataFrames (native)
• Polars LazyFrames (auto-collected)
• Pandas DataFrames (via narwhals)
• Any narwhals-compatible DataFrame type

Mapping Styles:

• Explicit: VISUALISE x AS x, y AS y
• Implicit: VISUALISE x, y (column name matches aesthetic)
• Wildcard: VISUALISE * (map all matching columns)

Building & Installation

Requirements:

• Python 3.10+
• Rust toolchain (install via rustup)
• maturin for building

From source (development mode):

cd ggsql-python
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
pip install maturin
maturin develop

Build a wheel:

cd ggsql-python
maturin build --release
pip install target/wheels/ggsql-*.whl

Run tests:

pip install pytest
pytest tests/ -v

Dependencies:

• altair>=5.0 - Chart rendering
• narwhals>=2.15.0 - DataFrame compatibility layer
• polars>=1.0 - Native DataFrame support
• pyarrow>=14.0 - Required by pyo3-polars

Test plan

• split_query() correctly separates SQL and VISUALISE portions
• render_altair() accepts polars DataFrames
• render_altair() accepts polars LazyFrames (auto-collected)
• render_altair() accepts narwhals DataFrames
• render_altair() accepts pandas DataFrames (via narwhals)
• render_altair() rejects invalid DataFrame types with TypeError
• render_altair() returns altair.Chart instance
• render_altair() passes **kwargs through to altair.Chart.from_json()
• Invalid VISUALISE syntax raises ValueError
• CI runs on Python 3.10-3.13 across ubuntu, macos, and windows

🤖 Generated with Claude Code

[cpsievert]

This change was needed since tree-sitter generate was failing on Windows. Claude offered a few different ways to fix this, but recommended this approach:

Approach	Repo Size	Build Speed	Reliability	Complexity
Commit generated files	+1.3MB	Fast	High	Low
CI installs tree-sitter-cli	Small	Slow	Medium	Low
tree-sitter-cli crate	Small	Slow	High	Medium
Conditional build.rs	Small*	Fast*	Medium	Medium

[georgestagg]

If the issue is simply that tree sitter is not installed in CI, I'd rather not check in the generated files and instead install it on Windows using something like https://github.com/tree-sitter/setup-action/tree/master.

Those generated files can get very large as grammars get complex, and I'd like to avoid the noise if we can.

[teunbrand]

I do recall having to do a little 'nvm' song and dance to please installation on windows, but I've forgotten the details already.

[cpsievert]

Done in 8ffdc1a

[cpsievert]

@georgestagg or @thomasp85 this is ready for a review whenever.

BTW, If neither of you have interest/bandwidth in reviewing the Python package (which, at least for now, I'm primarily wanting for querychat), then I'd be happy to gain write access and be considered a "maintainer" of the Python package. I'll handle submitting to PyPI, etc.

[georgestagg]

I am going to be very busy this week with other things, but I will take a look at this when I can. My apologies if it blocks the querychat work in the meantime.

I would like to think carefully about the consequences of checking in the tree sitter artefacts, and whether the split_query entry point is still the right design at our end. Probably it should be renamed at least.

[thomasp85]

I'm afraid my knowledge and interest in Python is too limited to provide any sensible review

[georgestagg]

skip doc tests to avoid linker memory issues

If you bang up against this again, I've used this little snippet in the past. A little cheeky, perhaps, but it seems to work.

  - name: Increase swapfile
    run: |
      sudo swapoff -a
      sudo fallocate -l 15G /swapfile
      sudo chmod 600 /swapfile
      sudo mkswap /swapfile
      sudo swapon /swapfile
      sudo swapon --show

We could also try the with the posit-dev runners.

[georgestagg]

OK, this looks good to go in. The infrastructure looks good, thank you for making the Python build optional.

Now, the tricky bit. I am going to rework the Rust API, as discussed elsewhere, and so the Python package will need to change in response. I will handle that, but in a followup PR and tag you for review. I will try to keep the render_altair() interface as it currently is presented to the end user.