Rename reader.execute to reader.execute_sql

Author: georgestagg

CLAUDE.md

@@ -207,7 +207,7 @@ let json = prepared.render(&writer)?;
 
 **Reader trait** (data source abstraction):
 
-- `execute(sql)` - Run SQL, return DataFrame
+- `execute_sql(sql)` - Run SQL, return DataFrame
 - `register(name, df)` - Register DataFrame as table
 - Implementation: `DuckDBReader`
 
@@ -505,7 +505,7 @@ pub type Result<T> = std::result::Result<T, GgsqlError>;
 
 ```rust
 pub trait Reader {
-    fn execute(&self, sql: &str) -> Result<DataFrame>;
+    fn execute_sql(&self, sql: &str) -> Result<DataFrame>;
     fn supports_query(&self, sql: &str) -> bool;
 }
 ```
@@ -871,7 +871,7 @@ When running in Positron IDE, the extension provides enhanced functionality:
 - PyO3-based Rust bindings compiled to a native Python extension
 - Two-stage API mirroring the Rust API: `prepare()` → `render()`
 - DuckDB reader with DataFrame registration
-- Custom Python reader support: any object with `execute(sql) -> DataFrame` method
+- Custom Python reader support: any object with `execute_sql(sql) -> DataFrame` method
 - Works with any narwhals-compatible DataFrame (polars, pandas, etc.)
 - LazyFrames are collected automatically
 - Returns native `altair.Chart` objects via `render_altair()` convenience function
@@ -976,7 +976,7 @@ print(f"Errors: {validated.errors()}")
 
 **Custom Python Readers**:
 
-Any Python object with an `execute(sql: str) -> polars.DataFrame` method can be used as a reader:
+Any Python object with an `execute_sql(sql: str) -> polars.DataFrame` method can be used as a reader:
 
 ```python
 import ggsql
@@ -985,7 +985,7 @@ import polars as pl
 class MyReader:
     """Custom reader that returns static data."""
 
-    def execute(self, sql: str) -> pl.DataFrame:
+    def execute_sql(self, sql: str) -> pl.DataFrame:
         return pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
 
 # Use custom reader with prepare()

ggsql-jupyter/src/executor.rs

@@ -60,7 +60,7 @@ impl QueryExecutor {
         // 2. Check if there's a visualization
         if !validated.has_visual() {
             // Pure SQL query - execute directly and return DataFrame
-            let df = self.reader.execute(code)?;
+            let df = self.reader.execute_sql(code)?;
             tracing::info!(
                 "Pure SQL executed: {} rows, {} cols",
                 df.height(),

ggsql-python/README.md

@@ -127,7 +127,7 @@ reader = ggsql.DuckDBReader("duckdb:///path/to/file.db")  # File database
 **Methods:**
 
 - `register(name: str, df: polars.DataFrame)` - Register a DataFrame as a queryable table
-- `execute(sql: str) -> polars.DataFrame` - Execute SQL and return results
+- `execute_sql(sql: str) -> polars.DataFrame` - Execute SQL and return results
 - `supports_register() -> bool` - Check if registration is supported
 
 #### `VegaLiteWriter()`
@@ -236,7 +236,7 @@ ggsql.render_altair(df, "VISUALISE x, y, category AS color DRAW point")
 
 ### Custom Readers
 
-You can use any Python object with an `execute(sql: str) -> polars.DataFrame` method as a reader. This enables integration with any data source.
+You can use any Python object with an `execute_sql(sql: str) -> polars.DataFrame` method as a reader. This enables integration with any data source.
 
 ```python
 import ggsql
@@ -248,7 +248,7 @@ class CSVReader:
     def __init__(self, data_dir: str):
         self.data_dir = data_dir
 
-    def execute(self, sql: str) -> pl.DataFrame:
+    def execute_sql(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")
@@ -275,7 +275,7 @@ class AdvancedReader:
     def __init__(self):
         self.tables = {}
 
-    def execute(self, sql: str) -> pl.DataFrame:
+    def execute_sql(self, sql: str) -> pl.DataFrame:
         # Your SQL execution logic here
         ...
 

ggsql-python/src/lib.rs

@@ -62,7 +62,7 @@ fn py_to_polars_inner(df: &Bound<'_, PyAny>) -> PyResult<DataFrame> {
 
     df.call_method1("write_ipc", (&bytes_io,)).map_err(|_| {
         PyErr::new::<pyo3::exceptions::PyTypeError, _>(
-            "Reader.execute() must return a polars.DataFrame",
+            "Reader.execute_sql() must return a polars.DataFrame",
         )
     })?;
 
@@ -127,12 +127,12 @@ struct PyReaderBridge {
 }
 
 impl Reader for PyReaderBridge {
-    fn execute(&self, sql: &str) -> ggsql::Result<DataFrame> {
+    fn execute_sql(&self, sql: &str) -> ggsql::Result<DataFrame> {
         Python::attach(|py| {
             let bound = self.obj.bind(py);
             let result = bound
-                .call_method1("execute", (sql,))
-                .map_err(|e| GgsqlError::ReaderError(format!("Reader.execute() failed: {}", e)))?;
+                .call_method1("execute_sql", (sql,))
+                .map_err(|e| GgsqlError::ReaderError(format!("Reader.execute_sql() failed: {}", e)))?;
             py_to_polars_inner(&result).map_err(|e| GgsqlError::ReaderError(e.to_string()))
         })
     }
@@ -190,11 +190,11 @@ macro_rules! try_native_readers {
 /// Examples
 /// --------
 /// >>> reader = DuckDBReader("duckdb://memory")
-/// >>> df = reader.execute("SELECT 1 as x, 2 as y")
+/// >>> df = reader.execute_sql("SELECT 1 as x, 2 as y")
 ///
 /// >>> reader = DuckDBReader("duckdb://memory")
 /// >>> reader.register("data", pl.DataFrame({"x": [1, 2, 3]}))
-/// >>> df = reader.execute("SELECT * FROM data WHERE x > 1")
+/// >>> df = reader.execute_sql("SELECT * FROM data WHERE x > 1")
 #[pyclass(name = "DuckDBReader", unsendable)]
 struct PyDuckDBReader {
     inner: RustDuckDBReader,
@@ -264,10 +264,10 @@ impl PyDuckDBReader {
     /// ------
     /// ValueError
     ///     If the SQL is invalid or execution fails.
-    fn execute(&self, py: Python<'_>, sql: &str) -> PyResult<Py<PyAny>> {
+    fn execute_sql(&self, py: Python<'_>, sql: &str) -> PyResult<Py<PyAny>> {
         let df = self
             .inner
-            .execute(sql)
+            .execute_sql(sql)
             .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))?;
         polars_to_py(py, &df)
     }

ggsql-python/tests/test_ggsql.py

@@ -62,7 +62,7 @@ def test_create_in_memory(self):
 
     def test_execute_simple_query(self):
         reader = ggsql.DuckDBReader("duckdb://memory")
-        df = reader.execute("SELECT 1 AS x, 2 AS y")
+        df = reader.execute_sql("SELECT 1 AS x, 2 AS y")
         assert isinstance(df, pl.DataFrame)
         assert df.shape == (1, 2)
         assert list(df.columns) == ["x", "y"]
@@ -72,7 +72,7 @@ def test_register_and_query(self):
         df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
         reader.register("my_data", df)
 
-        result = reader.execute("SELECT * FROM my_data WHERE x > 1")
+        result = reader.execute_sql("SELECT * FROM my_data WHERE x > 1")
         assert isinstance(result, pl.DataFrame)
         assert result.shape == (2, 2)
 
@@ -406,7 +406,7 @@ def test_simple_custom_reader(self):
         """Custom reader with execute() method works."""
 
         class SimpleReader:
-            def execute(self, sql: str) -> pl.DataFrame:
+            def execute_sql(self, sql: str) -> pl.DataFrame:
                 return pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
 
         reader = SimpleReader()
@@ -420,7 +420,7 @@ class RegisterReader:
             def __init__(self):
                 self.tables = {}
 
-            def execute(self, sql: str) -> pl.DataFrame:
+            def execute_sql(self, sql: str) -> pl.DataFrame:
                 # Simple: just return the first registered table
                 if self.tables:
                     return next(iter(self.tables.values()))
@@ -442,7 +442,7 @@ def test_custom_reader_error_handling(self):
         """Custom reader errors are propagated."""
 
         class ErrorReader:
-            def execute(self, sql: str) -> pl.DataFrame:
+            def execute_sql(self, sql: str) -> pl.DataFrame:
                 raise ValueError("Custom reader error")
 
         reader = ErrorReader()
@@ -453,7 +453,7 @@ def test_custom_reader_wrong_return_type(self):
         """Custom reader returning wrong type raises TypeError."""
 
         class WrongTypeReader:
-            def execute(self, sql: str):
+            def execute_sql(self, sql: str):
                 return {"x": [1, 2, 3]}  # dict, not DataFrame
 
         reader = WrongTypeReader()
@@ -472,7 +472,7 @@ def test_custom_reader_can_render(self):
         """Custom reader result can be rendered to Vega-Lite."""
 
         class StaticReader:
-            def execute(self, sql: str) -> pl.DataFrame:
+            def execute_sql(self, sql: str) -> pl.DataFrame:
                 return pl.DataFrame(
                     {
                         "x": [1, 2, 3, 4, 5],
@@ -501,7 +501,7 @@ class RecordingReader:
             def __init__(self):
                 self.execute_calls = []
 
-            def execute(self, sql: str) -> pl.DataFrame:
+            def execute_sql(self, sql: str) -> pl.DataFrame:
                 self.execute_calls.append(sql)
                 return pl.DataFrame({"x": [1], "y": [2]})
 

src/api.rs

@@ -245,7 +245,7 @@ pub fn prepare(query: &str, reader: &dyn Reader) -> Result<Prepared> {
     let warnings: Vec<ValidationWarning> = validated.warnings().to_vec();
 
     // Prepare data (this also validates, but we want the warnings from above)
-    let prepared_data = prepare_data_with_executor(query, |sql| reader.execute(sql))?;
+    let prepared_data = prepare_data_with_executor(query, |sql| reader.execute_sql(sql))?;
 
     Ok(Prepared::new(
         prepared_data.spec,

src/cli.rs

@@ -335,7 +335,7 @@ fn print_table_fallback(query: &str, reader: &DuckDBReader, max_rows: usize) {
     }
     let parsed = parsed.unwrap();
 
-    let data = reader.execute(&parsed);
+    let data = reader.execute_sql(&parsed);
     if let Err(e) = data {
         eprintln!("Failed to execute SQL query: {}", e);
         std::process::exit(1)

src/doc/API.md

@@ -374,7 +374,7 @@ pub struct Location {
 ```rust
 pub trait Reader {
     /// Execute a SQL query and return a DataFrame
-    fn execute(&self, sql: &str) -> Result<DataFrame>;
+    fn execute_sql(&self, sql: &str) -> Result<DataFrame>;
 
     /// Register a DataFrame as a queryable table
     fn register(&mut self, name: &str, df: DataFrame) -> Result<()>;
@@ -425,7 +425,7 @@ class DuckDBReader:
             df: Polars DataFrame or narwhals-compatible DataFrame
         """
 
-    def execute(self, sql: str) -> polars.DataFrame:
+    def execute_sql(self, sql: str) -> polars.DataFrame:
         """Execute SQL and return a Polars DataFrame."""
 
     def supports_register(self) -> bool:

src/execute.rs

@@ -1185,7 +1185,7 @@ where
 /// Convenience wrapper around `prepare_data_with_executor` for direct DuckDB reader usage.
 #[cfg(feature = "duckdb")]
 pub fn prepare_data(query: &str, reader: &DuckDBReader) -> Result<PreparedData> {
-    prepare_data_with_executor(query, |sql| reader.execute(sql))
+    prepare_data_with_executor(query, |sql| reader.execute_sql(sql))
 }
 
 #[cfg(test)]

src/lib.rs

@@ -116,7 +116,7 @@ mod integration_tests {
             FROM generate_series(0, 4) as t(n)
         "#;
 
-        let df = reader.execute(sql).unwrap();
+        let df = reader.execute_sql(sql).unwrap();
 
         // Verify DataFrame has temporal type (DuckDB returns Datetime for DATE + INTERVAL)
         assert_eq!(df.get_column_names(), vec!["date", "revenue"]);
@@ -176,7 +176,7 @@ mod integration_tests {
             FROM generate_series(0, 3) as t(n)
         "#;
 
-        let df = reader.execute(sql).unwrap();
+        let df = reader.execute_sql(sql).unwrap();
 
         // Verify DataFrame has Datetime type
         let timestamp_col = df.column("timestamp").unwrap();
@@ -224,7 +224,7 @@ mod integration_tests {
 
         // Real SQL that users would write
         let sql = "SELECT 1 as int_col, 2.5 as float_col, true as bool_col";
-        let df = reader.execute(sql).unwrap();
+        let df = reader.execute_sql(sql).unwrap();
 
         // Verify types are preserved
         // DuckDB treats numeric literals as DECIMAL, which we convert to Float64
@@ -279,7 +279,7 @@ mod integration_tests {
         let reader = DuckDBReader::from_connection_string("duckdb://memory").unwrap();
 
         let sql = "SELECT * FROM (VALUES (1, 2.5, 'a'), (2, NULL, 'b'), (NULL, 3.5, NULL)) AS t(int_col, float_col, str_col)";
-        let df = reader.execute(sql).unwrap();
+        let df = reader.execute_sql(sql).unwrap();
 
         // Verify types
         assert!(matches!(
@@ -329,7 +329,7 @@ mod integration_tests {
         let reader = DuckDBReader::from_connection_string("duckdb://memory").unwrap();
 
         let sql = "SELECT * FROM (VALUES ('A', 10), ('B', 20), ('A', 15), ('C', 30)) AS t(category, value)";
-        let df = reader.execute(sql).unwrap();
+        let df = reader.execute_sql(sql).unwrap();
 
         let mut spec = Plot::new();
         let layer = Layer::new(Geom::bar())
@@ -375,7 +375,7 @@ mod integration_tests {
             GROUP BY day
         "#;
 
-        let df = reader.execute(sql).unwrap();
+        let df = reader.execute_sql(sql).unwrap();
 
         // Verify temporal type is preserved through aggregation
         // DATE_TRUNC returns Date type (not Datetime)
@@ -413,7 +413,7 @@ mod integration_tests {
         let reader = DuckDBReader::from_connection_string("duckdb://memory").unwrap();
 
         let sql = "SELECT 0.1 as small, 123.456 as medium, 999999.999999 as large";
-        let df = reader.execute(sql).unwrap();
+        let df = reader.execute_sql(sql).unwrap();
 
         // All should be Float64
         assert!(matches!(
@@ -465,7 +465,7 @@ mod integration_tests {
         let reader = DuckDBReader::from_connection_string("duckdb://memory").unwrap();
 
         let sql = "SELECT CAST(1 AS TINYINT) as tiny, CAST(1000 AS SMALLINT) as small, CAST(1000000 AS INTEGER) as int, CAST(1000000000000 AS BIGINT) as big";
-        let df = reader.execute(sql).unwrap();
+        let df = reader.execute_sql(sql).unwrap();
 
         // Verify types
         assert!(matches!(
@@ -533,7 +533,7 @@ mod integration_tests {
 
         // Prepare data - this parses, injects constants into global data, and replaces literals with columns
         let prepared =
-            execute::prepare_data_with_executor(query, |sql| reader.execute(sql)).unwrap();
+            execute::prepare_data_with_executor(query, |sql| reader.execute_sql(sql)).unwrap();
 
         // Verify constants were injected into global data (not layer-specific data)
         // Both layers share __global__ data for faceting compatibility
@@ -641,7 +641,7 @@ mod integration_tests {
         "#;
 
         let prepared =
-            execute::prepare_data_with_executor(query, |sql| reader.execute(sql)).unwrap();
+            execute::prepare_data_with_executor(query, |sql| reader.execute_sql(sql)).unwrap();
 
         // All layers should use global data for faceting to work
         assert!(
@@ -729,7 +729,7 @@ mod integration_tests {
         "#;
 
         let prepared =
-            execute::prepare_data_with_executor(query, |sql| reader.execute(sql)).unwrap();
+            execute::prepare_data_with_executor(query, |sql| reader.execute_sql(sql)).unwrap();
 
         // Should have global data with the constant injected
         assert!(