dataface 0.1.2__py3-none-any.whl

dataface/core/execute/adapters/base.py

@@ -0,0 +1,245 @@
+"""Base adapter interface for query execution.
+
+Stage: EXECUTE
+Purpose: Define the base interface and types for query adapters.
+
+All adapters inherit from BaseAdapter and implement the unified query interface.
+QueryResult is the standard return type for all adapter executions.
+
+The unified interface uses:
+- `supported_types` property: Set of query types this adapter handles
+- `can_execute()`: Uses supported_types for type-based routing
+- `execute()`: Executes the query using type guards for type safety
+
+Security:
+- Adapters support parameterized queries via the optional `params` argument
+- When params are provided, values are passed to the database driver separately
+  from the SQL, preventing SQL injection
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from dataface.core.compile.models.face.compiled import VariableValues
+from dataface.core.compile.models.query.compiled import AnyQuery
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.source import SourceConfig
+
+# Type alias for query parameters
+QueryParams = list[Any] | None
+
+SchemaStatus = Literal["changed", "unchanged", "unknown"]
+
+
+@dataclass(frozen=True)
+class ResolvedRelation:
+    """A dbt ref/source resolved during query execution.
+
+    Tracks which schema each relation resolved to and whether it
+    differs from the production baseline (changed vs unchanged).
+    """
+
+    ref_name: str
+    schema: str
+    status: SchemaStatus
+
+
+class QueryResult:
+    """Result of a query execution.
+
+    This is the standard return type for all adapter executions, providing
+    a consistent interface for data retrieval and error handling.
+
+    Attributes:
+        data: List of dictionaries containing query results (each dict is a row)
+        columns: List of column names
+        column_descriptions: Full PEP 249 cursor.description tuples keyed by column name.
+            Each tuple: (name, type_code, display_size, internal_size, precision, scale, null_ok)
+        error: Error message if query failed, None if successful
+    """
+
+    def __init__(
+        self,
+        data: list[dict[str, Any]],
+        columns: list[str] | None = None,
+        column_descriptions: dict[str, tuple] | None = None,
+        error: str | None = None,
+        resolved_relations: list[ResolvedRelation] | None = None,
+    ):
+        """Initialize query result.
+
+        Args:
+            data: List of dictionaries containing query results (each dict is a row)
+            columns: Optional list of column names (inferred from data if not provided)
+            column_descriptions: Optional PEP 249 cursor.description tuples keyed by
+                column name. Each value is a 7-tuple: (name, type_code, display_size,
+                internal_size, precision, scale, null_ok). Populated from
+                cursor.description when a database adapter executes the query.
+            error: Optional error message if query failed
+            resolved_relations: dbt ref/source relations resolved during execution,
+                with dev-vs-prod schema status for each.
+        """
+        self.data = data or []
+        if columns is None and self.data:
+            self.columns = list(self.data[0].keys())
+        else:
+            self.columns = columns or []
+        self.column_descriptions = column_descriptions
+        self.error = error
+        self.resolved_relations: list[ResolvedRelation] = resolved_relations or []
+
+    @property
+    def is_success(self) -> bool:
+        """Check if query executed successfully."""
+        return self.error is None
+
+
+def handle_adapter_error(operation: str, error: Exception) -> QueryResult:
+    """Standard error handling for adapters.
+
+    Provides consistent error handling across all adapters, ensuring
+    uniform error messages and making it easier to add logging/metrics
+    in one place.
+
+    Args:
+        operation: Description of the operation that failed (e.g., "SQL execution", "HTTP request")
+        error: The exception that occurred
+
+    Returns:
+        QueryResult with error information
+    """
+    return QueryResult(
+        data=[],
+        error=f"{operation} failed: {str(error)}",
+    )
+
+
+class BaseAdapter(ABC):
+    """Base interface for query adapters.
+
+    All adapters must implement this interface to execute queries
+    against different backends (MetricFlow, SQL, HTTP, CSV, etc.).
+
+    The unified interface pattern uses:
+    - `supported_types`: Property returning set of query types this adapter handles
+    - Type guards for type-safe field access in execute methods
+
+    Subclasses must implement:
+        - supported_types: Property returning Set[str] of supported query types
+        - _execute(): Perform the actual query execution
+
+    Optional override:
+        - _can_execute(): Override for custom eligibility logic beyond type matching
+
+    Example:
+        >>> class MyAdapter(BaseAdapter):
+        ...     @property
+        ...     def supported_types(self) -> Set[str]:
+        ...         return {"sql"}
+        ...
+        ...     def _execute(self, query, variables):
+        ...         if is_sql_query(query):
+        ...             # Type checker knows query.sql exists
+        ...             return self._run_sql(query.sql)
+    """
+
+    @property
+    @abstractmethod
+    def supported_types(self) -> set[str]:
+        """Query types this adapter can execute.
+
+        Returns:
+            Set of query type strings (e.g., {"sql"}, {"csv", "http"})
+
+        Example:
+            >>> adapter.supported_types
+            {"sql"}
+        """
+        pass
+
+    def can_execute(self, query: AnyQuery) -> bool:
+        """Check if this adapter can execute the given query.
+
+        Uses supported_types for type-based routing. Override _can_execute()
+        for additional custom eligibility logic.
+
+        Args:
+            query: AnyQuery object (guaranteed by compiler)
+
+        Returns:
+            True if this adapter can execute the query, False otherwise
+        """
+        # First check if type is supported
+        if query.query_type not in self.supported_types:
+            return False
+        # Then check any additional conditions
+        return self._can_execute(query)
+
+    def _can_execute(self, query: AnyQuery) -> bool:
+        """Additional eligibility check beyond type matching.
+
+        Override this method to add custom eligibility logic.
+        The base implementation always returns True.
+
+        Args:
+            query: AnyQuery object (guaranteed)
+
+        Returns:
+            True if this adapter can execute the query, False otherwise
+        """
+        return True
+
+    def execute(
+        self,
+        query: AnyQuery,
+        variables: VariableValues | None = None,
+        params: QueryParams = None,
+        source_config: SourceConfig | None = None,
+    ) -> QueryResult:
+        """Execute a query and return results.
+
+        Args:
+            query: AnyQuery object (guaranteed by compiler)
+            variables: Optional dictionary of variable values for query resolution
+            params: Optional pre-computed parameter values for parameterized execution.
+                When provided, the adapter should use these params directly instead
+                of re-processing variables. This is used by batch execution where
+                parameterization happens before adapter execution.
+            source_config: Typed source config resolved by SourceResolver before
+                adapter dispatch. SqlAdapter consumes this; other adapters ignore it.
+
+        Returns:
+            QueryResult containing data or error information
+        """
+        return self._execute(query, variables, params, source_config)
+
+    @abstractmethod
+    def _execute(
+        self,
+        query: AnyQuery,
+        variables: VariableValues | None = None,
+        params: QueryParams = None,
+        source_config: SourceConfig | None = None,
+    ) -> QueryResult:
+        """Internal method to execute query.
+
+        Use type guards for type-safe field access:
+            if is_sql_query(query):
+                sql = query.sql  # Type checker knows this is str
+
+        Args:
+            query: AnyQuery object (guaranteed)
+            variables: Optional dictionary of variable values for query resolution
+            params: Optional pre-computed parameter values. When provided, skip
+                internal parameterization and use these params directly.
+            source_config: Typed source config from SourceResolver; SqlAdapter
+                reads it, other adapters accept and ignore.
+
+        Returns:
+            QueryResult containing data or error information
+        """
+        pass

dataface/core/execute/adapters/csv_adapter.py

@@ -0,0 +1,239 @@
+"""CSV adapter for executing queries against CSV files.
+
+Stage: EXECUTE
+Purpose: Load and query data from CSV files.
+
+This adapter allows users to load data from CSV files stored in their
+project's assets/data directory or other specified paths. It supports
+basic filtering and column selection via query parameters.
+"""
+
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.source import SourceConfig
+
+from dataface.core.compile.jinja import resolve_jinja_template
+from dataface.core.compile.models.face.compiled import VariableValues
+from dataface.core.compile.models.query.compiled import (
+    AnyQuery,
+    is_csv_query,
+)
+from dataface.core.execute.adapters.base import (
+    BaseAdapter,
+    QueryParams,
+    QueryResult,
+    handle_adapter_error,
+)
+
+
+def _coerce_csv_value(v: str) -> str | int | float:
+    """Try to parse a CSV string as int, then float; return the original string on failure."""
+    try:
+        return int(v)
+    except ValueError:
+        pass
+    try:
+        return float(v)
+    except ValueError:
+        return v
+
+
+class CsvAdapter(BaseAdapter):
+    """Adapter for executing queries against CSV files.
+
+    Supported query types: csv
+
+    Loads data from CSV files and supports:
+    - Column selection
+    - Row filtering (exact match, AND logic)
+    - Result limiting
+
+    Example:
+        >>> adapter = CsvAdapter()
+        >>> query = CsvQuery(file="data/sales.csv", columns=["date", "amount"])
+        >>> result = adapter.execute(query)
+    """
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize CSV adapter.
+
+        Args:
+            project_root: Root directory of the project (for resolving relative paths)
+        """
+        self.project_root = project_root or Path.cwd()
+
+    @property
+    def supported_types(self) -> set[str]:
+        """Return supported query types."""
+        return {"csv"}
+
+    def _resolve_file_path(self, file_path: str) -> Path:
+        """Resolve CSV file path relative to project root or assets/data.
+
+        Args:
+            file_path: File path from query (may be relative)
+
+        Returns:
+            Resolved Path object
+        """
+        # If absolute path, use as-is
+        if Path(file_path).is_absolute():
+            return Path(file_path)
+
+        # Try relative to project root first
+        project_path = self.project_root / file_path
+        if project_path.exists():
+            return project_path
+
+        # Try relative to assets/data
+        assets_data_path = self.project_root / "assets" / "data" / file_path
+        if assets_data_path.exists():
+            return assets_data_path
+
+        # Try just the filename in assets/data
+        filename_path = self.project_root / "assets" / "data" / Path(file_path).name
+        if filename_path.exists():
+            return filename_path
+
+        # Fall back to relative path (may not exist, but we'll handle error)
+        return self.project_root / file_path
+
+    def _execute(
+        self,
+        query: AnyQuery,
+        variables: VariableValues | None = None,
+        params: QueryParams = None,
+        source_config: SourceConfig | None = None,
+    ) -> QueryResult:
+        """Execute a CSV query.
+
+        Uses type guard for type-safe field access.
+
+        Args:
+            query: AnyQuery object (CsvQuery expected)
+            variables: Variable values for Jinja resolution
+            params: Not used for CSV queries (CSV doesn't use SQL parameterization)
+
+        Returns:
+            QueryResult with data or error
+        """
+        # Type guard ensures query.file is str
+        if not is_csv_query(query):
+            return QueryResult(
+                data=[],
+                error=f"Expected CSV query, got {query.query_type}",
+            )
+
+        file_path = query.effective_file
+        if not file_path:
+            return QueryResult(
+                data=[],
+                error="CSV query requires a file path",
+            )
+
+        # Resolve Jinja templates in file path
+        try:
+            resolved_file_path = resolve_jinja_template(file_path, variables)
+        except (ValueError, KeyError, TypeError) as e:
+            return handle_adapter_error("CSV file path template resolution", e)
+
+        # Resolve file path
+        try:
+            csv_path = self._resolve_file_path(resolved_file_path)
+        except (OSError, ValueError) as e:
+            return handle_adapter_error("CSV file path resolution", e)
+
+        # Check if file exists
+        if not csv_path.exists():
+            return QueryResult(
+                data=[],
+                error=f"CSV file not found: {csv_path}",
+            )
+
+        # Read CSV file using stdlib csv module
+        try:
+            with open(csv_path, encoding="utf-8") as f:
+                reader = csv.DictReader(f)
+                raw_rows = list(reader)
+        except (OSError, csv.Error, UnicodeDecodeError) as e:
+            return handle_adapter_error("CSV file reading", e)
+
+        # Coerce numeric strings to Python int/float so downstream type inference works.
+        rows: list[dict[str, Any]] = [
+            {k: _coerce_csv_value(v) for k, v in row.items()} for row in raw_rows
+        ]
+
+        if not rows:
+            return QueryResult(data=[])
+
+        # Get column names from first row
+        available_columns = list(rows[0].keys())
+
+        # Apply column selection if specified
+        columns = query.columns
+        if columns:
+            # Resolve Jinja in column names
+            try:
+                resolved_columns = [
+                    resolve_jinja_template(col, variables) for col in columns
+                ]
+                # Filter to only existing columns
+                existing_columns = [
+                    col for col in resolved_columns if col in available_columns
+                ]
+                if existing_columns:
+                    # Keep only selected columns
+                    rows = [{col: row[col] for col in existing_columns} for row in rows]
+                    available_columns = existing_columns
+            except (ValueError, KeyError, TypeError) as e:
+                return handle_adapter_error("CSV column name resolution", e)
+
+        # Apply filtering if specified (basic exact match, AND logic)
+        filter_dict = query.filter
+        if filter_dict:
+            try:
+                # Resolve Jinja in filter values
+                resolved_filter: dict[str, Any] = {}
+                for key, value in filter_dict.items():
+                    if isinstance(value, str):
+                        resolved_value = resolve_jinja_template(value, variables)
+                    else:
+                        resolved_value = value
+                    resolved_filter[key] = resolved_value
+
+                # Skip filters that resolved to None or empty string (conditional filters)
+                active_filters = {
+                    k: v
+                    for k, v in resolved_filter.items()
+                    if v is not None and v != "" and str(v).lower() != "none"
+                }
+
+                if active_filters:
+                    # Apply filters (exact match, AND logic)
+                    filtered_rows = []
+                    for row in rows:
+                        match = True
+                        for key, value in active_filters.items():
+                            if key not in available_columns:
+                                continue
+                            # Convert both to string for comparison (CSV reads everything as string)
+                            if str(row.get(key, "")) != str(value):
+                                match = False
+                                break
+                        if match:
+                            filtered_rows.append(row)
+                    rows = filtered_rows
+            except (ValueError, KeyError, TypeError) as e:
+                return handle_adapter_error("CSV filter application", e)
+
+        # Apply limit if specified
+        limit = query.limit
+        if limit is not None and limit > 0:
+            rows = rows[:limit]
+
+        return QueryResult(data=rows)