sqlspec 0.13.1__py3-none-any.whl → 0.16.2__py3-none-any.whl

sqlspec/{statement/builder → builder}/_parsing_utils.py

@@ -5,12 +5,16 @@ that users might pass as strings to various builder methods.
 """
 
 import contextlib
-from typing import Any, Optional, Union, cast
+from typing import Any, Final, Optional, Union, cast
 
 from sqlglot import exp, maybe_parse, parse_one
 
+from sqlspec.utils.type_guards import has_expression_attr, has_parameter_builder
 
-def parse_column_expression(column_input: Union[str, exp.Expression, Any]) -> exp.Expression:
+
+def parse_column_expression(
+    column_input: Union[str, exp.Expression, Any], builder: Optional[Any] = None
+) -> exp.Expression:
     """Parse a column input that might be a complex expression.
 
     Handles cases like:
@@ -20,9 +24,11 @@ def parse_column_expression(column_input: Union[str, exp.Expression, Any]) -> ex
     - Function calls: "MAX(price)" -> Max(this=Column(price))
     - Complex expressions: "CASE WHEN ... END" -> Case(...)
     - Custom Column objects from our builder
+    - SQL objects with raw SQL expressions
 
     Args:
-        column_input: String, SQLGlot expression, or Column object
+        column_input: String, SQLGlot expression, SQL object, or Column object
+        builder: Optional builder instance for parameter merging
 
     Returns:
         exp.Expression: Parsed SQLGlot expression
@@ -30,11 +36,33 @@ def parse_column_expression(column_input: Union[str, exp.Expression, Any]) -> ex
     if isinstance(column_input, exp.Expression):
         return column_input
 
-    # Handle our custom Column objects
-    if hasattr(column_input, "_expr"):
-        attr_value = getattr(column_input, "_expr", None)
-        if isinstance(attr_value, exp.Expression):
-            return attr_value
+    # Handle SQL objects (from sql.raw with parameters)
+    if hasattr(column_input, "expression") and hasattr(column_input, "sql"):
+        # This is likely a SQL object
+        expression = getattr(column_input, "expression", None)
+        if expression is not None and isinstance(expression, exp.Expression):
+            # Merge parameters from SQL object into builder if available
+            if builder and hasattr(column_input, "parameters") and hasattr(builder, "add_parameter"):
+                sql_parameters = getattr(column_input, "parameters", {})
+                for param_name, param_value in sql_parameters.items():
+                    builder.add_parameter(param_value, name=param_name)
+            return cast("exp.Expression", expression)
+        # If expression is None, fall back to parsing the raw SQL
+        sql_text = getattr(column_input, "sql", "")
+        # Merge parameters even when parsing raw SQL
+        if builder and hasattr(column_input, "parameters") and hasattr(builder, "add_parameter"):
+            sql_parameters = getattr(column_input, "parameters", {})
+            for param_name, param_value in sql_parameters.items():
+                builder.add_parameter(param_value, name=param_name)
+        return exp.maybe_parse(sql_text) or exp.column(str(sql_text))
+
+    if has_expression_attr(column_input):
+        try:
+            attr_value = column_input._expression
+            if isinstance(attr_value, exp.Expression):
+                return attr_value
+        except AttributeError:
+            pass
 
     return exp.maybe_parse(column_input) or exp.column(str(column_input))
 
@@ -42,7 +70,6 @@ def parse_column_expression(column_input: Union[str, exp.Expression, Any]) -> ex
 def parse_table_expression(table_input: str, explicit_alias: Optional[str] = None) -> exp.Expression:
     """Parses a table string that can be a name, a name with an alias, or a subquery string."""
     with contextlib.suppress(Exception):
-        # Wrapping in a SELECT statement is a robust way to parse various table-like syntaxes
         parsed = parse_one(f"SELECT * FROM {table_input}")
         if isinstance(parsed, exp.Select) and parsed.args.get("from"):
             from_clause = cast("exp.From", parsed.args.get("from"))
@@ -102,40 +129,36 @@ def parse_condition_expression(
     if isinstance(condition_input, exp.Expression):
         return condition_input
 
-    tuple_condition_parts = 2
+    tuple_condition_parts: Final[int] = 2
     if isinstance(condition_input, tuple) and len(condition_input) == tuple_condition_parts:
         column, value = condition_input
         column_expr = parse_column_expression(column)
         if value is None:
             return exp.Is(this=column_expr, expression=exp.null())
-        # Use builder's parameter system if available
-        if builder and hasattr(builder, "add_parameter"):
-            _, param_name = builder.add_parameter(value)
+        if builder and has_parameter_builder(builder):
+            from sqlspec.builder.mixins._where_clause import _extract_column_name
+
+            column_name = _extract_column_name(column)
+            param_name = builder._generate_unique_parameter_name(column_name)
+            _, param_name = builder.add_parameter(value, name=param_name)
             return exp.EQ(this=column_expr, expression=exp.Placeholder(this=param_name))
         if isinstance(value, str):
-            return exp.EQ(this=column_expr, expression=exp.Literal.string(value))
+            return exp.EQ(this=column_expr, expression=exp.convert(value))
         if isinstance(value, (int, float)):
-            return exp.EQ(this=column_expr, expression=exp.Literal.number(str(value)))
-        return exp.EQ(this=column_expr, expression=exp.Literal.string(str(value)))
+            return exp.EQ(this=column_expr, expression=exp.convert(str(value)))
+        return exp.EQ(this=column_expr, expression=exp.convert(str(value)))
 
     if not isinstance(condition_input, str):
         condition_input = str(condition_input)
 
     try:
-        # Parse as condition using SQLGlot's condition parser
         return exp.condition(condition_input)
     except Exception:
-        # If that fails, try parsing as a general expression
         try:
             parsed = exp.maybe_parse(condition_input)  # type: ignore[var-annotated]
-            if parsed:
-                return parsed  # type:ignore[no-any-return]
-        except Exception:  # noqa: S110
-            # SQLGlot condition parsing failed, will use raw condition
-            pass
-
-    # Ultimate fallback: treat as raw condition string
-    return exp.condition(condition_input)
+            return parsed or exp.condition(condition_input)
+        except Exception:
+            return exp.condition(condition_input)
 
 
 __all__ = ("parse_column_expression", "parse_condition_expression", "parse_order_expression", "parse_table_expression")

sqlspec/builder/_select.py

@@ -0,0 +1,170 @@
+"""Safe SQL query builder with validation and parameter binding.
+
+This module provides a fluent interface for building SQL queries safely,
+with automatic parameter binding and validation.
+"""
+
+import re
+from typing import Any, Callable, Final, Optional, Union
+
+from sqlglot import exp
+from typing_extensions import Self
+
+from sqlspec.builder._base import QueryBuilder, SafeQuery
+from sqlspec.builder.mixins import (
+    CommonTableExpressionMixin,
+    HavingClauseMixin,
+    JoinClauseMixin,
+    LimitOffsetClauseMixin,
+    OrderByClauseMixin,
+    PivotClauseMixin,
+    SelectClauseMixin,
+    SetOperationMixin,
+    UnpivotClauseMixin,
+    WhereClauseMixin,
+)
+from sqlspec.core.result import SQLResult
+
+__all__ = ("Select",)
+
+
+TABLE_HINT_PATTERN: Final[str] = r"\b{}\b(\s+AS\s+\w+)?"
+
+
+class Select(
+    QueryBuilder,
+    WhereClauseMixin,
+    OrderByClauseMixin,
+    LimitOffsetClauseMixin,
+    SelectClauseMixin,
+    JoinClauseMixin,
+    HavingClauseMixin,
+    SetOperationMixin,
+    CommonTableExpressionMixin,
+    PivotClauseMixin,
+    UnpivotClauseMixin,
+):
+    """Type-safe builder for SELECT queries with schema/model integration.
+
+    This builder provides a fluent, safe interface for constructing SQL SELECT statements.
+
+    Example:
+        >>> class User(BaseModel):
+        ...     id: int
+        ...     name: str
+        >>> builder = Select("id", "name").from_("users")
+        >>> result = driver.execute(builder)
+    """
+
+    __slots__ = ("_hints", "_with_parts")
+    _expression: Optional[exp.Expression]
+
+    def __init__(self, *columns: str, **kwargs: Any) -> None:
+        """Initialize SELECT with optional columns.
+
+        Args:
+            *columns: Column names to select (e.g., "id", "name", "u.email")
+            **kwargs: Additional QueryBuilder arguments (dialect, schema, etc.)
+
+        Examples:
+            Select("id", "name")  # Shorthand for Select().select("id", "name")
+            Select()              # Same as Select() - start empty
+        """
+        super().__init__(**kwargs)
+
+        # Initialize Select-specific attributes
+        self._with_parts: dict[str, Union[exp.CTE, Select]] = {}
+        self._hints: list[dict[str, object]] = []
+
+        self._initialize_expression()
+
+        if columns:
+            self.select(*columns)
+
+    @property
+    def _expected_result_type(self) -> "type[SQLResult]":
+        """Get the expected result type for SELECT operations.
+
+        Returns:
+            type: The SelectResult type.
+        """
+        return SQLResult
+
+    def _create_base_expression(self) -> exp.Select:
+        """Create base SELECT expression."""
+        if self._expression is None or not isinstance(self._expression, exp.Select):
+            self._expression = exp.Select()
+        return self._expression
+
+    def with_hint(
+        self,
+        hint: "str",
+        *,
+        location: "str" = "statement",
+        table: "Optional[str]" = None,
+        dialect: "Optional[str]" = None,
+    ) -> "Self":
+        """Attach an optimizer or dialect-specific hint to the query.
+
+        Args:
+            hint: The raw hint string (e.g., 'INDEX(users idx_users_name)').
+            location: Where to apply the hint ('statement', 'table').
+            table: Table name if the hint is for a specific table.
+            dialect: Restrict the hint to a specific dialect (optional).
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        self._hints.append({"hint": hint, "location": location, "table": table, "dialect": dialect})
+        return self
+
+    def build(self) -> "SafeQuery":
+        """Builds the SQL query string and parameters with hint injection.
+
+        Returns:
+            SafeQuery: A dataclass containing the SQL string and parameters.
+        """
+        safe_query = super().build()
+
+        if not self._hints:
+            return safe_query
+
+        modified_expr = self._expression or self._create_base_expression()
+
+        if isinstance(modified_expr, exp.Select):
+            statement_hints = [h["hint"] for h in self._hints if h.get("location") == "statement"]
+            if statement_hints:
+
+                def parse_hint_safely(hint: Any) -> exp.Expression:
+                    try:
+                        hint_str = str(hint)
+                        hint_expr: Optional[exp.Expression] = exp.maybe_parse(hint_str, dialect=self.dialect_name)
+                        return hint_expr or exp.Anonymous(this=hint_str)
+                    except Exception:
+                        return exp.Anonymous(this=str(hint))
+
+                hint_expressions: list[exp.Expression] = [parse_hint_safely(hint) for hint in statement_hints]
+
+                if hint_expressions:
+                    modified_expr.set("hint", exp.Hint(expressions=hint_expressions))
+
+        modified_sql = modified_expr.sql(dialect=self.dialect_name, pretty=True)
+
+        for hint_dict in self._hints:
+            if hint_dict.get("location") == "table" and hint_dict.get("table"):
+                table = str(hint_dict["table"])
+                hint = str(hint_dict["hint"])
+                pattern = TABLE_HINT_PATTERN.format(re.escape(table))
+
+                def make_replacement(hint_val: str, table_val: str) -> "Callable[[re.Match[str]], str]":
+                    def replacement_func(match: re.Match[str]) -> str:
+                        alias_part = match.group(1) or ""
+                        return f"/*+ {hint_val} */ {table_val}{alias_part}"
+
+                    return replacement_func
+
+                modified_sql = re.sub(
+                    pattern, make_replacement(hint, table), modified_sql, count=1, flags=re.IGNORECASE
+                )
+
+        return SafeQuery(sql=modified_sql, parameters=safe_query.parameters, dialect=safe_query.dialect)

sqlspec/{statement/builder/update.py → builder/_update.py}

@@ -4,33 +4,30 @@ This module provides a fluent interface for building SQL queries safely,
 with automatic parameter binding and validation.
 """
 
-from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Optional, Union
 
 from sqlglot import exp
 from typing_extensions import Self
 
-from sqlspec.exceptions import SQLBuilderError
-from sqlspec.statement.builder.base import QueryBuilder, SafeQuery
-from sqlspec.statement.builder.mixins import (
+from sqlspec.builder._base import QueryBuilder, SafeQuery
+from sqlspec.builder.mixins import (
     ReturningClauseMixin,
     UpdateFromClauseMixin,
     UpdateSetClauseMixin,
     UpdateTableClauseMixin,
     WhereClauseMixin,
 )
-from sqlspec.statement.result import SQLResult
-from sqlspec.typing import RowT
+from sqlspec.core.result import SQLResult
+from sqlspec.exceptions import SQLBuilderError
 
 if TYPE_CHECKING:
-    from sqlspec.statement.builder.select import Select
+    from sqlspec.builder._select import Select
 
 __all__ = ("Update",)
 
 
-@dataclass(unsafe_hash=True)
 class Update(
-    QueryBuilder[RowT],
+    QueryBuilder,
     WhereClauseMixin,
     ReturningClauseMixin,
     UpdateSetClauseMixin,
@@ -44,7 +41,6 @@ class Update(
 
     Example:
         ```python
-        # Basic UPDATE
         update_query = (
             Update()
             .table("users")
@@ -53,12 +49,10 @@ class Update(
             .where("id = 1")
         )
 
-        # Even more concise with constructor
         update_query = (
             Update("users").set(name="John Doe").where("id = 1")
         )
 
-        # UPDATE with parameterized conditions
         update_query = (
             Update()
             .table("users")
@@ -66,7 +60,6 @@ class Update(
             .where_eq("id", 123)
         )
 
-        # UPDATE with FROM clause (PostgreSQL style)
         update_query = (
             Update()
             .table("users", "u")
@@ -77,6 +70,9 @@ class Update(
         ```
     """
 
+    __slots__ = ("_table",)
+    _expression: Optional[exp.Expression]
+
     def __init__(self, table: Optional[str] = None, **kwargs: Any) -> None:
         """Initialize UPDATE with optional table.
 
@@ -85,14 +81,15 @@ class Update(
             **kwargs: Additional QueryBuilder arguments
         """
         super().__init__(**kwargs)
+        self._initialize_expression()
 
         if table:
             self.table(table)
 
     @property
-    def _expected_result_type(self) -> "type[SQLResult[RowT]]":
+    def _expected_result_type(self) -> "type[SQLResult]":
         """Return the expected result type for this builder."""
-        return SQLResult[RowT]
+        return SQLResult
 
     def _create_base_expression(self) -> exp.Update:
         """Create a base UPDATE expression.
@@ -104,7 +101,7 @@ class Update(
 
     def join(
         self,
-        table: "Union[str, exp.Expression, Select[RowT]]",
+        table: "Union[str, exp.Expression, Select]",
         on: "Union[str, exp.Expression]",
         alias: "Optional[str]" = None,
         join_type: str = "INNER",
@@ -135,10 +132,9 @@ class Update(
             subquery_exp = exp.paren(exp.maybe_parse(subquery.sql, dialect=self.dialect))
             table_expr = exp.alias_(subquery_exp, alias) if alias else subquery_exp
 
-            # Merge parameters
-            subquery_params = table._parameters
-            if subquery_params:
-                for p_name, p_value in subquery_params.items():
+            subquery_parameters = table._parameters
+            if subquery_parameters:
+                for p_name, p_value in subquery_parameters.items():
                     self.add_parameter(p_value, name=p_name)
         else:
             table_expr = table

sqlspec/builder/mixins/__init__.py

@@ -0,0 +1,55 @@
+"""SQL statement builder mixins."""
+
+from sqlspec.builder.mixins._cte_and_set_ops import CommonTableExpressionMixin, SetOperationMixin
+from sqlspec.builder.mixins._delete_operations import DeleteFromClauseMixin
+from sqlspec.builder.mixins._insert_operations import InsertFromSelectMixin, InsertIntoClauseMixin, InsertValuesMixin
+from sqlspec.builder.mixins._join_operations import JoinClauseMixin
+from sqlspec.builder.mixins._merge_operations import (
+    MergeIntoClauseMixin,
+    MergeMatchedClauseMixin,
+    MergeNotMatchedBySourceClauseMixin,
+    MergeNotMatchedClauseMixin,
+    MergeOnClauseMixin,
+    MergeUsingClauseMixin,
+)
+from sqlspec.builder.mixins._order_limit_operations import (
+    LimitOffsetClauseMixin,
+    OrderByClauseMixin,
+    ReturningClauseMixin,
+)
+from sqlspec.builder.mixins._pivot_operations import PivotClauseMixin, UnpivotClauseMixin
+from sqlspec.builder.mixins._select_operations import CaseBuilder, SelectClauseMixin
+from sqlspec.builder.mixins._update_operations import (
+    UpdateFromClauseMixin,
+    UpdateSetClauseMixin,
+    UpdateTableClauseMixin,
+)
+from sqlspec.builder.mixins._where_clause import HavingClauseMixin, WhereClauseMixin
+
+__all__ = (
+    "CaseBuilder",
+    "CommonTableExpressionMixin",
+    "DeleteFromClauseMixin",
+    "HavingClauseMixin",
+    "InsertFromSelectMixin",
+    "InsertIntoClauseMixin",
+    "InsertValuesMixin",
+    "JoinClauseMixin",
+    "LimitOffsetClauseMixin",
+    "MergeIntoClauseMixin",
+    "MergeMatchedClauseMixin",
+    "MergeNotMatchedBySourceClauseMixin",
+    "MergeNotMatchedClauseMixin",
+    "MergeOnClauseMixin",
+    "MergeUsingClauseMixin",
+    "OrderByClauseMixin",
+    "PivotClauseMixin",
+    "ReturningClauseMixin",
+    "SelectClauseMixin",
+    "SetOperationMixin",
+    "UnpivotClauseMixin",
+    "UpdateFromClauseMixin",
+    "UpdateSetClauseMixin",
+    "UpdateTableClauseMixin",
+    "WhereClauseMixin",
+)