refactor(python): rename render() to render_altair()

cpsievert · claude · cpsievert · commit 67cc299ab302 · 2026-01-22T12:39:59.000-06:00
- Rename render() to render_altair() for clearer API
- Remove writer parameter (always renders to Altair)
- Add **kwargs pass-through to altair.Chart.from_json()
- Update tests and README

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/ggsql-python/README.md b/ggsql-python/README.md
@@ -58,7 +58,7 @@ sql, viz = ggsql.split_query("""
 df = duckdb.sql(sql).pl()
 
 # Render DataFrame + VISUALISE spec to Altair chart
-chart = ggsql.render(df, viz)
+chart = ggsql.render_altair(df, viz)
 
 # Display or save the chart
 chart.display()  # In Jupyter
@@ -67,22 +67,22 @@ chart.save("chart.html")  # Save to file
 
 ### Mapping styles
 
-The `render()` function supports various mapping styles:
+The `render_altair()` function supports various mapping styles:
 
 ```python
 df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30], "category": ["A", "B", "A"]})
 
 # Explicit mapping
-ggsql.render(df, "VISUALISE x AS x, y AS y DRAW point")
+ggsql.render_altair(df, "VISUALISE x AS x, y AS y DRAW point")
 
 # Implicit mapping (column name = aesthetic name)
-ggsql.render(df, "VISUALISE x, y DRAW point")
+ggsql.render_altair(df, "VISUALISE x, y DRAW point")
 
 # Wildcard mapping (map all matching columns)
-ggsql.render(df, "VISUALISE * DRAW point")
+ggsql.render_altair(df, "VISUALISE * DRAW point")
 
 # With color encoding
-ggsql.render(df, "VISUALISE x, y, category AS color DRAW point")
+ggsql.render_altair(df, "VISUALISE x, y, category AS color DRAW point")
 ```
 
 ## API
@@ -100,14 +100,14 @@ Split a ggSQL query into SQL and VISUALISE portions.
 **Raises:**
 - `ValueError`: If the query cannot be parsed
 
-### `render(df, viz, *, writer="vegalite") -> altair.Chart`
+### `render_altair(df, viz, **kwargs) -> altair.Chart`
 
-Render a DataFrame with a VISUALISE specification.
+Render a DataFrame with a VISUALISE specification to an Altair chart.
 
 **Parameters:**
 - `df`: Any narwhals-compatible DataFrame (polars, pandas, etc.). LazyFrames are collected automatically.
 - `viz`: The VISUALISE specification string
-- `writer`: Output format, currently only `"vegalite"` is supported
+- `**kwargs`: Additional keyword arguments passed to `altair.Chart.from_json()`. Common options include `validate=False` to skip schema validation.
 
 **Returns:**
 - An `altair.Chart` object that can be displayed, saved, or further customized
diff --git a/ggsql-python/python/ggsql/__init__.py b/ggsql-python/python/ggsql/__init__.py
@@ -1,34 +1,23 @@
 from __future__ import annotations
-from typing import Literal, overload
+
+from typing import Any
 
 import altair
 import narwhals as nw
 from narwhals.typing import IntoFrame
 
 from ggsql._ggsql import split_query, render as _render
 
-__all__ = ["split_query", "render"]
+__all__ = ["split_query", "render_altair"]
 __version__ = "0.1.0"
 
-_SUPPORTED_WRITERS = {"vegalite"}
-
 
-@overload
-def render(
+def render_altair(
     df: IntoFrame,
     viz: str,
-    *,
-    writer: Literal["vegalite"] = ...,
-) -> altair.Chart: ...
-
-
-def render(
-    df: IntoFrame,
-    viz: str,
-    *,
-    writer: Literal["vegalite"] = "vegalite",
+    **kwargs: Any,
 ) -> altair.Chart:
-    """Render a DataFrame with a VISUALISE spec.
+    """Render a DataFrame with a VISUALISE spec to an Altair chart.
 
     Parameters
     ----------
@@ -37,19 +26,15 @@ def render(
         DataFrame. LazyFrames are collected automatically.
     viz
         VISUALISE spec string (e.g., "VISUALISE x, y DRAW point")
-    writer
-        Output format. Currently only "vegalite" supported.
+    **kwargs
+        Additional keyword arguments passed to `altair.Chart.from_json()`.
+        Common options include `validate=False` to skip schema validation.
 
     Returns
     -------
     altair.Chart
         An Altair chart object.
     """
-    if writer not in _SUPPORTED_WRITERS:
-        raise ValueError(
-            f"Unknown writer: {writer!r}. Supported writers: {', '.join(sorted(_SUPPORTED_WRITERS))}"
-        )
-
     df = nw.from_native(df, pass_through=True)
 
     if isinstance(df, nw.LazyFrame):
@@ -58,9 +43,8 @@ def render(
     if not isinstance(df, nw.DataFrame):
         raise TypeError("df must be a narwhals DataFrame or compatible type")
 
-    # Should be safe as long as we take polars dependency
     pl_df = df.to_polars()
 
-    vegalite_json = _render(pl_df, viz, writer=writer)
+    vegalite_json = _render(pl_df, viz, writer="vegalite")
 
-    return altair.Chart.from_json(vegalite_json)
+    return altair.Chart.from_json(vegalite_json, **kwargs)
diff --git a/ggsql-python/tests/test_ggsql.py b/ggsql-python/tests/test_ggsql.py
@@ -2,7 +2,6 @@
 
 These tests focus on Python-specific logic:
 - DataFrame conversion via narwhals
-- Writer parameter validation
 - Return type handling
 
 Rust logic (parsing, Vega-Lite generation) is tested in the Rust test suite.
@@ -31,17 +30,17 @@ def test_no_visualise_returns_empty_viz(self):
         assert viz == ""
 
 
-class TestRenderDataFrameConversion:
-    """Tests for DataFrame handling in render()."""
+class TestRenderAltairDataFrameConversion:
+    """Tests for DataFrame handling in render_altair()."""
 
     def test_accepts_polars_dataframe(self):
         df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
-        chart = ggsql.render(df, "VISUALISE x, y DRAW point")
+        chart = ggsql.render_altair(df, "VISUALISE x, y DRAW point")
         assert isinstance(chart, altair.TopLevelMixin)
 
     def test_accepts_polars_lazyframe(self):
         lf = pl.LazyFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
-        chart = ggsql.render(lf, "VISUALISE x, y DRAW point")
+        chart = ggsql.render_altair(lf, "VISUALISE x, y DRAW point")
         assert isinstance(chart, altair.TopLevelMixin)
 
     def test_accepts_narwhals_dataframe(self):
@@ -50,67 +49,48 @@ def test_accepts_narwhals_dataframe(self):
         pl_df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
         nw_df = nw.from_native(pl_df)
 
-        chart = ggsql.render(nw_df, "VISUALISE x, y DRAW point")
+        chart = ggsql.render_altair(nw_df, "VISUALISE x, y DRAW point")
         assert isinstance(chart, altair.TopLevelMixin)
 
     def test_accepts_pandas_dataframe(self):
         pd = pytest.importorskip("pandas")
 
         pd_df = pd.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
-        chart = ggsql.render(pd_df, "VISUALISE x, y DRAW point")
+        chart = ggsql.render_altair(pd_df, "VISUALISE x, y DRAW point")
         assert isinstance(chart, altair.TopLevelMixin)
 
     def test_rejects_invalid_dataframe_type(self):
         with pytest.raises(TypeError, match="must be a narwhals DataFrame"):
-            ggsql.render({"x": [1, 2, 3]}, "VISUALISE x, y DRAW point")
+            ggsql.render_altair({"x": [1, 2, 3]}, "VISUALISE x, y DRAW point")
 
 
-class TestRenderWriterValidation:
-    """Tests for writer parameter validation."""
-
-    def test_default_writer_is_vegalite(self):
-        df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
-        chart = ggsql.render(df, "VISUALISE x, y DRAW point")
-        assert isinstance(chart, altair.TopLevelMixin)
-
-    def test_explicit_vegalite_writer(self):
-        df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
-        chart = ggsql.render(df, "VISUALISE x, y DRAW point", writer="vegalite")
-        assert isinstance(chart, altair.TopLevelMixin)
-
-    def test_unknown_writer_raises(self):
-        df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
-        with pytest.raises(ValueError, match="Unknown writer.*Supported writers"):
-            ggsql.render(df, "VISUALISE x, y DRAW point", writer="ggplot2")
-
-
-class TestRenderReturnType:
-    """Tests for render() return type."""
+class TestRenderAltairReturnType:
+    """Tests for render_altair() return type."""
 
     def test_returns_altair_chart(self):
         df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
-        chart = ggsql.render(df, "VISUALISE x, y DRAW point")
+        chart = ggsql.render_altair(df, "VISUALISE x, y DRAW point")
         assert isinstance(chart, altair.TopLevelMixin)
 
     def test_chart_has_data(self):
         df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
-        chart = ggsql.render(df, "VISUALISE x, y DRAW point")
+        chart = ggsql.render_altair(df, "VISUALISE x, y DRAW point")
         spec = chart.to_dict()
         # Data should be embedded in datasets
         assert "datasets" in spec
 
     def test_chart_can_be_serialized(self):
         df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
-        chart = ggsql.render(df, "VISUALISE x, y DRAW point")
+        chart = ggsql.render_altair(df, "VISUALISE x, y DRAW point")
         # Should not raise
         json_str = chart.to_json()
         assert len(json_str) > 0
 
 
-class TestRenderErrorHandling:
-    """Tests for error handling in render()."""
+class TestRenderAltairErrorHandling:
+    """Tests for error handling in render_altair()."""
 
     def test_invalid_viz_raises(self):
         df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
         with pytest.raises(ValueError):
-            ggsql.render(df, "NOT VALID SYNTAX")
+            ggsql.render_altair(df, "NOT VALID SYNTAX")
