feat(python): add typed exception classes (ParseError, ValidationError, ReaderError, WriterError)

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

Author: cpsievert

ggsql-python/python/ggsql/__init__.py

@@ -15,6 +15,10 @@
     Spec,
     validate,
     execute,
+    ParseError,
+    ValidationError,
+    ReaderError,
+    WriterError,
 )
 
 __all__ = [
@@ -28,6 +32,11 @@
     "validate",
     "execute",
     "render_altair",
+    # Exceptions
+    "ParseError",
+    "ValidationError",
+    "ReaderError",
+    "WriterError",
 ]
 __version__ = "0.1.4"
 

ggsql-python/src/lib.rs

@@ -3,6 +3,8 @@
 #![allow(clippy::useless_conversion)]
 
 use pyo3::prelude::*;
+use pyo3::create_exception;
+use pyo3::exceptions::PyValueError;
 use pyo3::types::{PyBytes, PyDict, PyList};
 use std::io::Cursor;
 
@@ -12,6 +14,28 @@ use ggsql::validate::{validate as rust_validate, ValidationWarning};
 use ggsql::writer::{VegaLiteWriter as RustVegaLiteWriter, Writer as RustWriter};
 use ggsql::GgsqlError;
 
+// ============================================================================
+// Custom Exception Classes
+// ============================================================================
+
+// All subclass ValueError for backwards compatibility
+create_exception!(ggsql, ParseError, PyValueError, "Raised on query syntax errors.");
+create_exception!(ggsql, ValidationError, PyValueError, "Raised on semantic validation errors.");
+create_exception!(ggsql, ReaderError, PyValueError, "Raised on data source errors.");
+create_exception!(ggsql, WriterError, PyValueError, "Raised on output generation errors.");
+
+/// Convert a GgsqlError to the appropriate typed Python exception.
+fn ggsql_err_to_py(e: GgsqlError) -> PyErr {
+    let msg = e.to_string();
+    match e {
+        GgsqlError::ParseError(_) => PyErr::new::<ParseError, _>(msg),
+        GgsqlError::ValidationError(_) => PyErr::new::<ValidationError, _>(msg),
+        GgsqlError::ReaderError(_) => PyErr::new::<ReaderError, _>(msg),
+        GgsqlError::WriterError(_) => PyErr::new::<WriterError, _>(msg),
+        GgsqlError::InternalError(_) => PyErr::new::<PyValueError, _>(msg),
+    }
+}
+
 use polars::prelude::{DataFrame, IpcReader, IpcWriter, SerReader, SerWriter};
 
 // ============================================================================
@@ -175,7 +199,7 @@ macro_rules! try_native_readers {
             if let Ok(native) = $reader.downcast::<$native_type>() {
                 return native.borrow().inner.execute($query)
                     .map(|s| PySpec { inner: s })
-                    .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()));
+                    .map_err(ggsql_err_to_py);
             }
         )*
     }};
@@ -225,7 +249,7 @@ impl PyDuckDBReader {
     #[new]
     fn new(connection: &str) -> PyResult<Self> {
         let inner = RustDuckDBReader::from_connection_string(connection)
-            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))?;
+            .map_err(ggsql_err_to_py)?;
         Ok(Self { inner })
     }
 
@@ -255,7 +279,7 @@ impl PyDuckDBReader {
         let rust_df = py_to_polars(py, df)?;
         self.inner
             .register(name, rust_df, replace)
-            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))
+            .map_err(ggsql_err_to_py)
     }
 
     /// Unregister a previously registered table.
@@ -272,7 +296,7 @@ impl PyDuckDBReader {
     fn unregister(&self, name: &str) -> PyResult<()> {
         self.inner
             .unregister(name)
-            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))
+            .map_err(ggsql_err_to_py)
     }
 
     /// Execute a SQL query and return the result as a DataFrame.
@@ -295,7 +319,7 @@ impl PyDuckDBReader {
         let df = self
             .inner
             .execute_sql(sql)
-            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))?;
+            .map_err(ggsql_err_to_py)?;
         polars_to_py(py, &df)
     }
 
@@ -330,7 +354,7 @@ impl PyDuckDBReader {
         self.inner
             .execute(query)
             .map(|s| PySpec { inner: s })
-            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))
+            .map_err(ggsql_err_to_py)
     }
 }
 
@@ -393,7 +417,7 @@ impl PyVegaLiteWriter {
     fn render(&self, spec: &PySpec) -> PyResult<String> {
         self.inner
             .render(&spec.inner)
-            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))
+            .map_err(ggsql_err_to_py)
     }
 }
 
@@ -658,7 +682,7 @@ impl PySpec {
 #[pyfunction]
 fn validate(query: &str) -> PyResult<PyValidated> {
     let v = rust_validate(query)
-        .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))?;
+        .map_err(ggsql_err_to_py)?;
 
     Ok(PyValidated {
         sql: v.sql().to_string(),
@@ -739,7 +763,7 @@ fn execute(query: &str, reader: &Bound<'_, PyAny>) -> PyResult<PySpec> {
     bridge
         .execute(query)
         .map(|s| PySpec { inner: s })
-        .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))
+        .map_err(ggsql_err_to_py)
 }
 
 // ============================================================================
@@ -748,6 +772,12 @@ fn execute(query: &str, reader: &Bound<'_, PyAny>) -> PyResult<PySpec> {
 
 #[pymodule]
 fn _ggsql(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    // Exceptions
+    m.add("ParseError", m.py().get_type::<ParseError>())?;
+    m.add("ValidationError", m.py().get_type::<ValidationError>())?;
+    m.add("ReaderError", m.py().get_type::<ReaderError>())?;
+    m.add("WriterError", m.py().get_type::<WriterError>())?;
+
     // Classes
     m.add_class::<PyDuckDBReader>()?;
     m.add_class::<PyVegaLiteWriter>()?;

ggsql-python/tests/test_ggsql.py

@@ -532,6 +532,53 @@ def unregister(self, name: str) -> None:
         assert "point" in json_output
 
 
+class TestExceptions:
+    """Tests for typed exception classes."""
+
+    def test_parse_error_on_invalid_syntax(self):
+        """Invalid syntax raises ParseError when executing."""
+        with pytest.raises(ggsql.ParseError):
+            reader = ggsql.DuckDBReader("duckdb://memory")
+            reader.execute("SELECT 1 AS x VISUALISE DRAW not_a_geom")
+
+    def test_parse_error_is_value_error(self):
+        """ParseError is a subclass of ValueError for backwards compat."""
+        assert issubclass(ggsql.ParseError, ValueError)
+
+    def test_validation_error_on_missing_aesthetic(self):
+        """Missing required aesthetic raises ValidationError."""
+        with pytest.raises(ggsql.ValidationError):
+            reader = ggsql.DuckDBReader("duckdb://memory")
+            reader.execute("SELECT 1 AS x VISUALISE DRAW point MAPPING x AS x")
+
+    def test_validation_error_is_value_error(self):
+        """ValidationError is a subclass of ValueError for backwards compat."""
+        assert issubclass(ggsql.ValidationError, ValueError)
+
+    def test_reader_error_on_bad_sql(self):
+        """Bad SQL raises ReaderError."""
+        with pytest.raises(ggsql.ReaderError):
+            reader = ggsql.DuckDBReader("duckdb://memory")
+            reader.execute(
+                "SELECT * FROM nonexistent_table VISUALISE DRAW point MAPPING x AS x, y AS y"
+            )
+
+    def test_reader_error_is_value_error(self):
+        """ReaderError is a subclass of ValueError for backwards compat."""
+        assert issubclass(ggsql.ReaderError, ValueError)
+
+    def test_writer_error_is_value_error(self):
+        """WriterError is a subclass of ValueError for backwards compat."""
+        assert issubclass(ggsql.WriterError, ValueError)
+
+    def test_all_exceptions_exported(self):
+        """All exception classes are accessible from ggsql module."""
+        assert hasattr(ggsql, "ParseError")
+        assert hasattr(ggsql, "ValidationError")
+        assert hasattr(ggsql, "ReaderError")
+        assert hasattr(ggsql, "WriterError")
+
+
 class TestReaderProtocol:
     """Tests for Reader protocol."""