Switch rendering to writer.render()

Author: georgestagg

CLAUDE.md

@@ -165,16 +165,16 @@ let spec = reader.execute(
 
 // Render to Vega-Lite JSON
 let writer = VegaLiteWriter::new();
-let json = spec.render(&writer)?;
+let json = writer.render(&spec)?;
 ```
 
 ### Core Functions
 
-| Function                 | Purpose                                                |
-| ------------------------ | ------------------------------------------------------ |
-| `reader.execute(query)`  | Main entry point: parse, execute SQL, resolve mappings |
-| `spec.render(writer)`    | Generate output (Vega-Lite JSON) from Spec             |
-| `validate(query)`        | Validate syntax + semantics, inspect query structure   |
+| Function                | Purpose                                                |
+| ----------------------- | ------------------------------------------------------ |
+| `reader.execute(query)` | Main entry point: parse, execute SQL, resolve mappings |
+| `writer.render(spec)`   | Generate output from a Spec                            |
+| `validate(query)`       | Validate syntax + semantics, inspect query structure   |
 
 ### Key Types
 
@@ -909,7 +909,7 @@ print(f"SQL: {spec.sql()}")
 
 # Render to Vega-Lite JSON
 writer = ggsql.VegaLiteWriter()
-json_output = spec.render(writer)
+json_output = writer.render(spec)
 ```
 
 **Convenience Function** (`render_altair`):
@@ -942,21 +942,21 @@ print(f"Errors: {validated.errors()}")
 
 **Classes**:
 
-| Class                      | Description                                      |
-| -------------------------- | ------------------------------------------------ |
-| `DuckDBReader(connection)` | Database reader with DataFrame registration      |
-| `VegaLiteWriter()`         | Vega-Lite JSON output writer                     |
-| `Validated`                | Result of `validate()` with query inspection     |
+| Class                      | Description                                       |
+| -------------------------- | ------------------------------------------------- |
+| `DuckDBReader(connection)` | Database reader with DataFrame registration       |
+| `VegaLiteWriter()`         | Vega-Lite JSON output writer                      |
+| `Validated`                | Result of `validate()` with query inspection      |
 | `Spec`                     | Result of `reader.execute()`, ready for rendering |
 
 **Functions**:
 
-| Function                   | Description                                       |
-| -------------------------- | ------------------------------------------------- |
-| `validate(query)`          | Syntax/semantic validation with query inspection  |
-| `reader.execute(query)`    | Execute ggsql query, return Spec                  |
-| `execute(query, reader)`   | Execute with custom reader (bridge path)          |
-| `render_altair(df, viz)`   | Convenience: render DataFrame to Altair chart     |
+| Function                 | Description                                      |
+| ------------------------ | ------------------------------------------------ |
+| `validate(query)`        | Syntax/semantic validation with query inspection |
+| `reader.execute(query)`  | Execute ggsql query, return Spec                 |
+| `execute(query, reader)` | Execute with custom reader (bridge path)         |
+| `render_altair(df, viz)` | Convenience: render DataFrame to Altair chart    |
 
 **Spec Methods**:
 

README.md

@@ -327,13 +327,10 @@ chart.display()
 reader = ggsql.DuckDBReader("duckdb://memory")
 reader.register("data", df)
 
-prepared = ggsql.prepare(
-    "SELECT * FROM data VISUALISE x, y DRAW point",
-    reader
-)
+spec = reader.execute("SELECT * FROM data VISUALISE x, y DRAW point")
 
 writer = ggsql.VegaLiteWriter()
-json_output = prepared.render(writer)
+json_output = writer.render(spec)
 ```
 
 See the [ggsql-python README](ggsql-python/README.md) for complete API documentation.

ggsql-jupyter/src/executor.rs

@@ -7,7 +7,7 @@ use anyhow::Result;
 use ggsql::{
     reader::{DuckDBReader, Reader},
     validate,
-    writer::VegaLiteWriter,
+    writer::{VegaLiteWriter, Writer},
 };
 use polars::frame::DataFrame;
 
@@ -77,8 +77,8 @@ impl QueryExecutor {
             spec.metadata().layer_count
         );
 
-        // 4. Render to Vega-Lite
-        let vega_json = spec.render(&self.writer)?;
+        // 4. Render to output format
+        let vega_json = self.writer.render(&spec)?;
 
         tracing::debug!("Generated Vega-Lite spec: {} chars", vega_json.len());
 

ggsql-python/README.md

@@ -106,7 +106,7 @@ print(spec.data())  # Returns polars DataFrame
 
 # 6. Render to Vega-Lite JSON
 writer = ggsql.VegaLiteWriter()
-vegalite_json = spec.render(writer)
+vegalite_json = writer.render(spec)
 print(vegalite_json)
 ```
 
@@ -135,7 +135,7 @@ Writer that generates Vega-Lite v6 JSON specifications.
 
 ```python
 writer = ggsql.VegaLiteWriter()
-json_output = spec.render(writer)
+json_output = writer.render(spec)
 ```
 
 #### `Validated`
@@ -259,7 +259,7 @@ spec = ggsql.execute(
     reader
 )
 writer = ggsql.VegaLiteWriter()
-json_output = spec.render(writer)
+json_output = writer.render(spec)
 ```
 
 **Optional methods** for custom readers:

ggsql-python/python/ggsql/__init__.py

@@ -84,7 +84,7 @@ def render_altair(
     # Execute and render
     spec = reader.execute(query)
     writer = VegaLiteWriter()
-    vegalite_json = spec.render(writer)
+    vegalite_json = writer.render(spec)
 
     # Parse to determine the correct Altair class
     spec = json.loads(vegalite_json)

ggsql-python/src/lib.rs

@@ -6,10 +6,10 @@ use pyo3::prelude::*;
 use pyo3::types::{PyBytes, PyDict, PyList};
 use std::io::Cursor;
 
-use ggsql::validate::{validate as rust_validate, ValidationWarning};
 use ggsql::reader::Spec;
 use ggsql::reader::{DuckDBReader as RustDuckDBReader, Reader};
-use ggsql::writer::VegaLiteWriter as RustVegaLiteWriter;
+use ggsql::validate::{validate as rust_validate, ValidationWarning};
+use ggsql::writer::{VegaLiteWriter as RustVegaLiteWriter, Writer as RustWriter};
 use ggsql::GgsqlError;
 
 use polars::prelude::{DataFrame, IpcReader, IpcWriter, SerReader, SerWriter};
@@ -308,7 +308,8 @@ impl PyDuckDBReader {
     /// --------
     /// >>> reader = DuckDBReader("duckdb://memory")
     /// >>> spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
-    /// >>> json_output = spec.render(VegaLiteWriter())
+    /// >>> writer = VegaLiteWriter()
+    /// >>> json_output = writer.render(spec)
     fn execute(&self, query: &str) -> PyResult<PySpec> {
         self.inner
             .execute(query)
@@ -329,7 +330,7 @@ impl PyDuckDBReader {
 /// --------
 /// >>> writer = VegaLiteWriter()
 /// >>> spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
-/// >>> json_output = spec.render(writer)
+/// >>> json_output = writer.render(spec)
 #[pyclass(name = "VegaLiteWriter")]
 struct PyVegaLiteWriter {
     inner: RustVegaLiteWriter,
@@ -349,6 +350,35 @@ impl PyVegaLiteWriter {
             inner: RustVegaLiteWriter::new(),
         }
     }
+
+    /// Render a Spec to Vega-Lite JSON output
+    ///
+    /// Parameters
+    /// ----------
+    /// spec : Spec
+    ///     The visualization specification from reader.execute().
+    ///
+    /// Returns
+    /// -------
+    /// str
+    ///     The output (i.e., Vega-Lite JSON string).
+    ///
+    /// Raises
+    /// ------
+    /// ValueError
+    ///     If rendering fails.
+    ///
+    /// Examples
+    /// --------
+    /// >>> reader = DuckDBReader("duckdb://memory")
+    /// >>> spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
+    /// >>> writer = VegaLiteWriter()
+    /// >>> json_output = writer.render(spec)
+    fn render(&self, spec: &PySpec) -> PyResult<String> {
+        self.inner
+            .render(&spec.inner)
+            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))
+    }
 }
 
 // ============================================================================
@@ -439,42 +469,21 @@ impl PyValidated {
 /// Result of reader.execute(), ready for rendering.
 ///
 /// Contains the resolved plot specification, data, and metadata.
-/// Use render() to generate Vega-Lite JSON output.
+/// Use writer.render(spec) to generate output.
 ///
 /// Examples
 /// --------
 /// >>> spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
 /// >>> print(f"Rows: {spec.metadata()['rows']}")
-/// >>> json_output = spec.render(VegaLiteWriter())
+/// >>> writer = VegaLiteWriter()
+/// >>> json_output = writer.render(spec)
 #[pyclass(name = "Spec")]
 struct PySpec {
     inner: Spec,
 }
 
 #[pymethods]
 impl PySpec {
-    /// Render to output format (Vega-Lite JSON).
-    ///
-    /// Parameters
-    /// ----------
-    /// writer : VegaLiteWriter
-    ///     The writer to use for rendering.
-    ///
-    /// Returns
-    /// -------
-    /// str
-    ///     The Vega-Lite JSON specification as a string.
-    ///
-    /// Raises
-    /// ------
-    /// ValueError
-    ///     If rendering fails.
-    fn render(&self, writer: &PyVegaLiteWriter) -> PyResult<String> {
-        self.inner
-            .render(&writer.inner)
-            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))
-    }
-
     /// Get visualization metadata.
     ///
     /// Returns
@@ -688,8 +697,9 @@ fn validate(query: &str) -> PyResult<PyValidated> {
 /// --------
 /// >>> # Using native reader (prefer reader.execute() instead)
 /// >>> reader = DuckDBReader("duckdb://memory")
-/// >>> spec = execute("SELECT 1 AS x, 2 AS Y VISUALISE x, y DRAW point", reader)
-/// >>> json_output = spec.render(VegaLiteWriter())
+/// >>> spec = execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point", reader)
+/// >>> writer = VegaLiteWriter()
+/// >>> json_output = writer.render(spec)
 ///
 /// >>> # Using custom Python reader
 /// >>> class MyReader:

ggsql-python/tests/test_ggsql.py

@@ -98,9 +98,7 @@ class TestExecute:
 
     def test_execute_simple_query(self):
         reader = ggsql.DuckDBReader("duckdb://memory")
-        spec = reader.execute(
-            "SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point"
-        )
+        spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
         assert spec is not None
         assert spec.layer_count() == 1
 
@@ -127,23 +125,17 @@ def test_execute_metadata(self):
 
     def test_execute_sql_accessor(self):
         reader = ggsql.DuckDBReader("duckdb://memory")
-        spec = reader.execute(
-            "SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point"
-        )
+        spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
         assert "SELECT" in spec.sql()
 
     def test_execute_visual_accessor(self):
         reader = ggsql.DuckDBReader("duckdb://memory")
-        spec = reader.execute(
-            "SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point"
-        )
+        spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
         assert "VISUALISE" in spec.visual()
 
     def test_execute_data_accessor(self):
         reader = ggsql.DuckDBReader("duckdb://memory")
-        spec = reader.execute(
-            "SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point"
-        )
+        spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
         data = spec.data()
         assert isinstance(data, pl.DataFrame)
         assert data.shape == (1, 2)
@@ -154,17 +146,15 @@ def test_execute_without_visualise_fails(self):
             reader.execute("SELECT 1 AS x, 2 AS y")
 
 
-class TestSpecRender:
-    """Tests for Spec.render() method."""
+class TestWriterRender:
+    """Tests for VegaLiteWriter.render() method."""
 
     def test_render_to_vegalite(self):
         reader = ggsql.DuckDBReader("duckdb://memory")
-        spec = reader.execute(
-            "SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point"
-        )
+        spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
         writer = ggsql.VegaLiteWriter()
 
-        result = spec.render(writer)
+        result = writer.render(spec)
         assert isinstance(result, str)
 
         spec_dict = json.loads(result)
@@ -179,7 +169,7 @@ def test_render_contains_data(self):
         spec = reader.execute("SELECT * FROM data VISUALISE x, y DRAW point")
         writer = ggsql.VegaLiteWriter()
 
-        result = spec.render(writer)
+        result = writer.render(spec)
         spec_dict = json.loads(result)
         # Data should be in the spec (either inline or in datasets)
         assert "data" in spec_dict or "datasets" in spec_dict
@@ -194,7 +184,7 @@ def test_render_multi_layer(self):
         )
         writer = ggsql.VegaLiteWriter()
 
-        result = spec.render(writer)
+        result = writer.render(spec)
         spec_dict = json.loads(result)
         assert "layer" in spec_dict
 
@@ -367,7 +357,7 @@ def test_end_to_end_workflow(self):
 
         # Render to Vega-Lite
         writer = ggsql.VegaLiteWriter()
-        result = spec.render(writer)
+        result = writer.render(spec)
 
         # Verify output
         spec_dict = json.loads(result)
@@ -377,9 +367,7 @@ def test_end_to_end_workflow(self):
     def test_can_introspect_spec(self):
         """Test all introspection methods on Spec."""
         reader = ggsql.DuckDBReader("duckdb://memory")
-        spec = reader.execute(
-            "SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point"
-        )
+        spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
 
         # All these should work without error
         assert spec.sql() is not None
@@ -430,9 +418,7 @@ def register(self, name: str, df: pl.DataFrame) -> None:
                 self.tables[name] = df
 
         reader = RegisterReader()
-        spec = ggsql.execute(
-            "SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point", reader
-        )
+        spec = ggsql.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point", reader)
         assert spec is not None
 
     def test_custom_reader_error_handling(self):
@@ -460,9 +446,7 @@ def execute_sql(self, sql: str):
     def test_native_reader_fast_path(self):
         """Native DuckDBReader still works (fast path)."""
         reader = ggsql.DuckDBReader("duckdb://memory")
-        spec = reader.execute(
-            "SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point"
-        )
+        spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
         assert spec.metadata()["rows"] == 1
 
     def test_custom_reader_can_render(self):
@@ -485,7 +469,7 @@ def execute_sql(self, sql: str) -> pl.DataFrame:
         )
 
         writer = ggsql.VegaLiteWriter()
-        result = spec.render(writer)
+        result = writer.render(spec)
 
         spec_dict = json.loads(result)
         assert "$schema" in spec_dict