dataface 0.1.2__py3-none-any.whl

dataface/core/execute/duckdb_config.py

@@ -0,0 +1,26 @@
+"""DuckDB connection config validation shared by query and inspect paths."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+ALLOWED_DUCKDB_CONFIG_KEYS: frozenset[str] = frozenset({"enable_external_access"})
+
+
+def normalize_duckdb_config(
+    source_config: Mapping[str, Any],
+) -> dict[str, Any] | None:
+    """Return the configured DuckDB config mapping, if any."""
+    duckdb_config = source_config.get("duckdb_config")
+    if duckdb_config is None:
+        return None
+    if not isinstance(duckdb_config, dict):
+        raise ValueError("duckdb_config must be a mapping")
+    unknown = set(duckdb_config) - ALLOWED_DUCKDB_CONFIG_KEYS
+    if unknown:
+        raise ValueError(
+            f"Unsupported duckdb_config keys: {sorted(unknown)}. "
+            f"Allowed: {sorted(ALLOWED_DUCKDB_CONFIG_KEYS)}"
+        )
+    return dict(duckdb_config) if duckdb_config else None

dataface/core/execute/errors.py

@@ -0,0 +1,213 @@
+"""Execution error types.
+
+Stage: EXECUTE
+Purpose: Define error types for query execution failures.
+
+These errors are raised during:
+- Query execution (QueryError)
+- Adapter resolution/execution (AdapterError)
+- Connection failures (ConnectionError)
+
+All errors inherit from ExecutionError → DatafaceError for easy catching.
+"""
+
+from typing import Any
+
+from dataface.core.compile.errors import DatafaceError
+from dataface.core.errors.codes_execute import (
+    DF_EXECUTE_MUTATING_SQL,
+    DF_EXECUTE_UNPARSEABLE_SQL,
+)
+
+
+class ExecutionError(DatafaceError):
+    """Base error for all execution failures.
+
+    This is the parent class for all execution-related errors.
+    Catch this to handle any execution error.
+
+    Attributes:
+        message: Human-readable error description
+        query_name: Name of query that failed (if applicable)
+    """
+
+    # Class-level None default keeps `from_code`-constructed instances safe.
+    query_name: str | None = None
+
+    def __init__(self, message: str, query_name: str | None = None):
+        self.message = message
+        self.query_name = query_name
+        self.fields: dict[str, Any] = {}
+        super().__init__(self._format_message())
+        if self.code is None:
+            from dataface.core.errors.codes_unknown import DF_UNKNOWN_INTERNAL
+
+            self.code = DF_UNKNOWN_INTERNAL
+
+    def _format_message(self) -> str:
+        """Format error message with optional query name."""
+        if self.query_name:
+            return f"{self.message} (query: {self.query_name})"
+        return self.message
+
+
+class QueryError(ExecutionError):
+    """Error during query execution.
+
+    Raised when:
+    - SQL syntax is invalid
+    - Table/column doesn't exist
+    - Query returns unexpected results
+
+    Example:
+        >>> try:
+        ...     executor.execute_query("broken_query")
+        ... except QueryError as e:
+        ...     print(f"Query failed: {e}")
+    """
+
+    sql: str | None = None
+
+    def __init__(
+        self, message: str, query_name: str | None = None, sql: str | None = None
+    ):
+        self.sql = sql
+        super().__init__(f"Query execution failed: {message}", query_name)
+
+
+class AdapterError(ExecutionError):
+    """Error with adapter resolution or execution.
+
+    Raised when:
+    - Adapter not found for query type
+    - Adapter initialization fails
+    - Adapter-specific error occurs
+
+    Example:
+        >>> try:
+        ...     executor.execute_query("unknown_type_query")
+        ... except AdapterError as e:
+        ...     print(f"Adapter error: {e}")
+    """
+
+    adapter_type: str | None = None
+
+    def __init__(self, message: str, adapter_type: str | None = None):
+        self.adapter_type = adapter_type
+        super().__init__(f"Adapter error: {message}")
+
+
+class ConnectionError(ExecutionError):
+    """Error connecting to data source.
+
+    Raised when:
+    - Database connection fails
+    - HTTP endpoint unreachable
+    - File not found
+
+    Example:
+        >>> try:
+        ...     executor.execute_query("db_query")
+        ... except ConnectionError as e:
+        ...     print(f"Connection failed: {e}")
+    """
+
+    source: str | None = None
+
+    def __init__(self, message: str, source: str | None = None):
+        self.source = source
+        super().__init__(f"Connection failed: {message}")
+
+
+class QueryTimeoutError(ExecutionError):
+    """A query exceeded the per-query wall-clock timeout.
+
+    Raised when a warehouse query does not complete within the configured
+    timeout (``DFT_BQ_QUERY_TIMEOUT_SECONDS``).  The BQ job is
+    cancelled before this is raised.
+
+    Attributes:
+        elapsed: Elapsed wall-clock seconds at the point of timeout.
+        sql_preview: First 200 characters of the SQL that timed out.
+    """
+
+    elapsed: float | None = None
+    sql_preview: str | None = None
+
+    def __init__(
+        self,
+        elapsed: float,
+        sql_preview: str,
+        query_name: str | None = None,
+    ):
+        self.elapsed = elapsed
+        self.sql_preview = sql_preview
+        super().__init__(
+            f"Query timed out after {elapsed:.1f}s: {sql_preview!r}",
+            query_name=query_name,
+        )
+
+
+class MutatingSqlError(ExecutionError):
+    """SQL contains a statement type outside the validator's allowlist.
+
+    Raised by both `validate_select_only` (query allowlist) and
+    `validate_setup_sql` (setup allowlist). The `allowlist_label` arg
+    distinguishes the policy in the user-facing message.
+
+    Attributes:
+        rejected_node_kind: sqlglot expression class name (e.g. "Drop", "Insert").
+        fragment_preview: First ~60 chars of the rejected statement's .sql() output.
+        allowlist_label: "query" (default) or "setup" — names the policy violated.
+    """
+
+    rejected_node_kind: str | None = None
+    fragment_preview: str | None = None
+    allowlist_label: str = "query"
+
+    _QUERY_BODY = (
+        "  Allowed: SELECT, WITH, UNION, INTERSECT, EXCEPT, DESCRIBE, SHOW, "
+        "EXPLAIN of an allowed inner statement."
+    )
+    _SETUP_BODY = (
+        "  Allowed: CREATE TEMP FUNCTION / TEMP TABLE / TEMP VIEW (any dialect) "
+        "and CREATE [OR REPLACE] MACRO (DuckDB)."
+    )
+
+    def __init__(
+        self,
+        rejected_node_kind: str,
+        fragment_preview: str,
+        *,
+        allowlist_label: str = "query",
+    ):
+        self.rejected_node_kind = rejected_node_kind
+        self.fragment_preview = fragment_preview
+        self.allowlist_label = allowlist_label
+        self.code = DF_EXECUTE_MUTATING_SQL
+        body = self._SETUP_BODY if allowlist_label == "setup" else self._QUERY_BODY
+        policy = "setup_sql" if allowlist_label == "setup" else "read-only SQL"
+        msg = (
+            f"dft refuses to execute SQL outside the {policy} allowlist.\n\n"
+            f"  Statement: {rejected_node_kind}\n"
+            f"  Preview:   {fragment_preview}\n\n"
+            f"{body}\n"
+            f"  See dataface/core/execute/sql_guard.py for the full allowlist."
+        )
+        super().__init__(msg)
+
+
+class UnparseableSqlError(ExecutionError):
+    """SQL skeleton could not be determined — caller decides whether to defer.
+
+    Attributes:
+        cause: TemplateSyntaxError, sqlglot ParseError, or a str like
+               "unsupported_jinja_node:<NodeType>" for the bail-out-node case.
+    """
+
+    cause: Exception | str | None = None
+
+    def __init__(self, cause: Exception | str):
+        self.cause = cause
+        self.code = DF_EXECUTE_UNPARSEABLE_SQL
+        super().__init__(f"SQL could not be validated statically: {cause}")