sqlspec 0.26.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

sqlspec/builder/_insert.py

@@ -4,14 +4,15 @@ Provides a fluent interface for building SQL INSERT queries with
 parameter binding and validation.
 """
 
-from typing import TYPE_CHECKING, Any, Final, Optional
+from typing import TYPE_CHECKING, Any, Final
 
 from sqlglot import exp
 from typing_extensions import Self
 
 from sqlspec.builder._base import QueryBuilder
+from sqlspec.builder._dml import InsertFromSelectMixin, InsertIntoClauseMixin, InsertValuesMixin
 from sqlspec.builder._parsing_utils import extract_sql_object_expression
-from sqlspec.builder.mixins import InsertFromSelectMixin, InsertIntoClauseMixin, InsertValuesMixin, ReturningClauseMixin
+from sqlspec.builder._select import ReturningClauseMixin
 from sqlspec.core.result import SQLResult
 from sqlspec.exceptions import SQLBuilderError
 from sqlspec.utils.type_guards import has_expression_and_sql
@@ -23,9 +24,6 @@ if TYPE_CHECKING:
 __all__ = ("Insert",)
 
 ERR_MSG_TABLE_NOT_SET: Final[str] = "The target table must be set using .into() before adding values."
-ERR_MSG_VALUES_COLUMNS_MISMATCH: Final[str] = (
-    "Number of values ({values_len}) does not match the number of specified columns ({columns_len})."
-)
 ERR_MSG_INTERNAL_EXPRESSION_TYPE: Final[str] = "Internal error: expression is not an Insert instance as expected."
 ERR_MSG_EXPRESSION_NOT_INITIALIZED: Final[str] = "Internal error: base expression not initialized."
 
@@ -38,7 +36,7 @@ class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSe
 
     __slots__ = ("_columns", "_table", "_values_added_count")
 
-    def __init__(self, table: Optional[str] = None, **kwargs: Any) -> None:
+    def __init__(self, table: str | None = None, **kwargs: Any) -> None:
         """Initialize INSERT with optional table.
 
         Args:
@@ -47,7 +45,7 @@ class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSe
         """
         super().__init__(**kwargs)
 
-        self._table: Optional[str] = None
+        self._table: str | None = None
         self._columns: list[str] = []
         self._values_added_count: int = 0
 
@@ -94,81 +92,6 @@ class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSe
         """Get the insert expression (public API)."""
         return self._get_insert_expression()
 
-    def values(self, *values: Any, **kwargs: Any) -> "Self":
-        """Adds a row of values to the INSERT statement.
-
-        This method can be called multiple times to insert multiple rows,
-        resulting in a multi-row INSERT statement like `VALUES (...), (...)`.
-
-        Supports:
-        - values(val1, val2, val3)
-        - values(col1=val1, col2=val2)
-        - values(mapping)
-
-        Args:
-            *values: The values for the row to be inserted. The number of values
-                     must match the number of columns set by `columns()`, if `columns()` was called
-                     and specified any non-empty list of columns.
-            **kwargs: Column-value pairs for named values.
-
-        Returns:
-            The current builder instance for method chaining.
-
-        Raises:
-            SQLBuilderError: If `into()` has not been called to set the table,
-                             or if `columns()` was called with a non-empty list of columns
-                             and the number of values does not match the number of specified columns.
-        """
-        if not self._table:
-            raise SQLBuilderError(ERR_MSG_TABLE_NOT_SET)
-
-        if kwargs:
-            if values:
-                msg = "Cannot mix positional values with keyword values."
-                raise SQLBuilderError(msg)
-            return self.values_from_dict(kwargs)
-
-        if len(values) == 1:
-            values_0 = values[0]
-            if isinstance(values_0, dict):
-                return self.values_from_dict(values_0)
-
-        insert_expr = self.get_insert_expression()
-
-        if self._columns and len(values) != len(self._columns):
-            msg = ERR_MSG_VALUES_COLUMNS_MISMATCH.format(values_len=len(values), columns_len=len(self._columns))
-            raise SQLBuilderError(msg)
-
-        value_placeholders: list[exp.Expression] = []
-        for i, value in enumerate(values):
-            if isinstance(value, exp.Expression):
-                value_placeholders.append(value)
-            elif has_expression_and_sql(value):
-                value_expr = extract_sql_object_expression(value, builder=self)
-                value_placeholders.append(value_expr)
-            else:
-                if self._columns and i < len(self._columns):
-                    column_str = str(self._columns[i])
-                    column_name = column_str.rsplit(".", maxsplit=1)[-1] if "." in column_str else column_str
-                    param_name = self.generate_unique_parameter_name(column_name)
-                else:
-                    param_name = self.generate_unique_parameter_name(f"value_{i + 1}")
-                _, param_name = self.add_parameter(value, name=param_name)
-                value_placeholders.append(exp.Placeholder(this=param_name))
-
-        tuple_expr = exp.Tuple(expressions=value_placeholders)
-        if self._values_added_count == 0:
-            insert_expr.set("expression", exp.Values(expressions=[tuple_expr]))
-        else:
-            current_values = insert_expr.args.get("expression")
-            if isinstance(current_values, exp.Values):
-                current_values.expressions.append(tuple_expr)
-            else:
-                insert_expr.set("expression", exp.Values(expressions=[tuple_expr]))
-
-        self._values_added_count += 1
-        return self
-
     def values_from_dict(self, data: "Mapping[str, Any]") -> "Self":
         """Adds a row of values from a dictionary.
 

sqlspec/builder/{mixins/_join_operations.py → _join.py}

@@ -4,7 +4,7 @@
 Provides mixins for JOIN operations in SELECT statements.
 """
 
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Union, cast
 
 from mypy_extensions import trait
 from sqlglot import exp
@@ -21,6 +21,120 @@ if TYPE_CHECKING:
 __all__ = ("JoinBuilder", "JoinClauseMixin")
 
 
+def _handle_sql_object_condition(on: Any, builder: "SQLBuilderProtocol") -> exp.Expression:
+    if hasattr(on, "expression") and on.expression is not None:
+        if hasattr(on, "parameters"):
+            for param_name, param_value in on.parameters.items():
+                builder.add_parameter(param_value, name=param_name)
+        return cast("exp.Expression", on.expression)
+    if hasattr(on, "parameters"):
+        for param_name, param_value in on.parameters.items():
+            builder.add_parameter(param_value, name=param_name)
+    parsed_expr = exp.maybe_parse(on.sql)
+    return parsed_expr if parsed_expr is not None else exp.condition(str(on.sql))
+
+
+def _parse_join_condition(
+    builder: "SQLBuilderProtocol", on: Union[str, exp.Expression, "SQL"] | None
+) -> exp.Expression | None:
+    if on is None:
+        return None
+    if isinstance(on, str):
+        return exp.condition(on)
+    if hasattr(on, "expression") and hasattr(on, "sql"):
+        return _handle_sql_object_condition(on, builder)
+    if isinstance(on, exp.Expression):
+        return on
+    return exp.condition(str(on))
+
+
+def _handle_query_builder_table(table: Any, alias: str | None, builder: "SQLBuilderProtocol") -> exp.Expression:
+    subquery_expression: exp.Expression
+    parameters: dict[str, Any] | None = None
+    table_parameters = getattr(table, "parameters", None)
+    if isinstance(table_parameters, dict):
+        parameters = table_parameters
+
+    if hasattr(table, "_build_final_expression") and callable(table._build_final_expression):
+        subquery_expression = cast("exp.Expression", table._build_final_expression(copy=True))
+    else:
+        subquery_result = table.build()
+        sql_text = subquery_result.sql if hasattr(subquery_result, "sql") else str(subquery_result)
+        subquery_expression = exp.maybe_parse(sql_text, dialect=builder.dialect) or exp.convert(sql_text)
+        if parameters is None and hasattr(subquery_result, "parameters"):
+            result_parameters = subquery_result.parameters
+            if isinstance(result_parameters, dict):
+                parameters = result_parameters
+
+    if parameters:
+        for param_name, param_value in parameters.items():
+            builder.add_parameter(param_value, name=param_name)
+
+    subquery_exp = exp.paren(subquery_expression)
+    return exp.alias_(subquery_exp, alias) if alias else subquery_exp
+
+
+def _parse_join_table(
+    builder: "SQLBuilderProtocol", table: str | exp.Expression | Any, alias: str | None
+) -> exp.Expression:
+    if isinstance(table, str):
+        return parse_table_expression(table, alias)
+    if has_query_builder_parameters(table):
+        return _handle_query_builder_table(table, alias, builder)
+    if isinstance(table, exp.Expression):
+        return table
+    return cast("exp.Expression", table)
+
+
+def _create_join_expression(table_expr: exp.Expression, on_expr: exp.Expression | None, join_type: str) -> exp.Join:
+    join_type_upper = join_type.upper()
+    if join_type_upper == "INNER":
+        return exp.Join(this=table_expr, on=on_expr)
+    if join_type_upper == "LEFT":
+        return exp.Join(this=table_expr, on=on_expr, side="LEFT")
+    if join_type_upper == "RIGHT":
+        return exp.Join(this=table_expr, on=on_expr, side="RIGHT")
+    if join_type_upper == "FULL":
+        return exp.Join(this=table_expr, on=on_expr, side="FULL", kind="OUTER")
+    if join_type_upper == "CROSS":
+        return exp.Join(this=table_expr, kind="CROSS")
+    msg = f"Unsupported join type: {join_type}"
+    raise SQLBuilderError(msg)
+
+
+def _apply_lateral_modifier(join_expr: exp.Join) -> None:
+    current_kind = join_expr.args.get("kind")
+    current_side = join_expr.args.get("side")
+
+    if current_kind == "CROSS":
+        join_expr.set("kind", "CROSS LATERAL")
+    elif current_kind == "OUTER" and current_side == "FULL":
+        join_expr.set("side", "FULL")
+        join_expr.set("kind", "OUTER LATERAL")
+    elif current_side:
+        join_expr.set("kind", f"{current_side} LATERAL")
+        join_expr.set("side", None)
+    else:
+        join_expr.set("kind", "LATERAL")
+
+
+def build_join_clause(
+    builder: "SQLBuilderProtocol",
+    table: str | exp.Expression | Any,
+    on: Union[str, exp.Expression, "SQL"] | None,
+    alias: str | None,
+    join_type: str,
+    *,
+    lateral: bool = False,
+) -> exp.Join:
+    table_expr = _parse_join_table(builder, table, alias)
+    on_expr = _parse_join_condition(builder, on)
+    join_expr = _create_join_expression(table_expr, on_expr, join_type)
+    if lateral:
+        _apply_lateral_modifier(join_expr)
+    return join_expr
+
+
 @trait
 class JoinClauseMixin:
     """Mixin providing JOIN clause methods for SELECT builders."""
@@ -28,180 +142,68 @@ class JoinClauseMixin:
     __slots__ = ()
 
     # Type annotation for PyRight - this will be provided by the base class
-    _expression: Optional[exp.Expression]
+    _expression: exp.Expression | None
 
     def join(
         self,
-        table: Union[str, exp.Expression, Any],
-        on: Optional[Union[str, exp.Expression, "SQL"]] = None,
-        alias: Optional[str] = None,
+        table: str | exp.Expression | Any,
+        on: Union[str, exp.Expression, "SQL"] | None = None,
+        alias: str | None = None,
         join_type: str = "INNER",
         lateral: bool = False,
     ) -> Self:
         builder = cast("SQLBuilderProtocol", self)
-        self._validate_join_context(builder)
-
-        # Handle Join expressions directly (from JoinBuilder.on() calls)
-        if isinstance(table, exp.Join):
-            if builder._expression is not None and isinstance(builder._expression, exp.Select):
-                builder._expression = builder._expression.join(table, copy=False)
-            return cast("Self", builder)
-
-        table_expr = self._parse_table_expression(table, alias, builder)
-        on_expr = self._parse_on_condition(on, builder)
-        join_expr = self._create_join_expression(table_expr, on_expr, join_type)
-
-        if lateral:
-            self._apply_lateral_modifier(join_expr)
-
-        if builder._expression is not None and isinstance(builder._expression, exp.Select):
-            builder._expression = builder._expression.join(join_expr, copy=False)
-        return cast("Self", builder)
-
-    def _validate_join_context(self, builder: "SQLBuilderProtocol") -> None:
-        """Validate that the join can be applied to the current expression."""
         if builder._expression is None:
             builder._expression = exp.Select()
         if not isinstance(builder._expression, exp.Select):
             msg = "JOIN clause is only supported for SELECT statements."
             raise SQLBuilderError(msg)
 
-    def _parse_table_expression(
-        self, table: Union[str, exp.Expression, Any], alias: Optional[str], builder: "SQLBuilderProtocol"
-    ) -> exp.Expression:
-        """Parse table parameter into a SQLGlot expression."""
-        if isinstance(table, str):
-            return parse_table_expression(table, alias)
-        if has_query_builder_parameters(table):
-            return self._handle_query_builder_table(table, alias, builder)
-        if isinstance(table, exp.Expression):
-            return table
-        return cast("exp.Expression", table)
-
-    def _handle_query_builder_table(
-        self, table: Any, alias: Optional[str], builder: "SQLBuilderProtocol"
-    ) -> exp.Expression:
-        """Handle table parameters that are query builders."""
-        if hasattr(table, "_expression") and table._expression is not None:
-            subquery_exp = exp.paren(table._expression)
-            return exp.alias_(subquery_exp, alias) if alias else subquery_exp
-        subquery = table.build()
-        sql_str = subquery.sql if hasattr(subquery, "sql") and not callable(subquery.sql) else str(subquery)
-        subquery_exp = exp.paren(exp.maybe_parse(sql_str, dialect=builder.dialect))
-        return exp.alias_(subquery_exp, alias) if alias else subquery_exp
-
-    def _parse_on_condition(
-        self, on: Optional[Union[str, exp.Expression, "SQL"]], builder: "SQLBuilderProtocol"
-    ) -> Optional[exp.Expression]:
-        """Parse ON condition into a SQLGlot expression."""
-        if on is None:
-            return None
-
-        if isinstance(on, str):
-            return exp.condition(on)
-        if hasattr(on, "expression") and hasattr(on, "sql"):
-            return self._handle_sql_object_condition(on, builder)
-        if isinstance(on, exp.Expression):
-            return on
-        return exp.condition(str(on))
-
-    def _handle_sql_object_condition(self, on: Any, builder: "SQLBuilderProtocol") -> exp.Expression:
-        """Handle SQL object conditions with parameter binding."""
-        if hasattr(on, "expression") and on.expression is not None:
-            if hasattr(on, "parameters"):
-                for param_name, param_value in on.parameters.items():
-                    builder.add_parameter(param_value, name=param_name)
-            return cast("exp.Expression", on.expression)
-        if hasattr(on, "parameters"):
-            for param_name, param_value in on.parameters.items():
-                builder.add_parameter(param_value, name=param_name)
-        parsed_expr = exp.maybe_parse(on.sql)
-        return parsed_expr if parsed_expr is not None else exp.condition(str(on.sql))
-
-    def _create_join_expression(
-        self, table_expr: exp.Expression, on_expr: Optional[exp.Expression], join_type: str
-    ) -> exp.Join:
-        """Create the appropriate JOIN expression based on join type."""
-        join_type_upper = join_type.upper()
-        if join_type_upper == "INNER":
-            return exp.Join(this=table_expr, on=on_expr)
-        if join_type_upper == "LEFT":
-            return exp.Join(this=table_expr, on=on_expr, side="LEFT")
-        if join_type_upper == "RIGHT":
-            return exp.Join(this=table_expr, on=on_expr, side="RIGHT")
-        if join_type_upper == "FULL":
-            return exp.Join(this=table_expr, on=on_expr, side="FULL", kind="OUTER")
-        if join_type_upper == "CROSS":
-            return exp.Join(this=table_expr, kind="CROSS")
-        msg = f"Unsupported join type: {join_type}"
-        raise SQLBuilderError(msg)
-
-    def _apply_lateral_modifier(self, join_expr: exp.Join) -> None:
-        """Apply LATERAL modifier to the join expression."""
-        current_kind = join_expr.args.get("kind")
-        current_side = join_expr.args.get("side")
-
-        if current_kind == "CROSS":
-            join_expr.set("kind", "CROSS LATERAL")
-        elif current_kind == "OUTER" and current_side == "FULL":
-            join_expr.set("side", "FULL")  # Keep side
-            join_expr.set("kind", "OUTER LATERAL")
-        elif current_side:
-            join_expr.set("kind", f"{current_side} LATERAL")
-            join_expr.set("side", None)  # Clear side to avoid duplication
-        else:
-            join_expr.set("kind", "LATERAL")
+        if isinstance(table, exp.Join):
+            builder._expression = builder._expression.join(table, copy=False)
+            return cast("Self", builder)
+
+        join_expr = build_join_clause(builder, table, on, alias, join_type, lateral=lateral)
+        builder._expression = builder._expression.join(join_expr, copy=False)
+        return cast("Self", builder)
 
     def inner_join(
-        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression, "SQL"], alias: Optional[str] = None
+        self, table: str | exp.Expression | Any, on: Union[str, exp.Expression, "SQL"], alias: str | None = None
     ) -> Self:
         return self.join(table, on, alias, "INNER")
 
     def left_join(
-        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression, "SQL"], alias: Optional[str] = None
+        self, table: str | exp.Expression | Any, on: Union[str, exp.Expression, "SQL"], alias: str | None = None
     ) -> Self:
         return self.join(table, on, alias, "LEFT")
 
     def right_join(
-        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression, "SQL"], alias: Optional[str] = None
+        self, table: str | exp.Expression | Any, on: Union[str, exp.Expression, "SQL"], alias: str | None = None
     ) -> Self:
         return self.join(table, on, alias, "RIGHT")
 
     def full_join(
-        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression, "SQL"], alias: Optional[str] = None
+        self, table: str | exp.Expression | Any, on: Union[str, exp.Expression, "SQL"], alias: str | None = None
     ) -> Self:
         return self.join(table, on, alias, "FULL")
 
-    def cross_join(self, table: Union[str, exp.Expression, Any], alias: Optional[str] = None) -> Self:
+    def cross_join(self, table: str | exp.Expression | Any, alias: str | None = None) -> Self:
         builder = cast("SQLBuilderProtocol", self)
         if builder._expression is None:
             builder._expression = exp.Select()
         if not isinstance(builder._expression, exp.Select):
             msg = "Cannot add cross join to a non-SELECT expression."
             raise SQLBuilderError(msg)
-        table_expr: exp.Expression
-        if isinstance(table, str):
-            table_expr = parse_table_expression(table, alias)
-        elif has_query_builder_parameters(table):
-            if hasattr(table, "_expression") and table._expression is not None:
-                subquery_exp = exp.paren(table._expression)
-                table_expr = exp.alias_(subquery_exp, alias) if alias else subquery_exp
-            else:
-                subquery = table.build()
-                sql_str = subquery.sql if hasattr(subquery, "sql") and not callable(subquery.sql) else str(subquery)
-                subquery_exp = exp.paren(exp.maybe_parse(sql_str, dialect=builder.dialect))
-                table_expr = exp.alias_(subquery_exp, alias) if alias else subquery_exp
-        else:
-            table_expr = table
+        table_expr = _parse_join_table(builder, table, alias)
         join_expr = exp.Join(this=table_expr, kind="CROSS")
         builder._expression = builder._expression.join(join_expr, copy=False)
         return cast("Self", builder)
 
     def lateral_join(
         self,
-        table: Union[str, exp.Expression, Any],
-        on: Optional[Union[str, exp.Expression, "SQL"]] = None,
-        alias: Optional[str] = None,
+        table: str | exp.Expression | Any,
+        on: Union[str, exp.Expression, "SQL"] | None = None,
+        alias: str | None = None,
     ) -> Self:
         """Create a LATERAL JOIN.
 
@@ -226,9 +228,9 @@ class JoinClauseMixin:
 
     def left_lateral_join(
         self,
-        table: Union[str, exp.Expression, Any],
-        on: Optional[Union[str, exp.Expression, "SQL"]] = None,
-        alias: Optional[str] = None,
+        table: str | exp.Expression | Any,
+        on: Union[str, exp.Expression, "SQL"] | None = None,
+        alias: str | None = None,
     ) -> Self:
         """Create a LEFT LATERAL JOIN.
 
@@ -242,7 +244,7 @@ class JoinClauseMixin:
         """
         return self.join(table, on=on, alias=alias, join_type="LEFT", lateral=True)
 
-    def cross_lateral_join(self, table: Union[str, exp.Expression, Any], alias: Optional[str] = None) -> Self:
+    def cross_lateral_join(self, table: str | exp.Expression | Any, alias: str | None = None) -> Self:
         """Create a CROSS LATERAL JOIN (no ON condition).
 
         Args:
@@ -290,11 +292,11 @@ class JoinBuilder:
         """
         self._join_type = join_type.upper()
         self._lateral = lateral
-        self._table: Optional[Union[str, exp.Expression]] = None
-        self._condition: Optional[exp.Expression] = None
-        self._alias: Optional[str] = None
+        self._table: str | exp.Expression | None = None
+        self._condition: exp.Expression | None = None
+        self._alias: str | None = None
 
-    def __call__(self, table: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
+    def __call__(self, table: str | exp.Expression, alias: str | None = None) -> Self:
         """Set the table to join.
 
         Args:
@@ -308,7 +310,7 @@ class JoinBuilder:
         self._alias = alias
         return self
 
-    def on(self, condition: Union[str, exp.Expression]) -> exp.Expression:
+    def on(self, condition: str | exp.Expression) -> exp.Expression:
         """Set the join condition and build the JOIN expression.
 
         Args:
@@ -324,7 +326,7 @@ class JoinBuilder:
         # Parse the condition
         condition_expr: exp.Expression
         if isinstance(condition, str):
-            parsed: Optional[exp.Expression] = exp.maybe_parse(condition)
+            parsed: exp.Expression | None = exp.maybe_parse(condition)
             condition_expr = parsed or exp.condition(condition)
         else:
             condition_expr = condition