feat(python): add Reader protocol for custom reader contract

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cpsievert

ggsql-python/python/ggsql/__init__.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
 import json
-from typing import Any, Union
+from typing import Any, Protocol, Union, runtime_checkable
 
 import altair
 import narwhals as nw
 from narwhals.typing import IntoFrame
+import polars as pl
 
 from ggsql._ggsql import (
     DuckDBReader,
@@ -22,12 +23,13 @@
     "VegaLiteWriter",
     "Validated",
     "Spec",
+    "Reader",
     # Functions
     "validate",
     "execute",
     "render_altair",
 ]
-__version__ = "0.1.0"
+__version__ = "0.1.4"
 
 # Type alias for any Altair chart type
 AltairChart = Union[
@@ -41,6 +43,29 @@
 ]
 
 
+@runtime_checkable
+class Reader(Protocol):
+    """Protocol for ggsql database readers.
+
+    Any object implementing these methods can be used as a reader with
+    ``ggsql.execute()``. Native readers like ``DuckDBReader`` satisfy
+    this protocol automatically.
+
+    Required methods
+    ----------------
+    execute_sql(sql: str) -> polars.DataFrame
+        Execute a SQL query and return results as a polars DataFrame.
+    register(name: str, df: polars.DataFrame, replace: bool = False) -> None
+        Register a DataFrame as a named table for SQL queries.
+    """
+
+    def execute_sql(self, sql: str) -> pl.DataFrame: ...
+
+    def register(
+        self, name: str, df: pl.DataFrame, replace: bool = False
+    ) -> None: ...
+
+
 def render_altair(
     df: IntoFrame,
     viz: str,

ggsql-python/tests/test_ggsql.py

@@ -530,3 +530,42 @@ def unregister(self, name: str) -> None:
         writer = ggsql.VegaLiteWriter()
         json_output = writer.render(spec)
         assert "point" in json_output
+
+
+class TestReaderProtocol:
+    """Tests for Reader protocol."""
+
+    def test_duckdb_reader_is_reader(self):
+        """Native DuckDBReader satisfies the Reader protocol."""
+        reader = ggsql.DuckDBReader("duckdb://memory")
+        assert isinstance(reader, ggsql.Reader)
+
+    def test_custom_reader_is_reader(self):
+        """Custom reader with correct methods satisfies the Reader protocol."""
+
+        class MyReader:
+            def execute_sql(self, sql: str) -> pl.DataFrame:
+                return pl.DataFrame({"x": [1]})
+
+            def register(
+                self, name: str, df: pl.DataFrame, replace: bool = False
+            ) -> None:
+                pass
+
+        reader = MyReader()
+        assert isinstance(reader, ggsql.Reader)
+
+    def test_incomplete_reader_is_not_reader(self):
+        """Object missing required methods is not a Reader."""
+
+        class NotAReader:
+            def execute_sql(self, sql: str) -> pl.DataFrame:
+                return pl.DataFrame({"x": [1]})
+            # Missing register()
+
+        obj = NotAReader()
+        assert not isinstance(obj, ggsql.Reader)
+
+    def test_reader_is_exported(self):
+        """Reader is accessible from ggsql module."""
+        assert hasattr(ggsql, "Reader")