feat: add validate, height, and width as formal arguments on render_chart() and render_altair()

These were previously only accessible via **kwargs. Using None as the
sentinel for height/width preserves ggsql's own defaults when unset.

Author: cpsievert

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## UNRELEASED
+
+### Changed
+
+- `VegaLiteWriter.render_chart()` and `render_altair()` now accept `validate`, `height`, and `width` as explicit keyword arguments. `height` and `width` default to `None`, which preserves whatever dimensions ggsql produces. `validate` defaults to `False` (same behavior as before, now a named parameter).
+
 ## 0.3.2
 
 ### Changed

python/ggsql/__init__.py

@@ -93,30 +93,55 @@ def render(self, spec: Spec) -> str:
         """Render a Spec to a Vega-Lite JSON string."""
         return self._inner.render(spec)
 
-    def render_chart(self, spec: Spec, **kwargs: Any) -> AltairChart:
+    def render_chart(
+        self,
+        spec: Spec,
+        *,
+        validate: bool = False,
+        height: int | None = None,
+        width: int | None = None,
+        **kwargs: Any,
+    ) -> AltairChart:
         """Render a Spec to an Altair chart object.
 
         Parameters
         ----------
         spec
             The resolved visualization specification from ``reader.execute()``.
+        validate
+            Whether to validate the spec against the Vega-Lite schema.
+        height
+            Chart height in pixels. When ``None`` (the default), the height
+            produced by ggsql is used as-is.
+        width
+            Chart width in pixels. When ``None`` (the default), the width
+            produced by ggsql is used as-is.
         **kwargs
             Additional keyword arguments passed to ``altair.Chart.from_json()``.
-            Vega-Lite schema validation is disabled by default; pass
-            ``validate=True`` to re-enable it.
 
         Returns
         -------
         AltairChart
             An Altair chart object (Chart, LayerChart, FacetChart, etc.).
         """
         vegalite_json = self.render(spec)
-        return _json_to_altair_chart(vegalite_json, **kwargs)
+        if height is not None or width is not None:
+            spec_dict = json.loads(vegalite_json)
+            if height is not None:
+                spec_dict["height"] = height
+            if width is not None:
+                spec_dict["width"] = width
+            vegalite_json = json.dumps(spec_dict)
+        return _json_to_altair_chart(vegalite_json, validate=validate, **kwargs)
 
 
 def render_altair(
     df: IntoFrame,
     viz: str,
+    *,
+    validate: bool = False,
+    height: int | None = None,
+    width: int | None = None,
     **kwargs: Any,
 ) -> AltairChart:
     """Render a DataFrame with a VISUALISE spec to an Altair chart.
@@ -128,10 +153,16 @@ def render_altair(
         DataFrame. LazyFrames are collected automatically.
     viz
         VISUALISE spec string (e.g., "VISUALISE x, y DRAW point")
+    validate
+        Whether to validate the spec against the Vega-Lite schema.
+    height
+        Chart height in pixels. When ``None`` (the default), the height
+        produced by ggsql is used as-is.
+    width
+        Chart width in pixels. When ``None`` (the default), the width
+        produced by ggsql is used as-is.
     **kwargs
-        Additional keyword arguments passed to `from_json()`.
-        Vega-Lite schema validation is disabled by default; pass
-        `validate=True` to re-enable it.
+        Additional keyword arguments passed to ``altair.Chart.from_json()``.
 
     Returns
     -------
@@ -160,4 +191,12 @@ def render_altair(
     writer = VegaLiteWriter()
     vegalite_json = writer.render(spec)
 
-    return _json_to_altair_chart(vegalite_json, **kwargs)
+    if height is not None or width is not None:
+        spec_dict = json.loads(vegalite_json)
+        if height is not None:
+            spec_dict["height"] = height
+        if width is not None:
+            spec_dict["width"] = width
+        vegalite_json = json.dumps(spec_dict)
+
+    return _json_to_altair_chart(vegalite_json, validate=validate, **kwargs)

tests/test_ggsql.py

@@ -275,6 +275,37 @@ def test_chart_can_be_serialized(self):
         json_str = chart.to_json()
         assert len(json_str) > 0
 
+    def test_height_width(self):
+        table = pa.table({"x": [1, 2, 3], "y": [10, 20, 30]})
+        chart = ggsql.render_altair(
+            table, "VISUALISE x, y DRAW point", height=300, width=500
+        )
+        chart_dict = chart.to_dict()
+        assert chart_dict["height"] == 300
+        assert chart_dict["width"] == 500
+
+    def test_height_only(self):
+        table = pa.table({"x": [1, 2, 3], "y": [10, 20, 30]})
+        chart = ggsql.render_altair(table, "VISUALISE x, y DRAW point", height=400)
+        chart_dict = chart.to_dict()
+        assert chart_dict["height"] == 400
+
+    def test_default_preserves_ggsql_dimensions(self):
+        table = pa.table({"x": [1, 2, 3], "y": [10, 20, 30]})
+
+        reader = ggsql.DuckDBReader("duckdb://memory")
+        reader.register("__data__", table)
+        spec = reader.execute("SELECT * FROM __data__ VISUALISE x, y DRAW point")
+        raw_spec = json.loads(ggsql.VegaLiteWriter().render(spec))
+
+        chart = ggsql.render_altair(table, "VISUALISE x, y DRAW point")
+        chart_dict = chart.to_dict()
+
+        if "height" in raw_spec:
+            assert chart_dict["height"] == raw_spec["height"]
+        if "width" in raw_spec:
+            assert chart_dict["width"] == raw_spec["width"]
+
 
 class TestRenderAltairChartTypeDetection:
     """Tests for correct Altair chart type detection based on spec structure."""
@@ -638,3 +669,37 @@ def test_render_chart_facet(self):
         writer = ggsql.VegaLiteWriter()
         chart = writer.render_chart(spec, validate=False)
         assert isinstance(chart, altair.FacetChart)
+
+    def test_render_chart_height_width(self):
+        """render_chart() injects height/width into the spec when provided."""
+        reader = ggsql.DuckDBReader("duckdb://memory")
+        spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
+        writer = ggsql.VegaLiteWriter()
+        chart = writer.render_chart(spec, height=300, width=500)
+        chart_dict = chart.to_dict()
+        assert chart_dict["height"] == 300
+        assert chart_dict["width"] == 500
+
+    def test_render_chart_height_only(self):
+        """render_chart() can set height without width."""
+        reader = ggsql.DuckDBReader("duckdb://memory")
+        spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
+        writer = ggsql.VegaLiteWriter()
+        chart = writer.render_chart(spec, height=400)
+        chart_dict = chart.to_dict()
+        assert chart_dict["height"] == 400
+
+    def test_render_chart_default_preserves_ggsql_dimensions(self):
+        """When height/width are not specified, ggsql's defaults are preserved."""
+        reader = ggsql.DuckDBReader("duckdb://memory")
+        spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
+        writer = ggsql.VegaLiteWriter()
+
+        raw_spec = json.loads(writer.render(spec))
+        chart = writer.render_chart(spec)
+        chart_dict = chart.to_dict()
+
+        if "height" in raw_spec:
+            assert chart_dict["height"] == raw_spec["height"]
+        if "width" in raw_spec:
+            assert chart_dict["width"] == raw_spec["width"]