Refactor API: Writer-centric rendering and Python module restructure

[cpsievert]

This PR builds on #89 to improve the Python package with a cleaner API structure, proper IDE support, and better error handling.

API Tweaks

Before

import ggsql
import polars as pl

df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})

reader = ggsql.DuckDBReader("duckdb://memory")
reader.register("data", df)
prepared = ggsql.prepare("SELECT * FROM data VISUALISE x, y DRAW point", reader)
json_str = prepared.render(ggsql.VegaLiteWriter())

After

import polars as pl
from ggsql.readers import DuckDB
from ggsql.writers import VegaLite

df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})

reader = DuckDB("duckdb://memory")
spec = reader.execute(
    "SELECT * FROM data VISUALISE x, y DRAW point",
    {"data": df}  # Auto-registered, auto-cleaned up
)
writer = VegaLite()
chart = writer.render_chart(spec)  # Returns Altair chart
json_str = writer.render_json(spec)  # Or get raw JSON

A summary of the API changes:

Before	After
ggsql.DuckDBReader(conn)	ggsql.readers.DuckDB(conn)
ggsql.VegaLiteWriter()	ggsql.writers.VegaLite()
ggsql.prepare(query, reader)	reader.execute(query, data_dict)
prepared.render(writer)	writer.render_json(spec) or writer.render_chart(spec)
reader.execute(sql)	reader.execute_sql(sql)
ValueError for all errors	Specific exception types
render_altair(df, viz)	Use writer.render_chart(spec)

Which will require/inspire some Rust API tweaks

Change	Why
Writer::render(&Prepared)	Moves rendering responsibility to Writer, enabling Python's writer.render_json(spec) pattern
Reader::execute() → execute_sql()	Frees up execute name for Python's higher-level execute(query, data_dict) method
Reader::unregister(name)	Enables auto-cleanup in Python's execute() - tables are unregistered after query
GgsqlError::NoVisualise	Enables Python's NoVisualiseError exception for queries missing VISUALISE clause

Other Python Improvements

1. Full IDE Support with Type Stubs

The new _ggsql.pyi provides complete type information for the native extension:

• Autocomplete for all methods and parameters
• Inline documentation in IDE tooltips
• Type checking with mypy/pyright

2. Proper Exception Hierarchy

try:
    spec = reader.execute(query, {"data": df})
except ggsql.types.NoVisualiseError:
    # Query has no VISUALISE clause - use execute_sql() instead
    df = reader.execute_sql(query)
except ggsql.types.ValidationError as e:
    # Column doesn't exist, missing required aesthetic, etc.
    print(f"Invalid query: {e}")
except ggsql.types.ReaderError as e:
    # SQL execution failed
    print(f"Database error: {e}")
except ggsql.types.GgsqlError as e:
    # Catch-all for any ggsql error
    print(f"Error: {e}")

3. Clean Module Structure

ggsql/
├── readers.py    # DuckDB (more backends later)
├── writers.py    # VegaLite (more formats later)  
├── types.py      # Prepared, Validated, exceptions
└── _ggsql.pyi    # Type stubs for IDE support

4. Auto-Registration with Cleanup

Tables passed to execute() are automatically:

• Registered before query execution
• Unregistered after (even on error)

5. Context Manager Support

with DuckDB("duckdb://memory") as reader:
    spec = reader.execute(query, {"data": df})

Commits

1. Rust API refactor - Writer::render(), execute_sql(), unregister(), NoVisualise error
2. Python bindings restructure - New modules, exceptions, type stubs
3. Python tests - Full coverage for new API
4. Documentation - Updated examples and reference
5. Formatting fix - cargo fmt
6. REST API fix - Handle NoVisualise error, clippy warnings

🤖 Generated with Claude Code

[cpsievert]

@georgestagg something went way off the rails with the Reader class refactoring/API.

Before I spend time untangling the mess, does the overall proposal in the PR description seem sensible to you?

Additionally, would it be off base to think we should allow a custom Reader to be implemented in Python without Rust (i.e., simple wrapper around sqlalchemy, Ibis, etc)?

[georgestagg]

Additionally, would it be off base to think we should allow a custom Reader to be implemented in Python without Rust (i.e., simple wrapper around sqlalchemy, Ibis, etc)?

This should have already been possible in #89, right?

import ggsql
import polars as pl

class CSVReader:
    """Custom reader that loads data from CSV files."""

    def __init__(self, data_dir: str):
        self.data_dir = data_dir

    def execute(self, sql: str) -> pl.DataFrame:
        # Simple implementation: ignore SQL and return fixed data
        # A real implementation would parse SQL to determine which file to load
        return pl.read_csv(f"{self.data_dir}/data.csv")

# Use custom reader with prepare()
reader = CSVReader("/path/to/data")
prepared = ggsql.prepare(
    "SELECT * FROM data VISUALISE x, y DRAW point",
    reader
)
writer = ggsql.VegaLiteWriter()
json_output = prepared.render(writer)

[georgestagg]

Note that there is a performance implication when crossing the Rust/Python barrier. So it might not be a good idea to thinly wrap the duckdb reader like this.

[cpsievert]

This should have already been possible

Yea, I missed that on first pass. I'll have to think on it a bit more.

I'm gonna close this PR in favor of a set of more focused PRs.