sqlspec 0.16.2__cp39-cp39-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/builder/_parsing_utils.py

@@ -0,0 +1,164 @@
+"""Centralized parsing utilities for SQLSpec builders.
+
+This module provides common parsing functions to handle complex SQL expressions
+that users might pass as strings to various builder methods.
+"""
+
+import contextlib
+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], builder: Optional[Any] = None
+) -> exp.Expression:
+    """Parse a column input that might be a complex expression.
+
+    Handles cases like:
+    - Simple column names: "name" -> Column(this=name)
+    - Qualified names: "users.name" -> Column(table=users, this=name)
+    - Aliased columns: "name AS user_name" -> Alias(this=Column(name), alias=user_name)
+    - 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, SQL object, or Column object
+        builder: Optional builder instance for parameter merging
+
+    Returns:
+        exp.Expression: Parsed SQLGlot expression
+    """
+    if isinstance(column_input, exp.Expression):
+        return column_input
+
+    # 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))
+
+
+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):
+        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"))
+            table_expr = from_clause.this
+
+            if explicit_alias:
+                return exp.alias_(table_expr, explicit_alias)  # type:ignore[no-any-return]
+            return table_expr  # type:ignore[no-any-return]
+
+    return exp.to_table(table_input, alias=explicit_alias)
+
+
+def parse_order_expression(order_input: Union[str, exp.Expression]) -> exp.Expression:
+    """Parse an ORDER BY expression that might include direction.
+
+    Handles cases like:
+    - Simple column: "name" -> Column(this=name)
+    - With direction: "name DESC" -> Ordered(this=Column(name), desc=True)
+    - Qualified: "users.name ASC" -> Ordered(this=Column(table=users, this=name), desc=False)
+    - Function: "COUNT(*) DESC" -> Ordered(this=Count(this=Star), desc=True)
+
+    Args:
+        order_input: String or SQLGlot expression for ORDER BY
+
+    Returns:
+        exp.Expression: Parsed SQLGlot expression (usually Ordered or Column)
+    """
+    if isinstance(order_input, exp.Expression):
+        return order_input
+
+    with contextlib.suppress(Exception):
+        parsed = maybe_parse(str(order_input), into=exp.Ordered)
+        if parsed:
+            return parsed
+
+    return parse_column_expression(order_input)
+
+
+def parse_condition_expression(
+    condition_input: Union[str, exp.Expression, tuple[str, Any]], builder: "Any" = None
+) -> exp.Expression:
+    """Parse a condition that might be complex SQL.
+
+    Handles cases like:
+    - Simple conditions: "name = 'John'" -> EQ(Column(name), Literal('John'))
+    - Tuple format: ("name", "John") -> EQ(Column(name), Literal('John'))
+    - Complex conditions: "age > 18 AND status = 'active'" -> And(GT(...), EQ(...))
+    - Function conditions: "LENGTH(name) > 5" -> GT(Length(Column(name)), Literal(5))
+
+    Args:
+        condition_input: String, tuple, or SQLGlot expression for condition
+        builder: Optional builder instance for parameter binding
+
+    Returns:
+        exp.Expression: Parsed SQLGlot expression (usually a comparison or logical op)
+    """
+    if isinstance(condition_input, exp.Expression):
+        return condition_input
+
+    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())
+        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.convert(value))
+        if isinstance(value, (int, float)):
+            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:
+        return exp.condition(condition_input)
+    except Exception:
+        try:
+            parsed = exp.maybe_parse(condition_input)  # type: ignore[var-annotated]
+            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/builder/_update.py

@@ -0,0 +1,188 @@
+"""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.
+"""
+
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+from sqlglot import exp
+from typing_extensions import Self
+
+from sqlspec.builder._base import QueryBuilder, SafeQuery
+from sqlspec.builder.mixins import (
+    ReturningClauseMixin,
+    UpdateFromClauseMixin,
+    UpdateSetClauseMixin,
+    UpdateTableClauseMixin,
+    WhereClauseMixin,
+)
+from sqlspec.core.result import SQLResult
+from sqlspec.exceptions import SQLBuilderError
+
+if TYPE_CHECKING:
+    from sqlspec.builder._select import Select
+
+__all__ = ("Update",)
+
+
+class Update(
+    QueryBuilder,
+    WhereClauseMixin,
+    ReturningClauseMixin,
+    UpdateSetClauseMixin,
+    UpdateFromClauseMixin,
+    UpdateTableClauseMixin,
+):
+    """Builder for UPDATE statements.
+
+    This builder provides a fluent interface for constructing SQL UPDATE statements
+    with automatic parameter binding and validation.
+
+    Example:
+        ```python
+        update_query = (
+            Update()
+            .table("users")
+            .set(name="John Doe")
+            .set(email="john@example.com")
+            .where("id = 1")
+        )
+
+        update_query = (
+            Update("users").set(name="John Doe").where("id = 1")
+        )
+
+        update_query = (
+            Update()
+            .table("users")
+            .set(status="active")
+            .where_eq("id", 123)
+        )
+
+        update_query = (
+            Update()
+            .table("users", "u")
+            .set(name="Updated Name")
+            .from_("profiles", "p")
+            .where("u.id = p.user_id AND p.is_verified = true")
+        )
+        ```
+    """
+
+    __slots__ = ("_table",)
+    _expression: Optional[exp.Expression]
+
+    def __init__(self, table: Optional[str] = None, **kwargs: Any) -> None:
+        """Initialize UPDATE with optional table.
+
+        Args:
+            table: Target table name
+            **kwargs: Additional QueryBuilder arguments
+        """
+        super().__init__(**kwargs)
+        self._initialize_expression()
+
+        if table:
+            self.table(table)
+
+    @property
+    def _expected_result_type(self) -> "type[SQLResult]":
+        """Return the expected result type for this builder."""
+        return SQLResult
+
+    def _create_base_expression(self) -> exp.Update:
+        """Create a base UPDATE expression.
+
+        Returns:
+            A new sqlglot Update expression with empty clauses.
+        """
+        return exp.Update(this=None, expressions=[], joins=[])
+
+    def join(
+        self,
+        table: "Union[str, exp.Expression, Select]",
+        on: "Union[str, exp.Expression]",
+        alias: "Optional[str]" = None,
+        join_type: str = "INNER",
+    ) -> "Self":
+        """Add JOIN clause to the UPDATE statement.
+
+        Args:
+            table: The table name, expression, or subquery to join.
+            on: The JOIN condition.
+            alias: Optional alias for the joined table.
+            join_type: Type of join (INNER, LEFT, RIGHT, FULL).
+
+        Returns:
+            The current builder instance for method chaining.
+
+        Raises:
+            SQLBuilderError: If the current expression is not an UPDATE statement.
+        """
+        if self._expression is None or not isinstance(self._expression, exp.Update):
+            msg = "Cannot add JOIN clause to non-UPDATE expression."
+            raise SQLBuilderError(msg)
+
+        table_expr: exp.Expression
+        if isinstance(table, str):
+            table_expr = exp.table_(table, alias=alias)
+        elif isinstance(table, QueryBuilder):
+            subquery = table.build()
+            subquery_exp = exp.paren(exp.maybe_parse(subquery.sql, dialect=self.dialect))
+            table_expr = exp.alias_(subquery_exp, alias) if alias else subquery_exp
+
+            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
+
+        on_expr: exp.Expression = exp.condition(on) if isinstance(on, str) else on
+
+        join_type_upper = join_type.upper()
+        if join_type_upper == "INNER":
+            join_expr = exp.Join(this=table_expr, on=on_expr)
+        elif join_type_upper == "LEFT":
+            join_expr = exp.Join(this=table_expr, on=on_expr, side="LEFT")
+        elif join_type_upper == "RIGHT":
+            join_expr = exp.Join(this=table_expr, on=on_expr, side="RIGHT")
+        elif join_type_upper == "FULL":
+            join_expr = exp.Join(this=table_expr, on=on_expr, side="FULL", kind="OUTER")
+        else:
+            msg = f"Unsupported join type: {join_type}"
+            raise SQLBuilderError(msg)
+
+        if not self._expression.args.get("joins"):
+            self._expression.set("joins", [])
+        self._expression.args["joins"].append(join_expr)
+
+        return self
+
+    def build(self) -> "SafeQuery":
+        """Build the UPDATE query with validation.
+
+        Returns:
+            SafeQuery: The built query with SQL and parameters.
+
+        Raises:
+            SQLBuilderError: If no table is set or expression is not an UPDATE.
+        """
+        if self._expression is None:
+            msg = "UPDATE expression not initialized."
+            raise SQLBuilderError(msg)
+
+        if not isinstance(self._expression, exp.Update):
+            msg = "No UPDATE expression to build or expression is of the wrong type."
+            raise SQLBuilderError(msg)
+
+        if getattr(self._expression, "this", None) is None:
+            msg = "No table specified for UPDATE statement."
+            raise SQLBuilderError(msg)
+
+        if not self._expression.args.get("expressions"):
+            msg = "At least one SET clause must be specified for UPDATE statement."
+            raise SQLBuilderError(msg)
+
+        return super().build()

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",
+)