dataface 0.1.2__py3-none-any.whl

dataface/core/execute/dialects/base.py

@@ -0,0 +1,302 @@
+"""Base SQL dialect interface for database-specific behavior.
+
+Stage: EXECUTE
+Purpose: Define the abstract interface for database-specific SQL generation.
+
+This module provides the base SQLDialect class that all database-specific
+dialects inherit from. Each dialect encapsulates its own quirks for:
+- Temp table syntax
+- Parameter placeholders
+- Filter macros
+- (Future) SQL transpilation
+
+Rather than spreading conditionals throughout the codebase, each dialect
+encapsulates its own behavior.
+"""
+
+from abc import ABC, abstractmethod
+
+# Allowlist of valid SQL operators for filter() method
+# This prevents SQL injection via operator parameter
+VALID_OPERATORS = frozenset(
+    {
+        "=",
+        "!=",
+        "<>",
+        ">",
+        "<",
+        ">=",
+        "<=",
+        "LIKE",
+        "NOT LIKE",
+        "ILIKE",
+        "NOT ILIKE",
+        "IN",
+        "NOT IN",
+        "IS",
+        "IS NOT",
+        "BETWEEN",
+        "NOT BETWEEN",
+        "~",
+        "~*",
+        "!~",
+        "!~*",  # PostgreSQL regex operators
+    }
+)
+
+
+class SQLDialect(ABC):
+    """Abstract base class for SQL dialect implementations.
+
+    Each database dialect inherits from this class and implements
+    database-specific behavior for SQL generation.
+
+    Attributes:
+        name: The canonical name of the dialect (e.g., 'postgres', 'mysql')
+
+    Example:
+        >>> dialect = PostgresDialect()
+        >>> dialect.param(1)
+        '$1'
+        >>> dialect.temp_table('tmp', 'SELECT 1')
+        'CREATE TEMP TABLE tmp AS SELECT 1'
+    """
+
+    name: str
+
+    # --- Temp Tables ---
+
+    @property
+    def supports_temp_tables(self) -> bool:
+        """Check if the dialect supports temporary tables.
+
+        Returns:
+            True if temp tables are supported, False otherwise.
+            Default is True for most databases.
+        """
+        return True
+
+    def temp_table(self, name: str, sql: str) -> str:
+        """Generate CREATE TEMP TABLE statement.
+
+        Args:
+            name: Name of the temporary table to create
+            sql: SQL query to populate the table
+
+        Returns:
+            Complete CREATE TEMP TABLE statement
+
+        Raises:
+            NotImplementedError: If the dialect doesn't support temp tables
+        """
+        return f"CREATE TEMP TABLE {name} AS {sql}"
+
+    def temp_table_ref(self, name: str) -> str:
+        """Generate reference to a temporary table.
+
+        Override for dialects with special temp table naming (e.g., SQL Server #name).
+
+        Args:
+            name: Name of the temporary table
+
+        Returns:
+            How to reference the temp table in SQL
+        """
+        return name
+
+    def drop_temp_table(self, name: str) -> str:
+        """Generate DROP TEMP TABLE statement.
+
+        Args:
+            name: Name of the temporary table to drop
+
+        Returns:
+            Complete DROP TABLE IF EXISTS statement
+        """
+        return f"DROP TABLE IF EXISTS {self.temp_table_ref(name)}"
+
+    # --- Parameters ---
+
+    @abstractmethod
+    def param(self, index: int) -> str:
+        """Generate parameter placeholder for the given index.
+
+        This is the only abstract method that must be implemented by all dialects,
+        as parameter syntax varies significantly between databases.
+
+        Args:
+            index: 1-based parameter index
+
+        Returns:
+            Parameter placeholder string (e.g., '$1', '?', '%s', '@p1')
+        """
+        pass
+
+    def params(self, count: int) -> list[str]:
+        """Generate a list of parameter placeholders.
+
+        Args:
+            count: Number of parameters needed
+
+        Returns:
+            List of parameter placeholders (e.g., ['$1', '$2', '$3'])
+        """
+        return [self.param(i) for i in range(1, count + 1)]
+
+    # --- Filters ---
+
+    def filter(self, column: str, operator: str, param_index: int) -> str:
+        """Generate filter expression with parameterized value.
+
+        This is the primary filter method that matches the Jinja filter macro:
+        {{ filter('column', '=', variable) }}
+
+        For null-safe filtering (same SQL regardless of value), use
+        filter_nullable() instead.
+
+        Security note: The operator is validated against an allowlist to prevent
+        SQL injection. Column names should come from schema definitions, not
+        user input.
+
+        Args:
+            column: Column name to filter on (must be from schema, not user input)
+            operator: SQL operator (=, !=, >, <, >=, <=, LIKE, IN, etc.)
+            param_index: Parameter index for the value
+
+        Returns:
+            SQL expression (e.g., 'column = $1', 'column > $1')
+
+        Raises:
+            ValueError: If operator is not in the allowlist
+
+        Example:
+            >>> dialect = PostgresDialect()
+            >>> dialect.filter('country', '=', 1)
+            'country = $1'
+            >>> dialect.filter('price', '>', 2)
+            'price > $2'
+        """
+        # Validate operator to prevent SQL injection
+        op_upper = operator.upper().strip()
+        if op_upper not in VALID_OPERATORS:
+            raise ValueError(
+                f"Invalid SQL operator: {operator!r}. "
+                f"Must be one of: {', '.join(sorted(VALID_OPERATORS))}"
+            )
+        return f"{column} {operator} {self.param(param_index)}"
+
+    def filter_nullable(self, column: str, operator: str, param_index: int) -> str:
+        """Generate null-safe filter expression.
+
+        Produces SQL that handles NULL parameter values gracefully, allowing
+        the same query string to be used regardless of whether filtering is
+        applied. This enables query plan caching.
+
+        When the parameter is NULL, all rows match (no filtering).
+        When the parameter has a value, normal filtering applies.
+
+        Pattern: (param IS NULL OR column operator param)
+
+        Args:
+            column: Column name to filter on (must be from schema, not user input)
+            operator: SQL operator (=, !=, >, <, >=, <=, LIKE, etc.)
+            param_index: Parameter index for the value
+
+        Returns:
+            SQL expression like '($1 IS NULL OR column = $1)'
+
+        Raises:
+            ValueError: If operator is not in the allowlist
+
+        Example:
+            >>> dialect = PostgresDialect()
+            >>> dialect.filter_nullable('country', '=', 1)
+            '($1 IS NULL OR country = $1)'
+
+            # With param='USA': filters to USA
+            # With param=NULL: ($1 IS NULL) is true, all rows match
+        """
+        # Validate operator to prevent SQL injection
+        op_upper = operator.upper().strip()
+        if op_upper not in VALID_OPERATORS:
+            raise ValueError(
+                f"Invalid SQL operator: {operator!r}. "
+                f"Must be one of: {', '.join(sorted(VALID_OPERATORS))}"
+            )
+        param = self.param(param_index)
+        return f"({param} IS NULL OR {column} {operator} {param})"
+
+    # --- Param Conversion ---
+
+    uses_named_params: bool = False
+    """Whether this dialect uses named parameters (dict) vs positional (list).
+
+    Positional dialects (default): $1, ?, %s — params passed as list.
+    Named dialects: @param1, @p1, :param1 — params passed as dict.
+    """
+
+    dbapi_placeholder: str = ""
+    """The placeholder format that DB-API drivers for this dialect expect.
+
+    Most DB-API drivers use either '?' (qmark) or '%s' (pyformat).
+    Override for dialects where param() doesn't match the DB-API driver.
+    Empty string means no rewriting is needed (param() already matches).
+    """
+
+    def rewrite_sql_for_dbapi(self, sql: str, param_count: int) -> str:
+        """Rewrite SQL to replace dialect placeholders with DB-API driver placeholders.
+
+        For dialects where param() matches what the driver expects (SQLite '?',
+        MySQL '%s'), this is a no-op. For dialects where they differ (Postgres '$1'
+        → '%s', SQL Server '@p1' → '%s'), this replaces each placeholder.
+        """
+        placeholder = self.dbapi_placeholder
+        if not placeholder:
+            return sql
+        # Replace each dialect placeholder with the DB-API placeholder,
+        # going in reverse order to avoid $1 matching inside $10
+        for i in range(param_count, 0, -1):
+            sql = sql.replace(self.param(i), placeholder)
+        return sql
+
+    def build_params(self, params: list) -> list | dict:
+        """Convert positional param list to the format this dialect expects.
+
+        Positional dialects return the list as-is.
+        Named dialects convert to a dict keyed by param name (without prefix).
+        When dbapi_placeholder is set, SQL has been rewritten to positional
+        format, so params stay as a list regardless of uses_named_params.
+        """
+        if self.dbapi_placeholder or not self.uses_named_params:
+            return params
+        return self._params_to_dict(params)
+
+    def _params_to_dict(self, params: list) -> dict:
+        """Convert param list to named dict. Override for custom key format."""
+        # Default: strip the prefix/sigil from param(i) to get the key
+        # e.g. @param1 -> param1, @p1 -> p1, :param1 -> param1
+        return {self.param(i + 1).lstrip("@:"): v for i, v in enumerate(params)}
+
+    # --- Quoting ---
+
+    def quote_identifier(self, identifier: str) -> str:
+        """Quote an identifier (table name, column name, etc.).
+
+        Default uses double quotes which works for PostgreSQL, BigQuery, etc.
+        Override for databases with different quoting conventions.
+
+        Args:
+            identifier: The identifier to quote
+
+        Returns:
+            Quoted identifier string
+        """
+        # Escape any existing double quotes
+        escaped = identifier.replace('"', '""')
+        return f'"{escaped}"'
+
+    # --- Representation ---
+
+    def __repr__(self) -> str:
+        """Return string representation of the dialect."""
+        return f"{self.__class__.__name__}(name={self.name!r})"

dataface/core/execute/dialects/bigquery.py

@@ -0,0 +1,38 @@
+"""BigQuery dialect implementation.
+
+BigQuery uses:
+- @param1, @param2 for named parameter placeholders
+- CREATE TEMP TABLE x AS for temporary tables
+"""
+
+from dataface.core.execute.dialects.base import SQLDialect
+
+
+class BigQueryDialect(SQLDialect):
+    """BigQuery dialect with @paramN parameter style.
+
+    BigQuery uses named parameters with @ prefix and supports temp tables.
+
+    Example:
+        >>> dialect = BigQueryDialect()
+        >>> dialect.param(1)
+        '@param1'
+        >>> dialect.filter('category', '=', 1)
+        'category = @param1'
+    """
+
+    name = "bigquery"
+    uses_named_params = True
+
+    def param(self, index: int) -> str:
+        """Generate BigQuery parameter placeholder.
+
+        BigQuery uses @paramN named style.
+
+        Args:
+            index: 1-based parameter index
+
+        Returns:
+            Parameter placeholder in @paramN format
+        """
+        return f"@param{index}"

dataface/core/execute/dialects/databricks.py

@@ -0,0 +1,68 @@
+"""Databricks dialect implementation.
+
+Databricks uses:
+- :param1, :param2 for named parameter placeholders
+- CREATE TEMPORARY VIEW x AS for temporary views (not tables)
+"""
+
+from dataface.core.execute.dialects.base import SQLDialect
+
+
+class DatabricksDialect(SQLDialect):
+    """Databricks dialect with :paramN parameter style.
+
+    Databricks (Spark SQL) uses named parameters with : prefix.
+    It creates temporary views instead of temporary tables.
+
+    Example:
+        >>> dialect = DatabricksDialect()
+        >>> dialect.param(1)
+        ':param1'
+        >>> dialect.temp_table('tmp', 'SELECT 1')
+        'CREATE OR REPLACE TEMPORARY VIEW tmp AS SELECT 1'
+        >>> dialect.filter('category', '=', 1)
+        'category = :param1'
+    """
+
+    name = "databricks"
+    uses_named_params = True
+
+    def param(self, index: int) -> str:
+        """Generate Databricks parameter placeholder.
+
+        Databricks uses :paramN named style.
+
+        Args:
+            index: 1-based parameter index
+
+        Returns:
+            Parameter placeholder in :paramN format
+        """
+        return f":param{index}"
+
+    def temp_table(self, name: str, sql: str) -> str:
+        """Generate Databricks temporary view creation.
+
+        Databricks uses TEMPORARY VIEW instead of TEMP TABLE.
+
+        Args:
+            name: Name of the temporary view
+            sql: SQL query for the view
+
+        Returns:
+            CREATE OR REPLACE TEMPORARY VIEW statement
+        """
+        return f"CREATE OR REPLACE TEMPORARY VIEW {name} AS {sql}"
+
+    def drop_temp_table(self, name: str) -> str:
+        """Generate Databricks DROP VIEW statement.
+
+        Since Databricks uses views, we drop the view.
+
+        Args:
+            name: Name of the temporary view
+
+        Returns:
+            DROP VIEW IF EXISTS statement
+        """
+        return f"DROP VIEW IF EXISTS {name}"

dataface/core/execute/dialects/duckdb.py

@@ -0,0 +1,35 @@
+"""DuckDB dialect implementation.
+
+DuckDB uses:
+- $1, $2, ... for parameter placeholders (also supports ?)
+- CREATE TEMP TABLE x AS for temporary tables
+"""
+
+from dataface.core.execute.dialects.base import SQLDialect
+
+
+class DuckDBDialect(SQLDialect):
+    """DuckDB dialect with $1, $2 parameter style.
+
+    DuckDB is similar to PostgreSQL and uses the same parameter syntax.
+
+    Example:
+        >>> dialect = DuckDBDialect()
+        >>> dialect.param(1)
+        '$1'
+        >>> dialect.filter('category', '=', 1)
+        'category = $1'
+    """
+
+    name = "duckdb"
+
+    def param(self, index: int) -> str:
+        """Generate DuckDB parameter placeholder.
+
+        Args:
+            index: 1-based parameter index
+
+        Returns:
+            Parameter placeholder in $N format
+        """
+        return f"${index}"

dataface/core/execute/dialects/mysql.py

@@ -0,0 +1,68 @@
+"""MySQL dialect implementation.
+
+MySQL uses:
+- %s for parameter placeholders (positional)
+- CREATE TEMPORARY TABLE x AS for temporary tables
+- Backticks for identifier quoting
+"""
+
+from dataface.core.execute.dialects.base import SQLDialect
+
+
+class MySQLDialect(SQLDialect):
+    """MySQL dialect with %s parameter style.
+
+    MySQL uses format-style parameter placeholders and TEMPORARY keyword
+    for temp tables.
+
+    Example:
+        >>> dialect = MySQLDialect()
+        >>> dialect.param()
+        '%s'
+        >>> dialect.temp_table('tmp', 'SELECT 1')
+        'CREATE TEMPORARY TABLE tmp AS SELECT 1'
+        >>> dialect.filter('category', '=', 1)
+        'category = %s'
+    """
+
+    name = "mysql"
+
+    def param(self, index: int) -> str:
+        """Generate MySQL parameter placeholder.
+
+        MySQL uses %s for all parameters (positional, not indexed).
+
+        Args:
+            index: 1-based parameter index (ignored for MySQL)
+
+        Returns:
+            Parameter placeholder '%s'
+        """
+        return "%s"
+
+    def temp_table(self, name: str, sql: str) -> str:
+        """Generate MySQL CREATE TEMPORARY TABLE statement.
+
+        MySQL uses TEMPORARY instead of TEMP.
+
+        Args:
+            name: Name of the temporary table
+            sql: SQL query to populate the table
+
+        Returns:
+            CREATE TEMPORARY TABLE statement
+        """
+        return f"CREATE TEMPORARY TABLE {name} AS {sql}"
+
+    def quote_identifier(self, identifier: str) -> str:
+        """Quote an identifier using MySQL backticks.
+
+        Args:
+            identifier: The identifier to quote
+
+        Returns:
+            Backtick-quoted identifier
+        """
+        # Escape backticks by doubling them
+        escaped = identifier.replace("`", "``")
+        return f"`{escaped}`"

dataface/core/execute/dialects/postgres.py

@@ -0,0 +1,39 @@
+"""PostgreSQL dialect implementation.
+
+PostgreSQL uses:
+- $1, $2, ... for parameter placeholders
+- CREATE TEMP TABLE x AS for temporary tables
+"""
+
+from dataface.core.execute.dialects.base import SQLDialect
+
+
+class PostgresDialect(SQLDialect):
+    """PostgreSQL dialect with $1, $2 parameter style.
+
+    PostgreSQL is the default dialect and uses standard SQL syntax
+    with numbered parameter placeholders.
+
+    Example:
+        >>> dialect = PostgresDialect()
+        >>> dialect.param(1)
+        '$1'
+        >>> dialect.params(3)
+        ['$1', '$2', '$3']
+        >>> dialect.filter('country', '=', 1)
+        'country = $1'
+    """
+
+    name = "postgres"
+    dbapi_placeholder = "%s"
+
+    def param(self, index: int) -> str:
+        """Generate PostgreSQL parameter placeholder.
+
+        Args:
+            index: 1-based parameter index
+
+        Returns:
+            Parameter placeholder in $N format
+        """
+        return f"${index}"

dataface/core/execute/dialects/redshift.py

@@ -0,0 +1,12 @@
+"""Redshift dialect implementation.
+
+Redshift is PostgreSQL-based (8.0.2), so it inherits all PostgreSQL behavior.
+"""
+
+from dataface.core.execute.dialects.postgres import PostgresDialect
+
+
+class RedshiftDialect(PostgresDialect):
+    """Redshift dialect — identical to PostgreSQL."""
+
+    name = "redshift"

dataface/core/execute/dialects/snowflake.py

@@ -0,0 +1,51 @@
+"""Snowflake dialect implementation.
+
+Snowflake uses:
+- ? for positional parameters or :name for named parameters
+- CREATE TEMPORARY TABLE x AS for temporary tables
+"""
+
+from dataface.core.execute.dialects.base import SQLDialect
+
+
+class SnowflakeDialect(SQLDialect):
+    """Snowflake dialect with ? parameter style.
+
+    Snowflake uses positional ? placeholders and has TEMPORARY tables.
+
+    Example:
+        >>> dialect = SnowflakeDialect()
+        >>> dialect.param()
+        '?'
+        >>> dialect.temp_table('tmp', 'SELECT 1')
+        'CREATE TEMPORARY TABLE tmp AS SELECT 1'
+        >>> dialect.filter('category', '=', 1)
+        'category = ?'
+    """
+
+    name = "snowflake"
+
+    def param(self, index: int) -> str:
+        """Generate Snowflake parameter placeholder.
+
+        Snowflake uses ? for positional parameters.
+
+        Args:
+            index: 1-based parameter index (ignored for positional)
+
+        Returns:
+            Parameter placeholder '?'
+        """
+        return "?"
+
+    def temp_table(self, name: str, sql: str) -> str:
+        """Generate Snowflake CREATE TEMPORARY TABLE statement.
+
+        Args:
+            name: Name of the temporary table
+            sql: SQL query to populate the table
+
+        Returns:
+            CREATE TEMPORARY TABLE statement
+        """
+        return f"CREATE TEMPORARY TABLE {name} AS {sql}"