sqlspec 0.23.0__py3-none-any.whl → 0.24.1__py3-none-any.whl

sqlspec/_sql.py

@@ -137,21 +137,18 @@ class SQLFactory:
         self.dialect = dialect
 
     def __call__(self, statement: str, dialect: DialectType = None) -> "Any":
-        """Create a SelectBuilder from a SQL string, only allowing SELECT/CTE queries.
+        """Create a SelectBuilder from a SQL string, or SQL object for DML with RETURNING.
 
         Args:
             statement: The SQL statement string.
-            parameters: Optional parameters for the query.
-            *filters: Optional filters.
-            config: Optional config.
             dialect: Optional SQL dialect.
-            **kwargs: Additional parameters.
 
         Returns:
-            SelectBuilder instance.
+            SelectBuilder instance for SELECT/WITH statements,
+            SQL object for DML statements with RETURNING clause.
 
         Raises:
-            SQLBuilderError: If the SQL is not a SELECT/CTE statement.
+            SQLBuilderError: If the SQL is not a SELECT/CTE/DML+RETURNING statement.
         """
 
         try:
@@ -175,8 +172,13 @@ class SQLFactory:
             builder = Select(dialect=dialect or self.dialect)
             builder._expression = parsed_expr
             return builder
+
+        if actual_type_str in {"INSERT", "UPDATE", "DELETE"} and parsed_expr.args.get("returning") is not None:
+            return SQL(statement)
+
         msg = (
-            f"sql(...) only supports SELECT statements. Detected type: {actual_type_str}. "
+            f"sql(...) only supports SELECT statements or DML statements with RETURNING clause. "
+            f"Detected type: {actual_type_str}. "
             f"Use sql.{actual_type_str.lower()}() instead."
         )
         raise SQLBuilderError(msg)

sqlspec/builder/_base.py

@@ -19,7 +19,7 @@ from sqlspec.core.parameters import ParameterStyle, ParameterStyleConfig
 from sqlspec.core.statement import SQL, StatementConfig
 from sqlspec.exceptions import SQLBuilderError
 from sqlspec.utils.logging import get_logger
-from sqlspec.utils.type_guards import has_sql_method, has_with_method
+from sqlspec.utils.type_guards import has_expression_and_parameters, has_sql_method, has_with_method
 
 if TYPE_CHECKING:
     from sqlspec.core.result import SQLResult
@@ -208,6 +208,43 @@ class QueryBuilder(ABC):
 
         return f"{base_name}_{uuid.uuid4().hex[:8]}"
 
+    def _merge_cte_parameters(self, cte_name: str, parameters: dict[str, Any]) -> dict[str, str]:
+        """Merge CTE parameters with unique naming to prevent collisions.
+
+        Args:
+            cte_name: The name of the CTE for parameter prefixing
+            parameters: The CTE's parameter dictionary
+
+        Returns:
+            Mapping of old parameter names to new unique names
+        """
+        param_mapping = {}
+        for old_name, value in parameters.items():
+            new_name = self._generate_unique_parameter_name(f"{cte_name}_{old_name}")
+            param_mapping[old_name] = new_name
+            self.add_parameter(value, name=new_name)
+        return param_mapping
+
+    def _update_placeholders_in_expression(
+        self, expression: exp.Expression, param_mapping: dict[str, str]
+    ) -> exp.Expression:
+        """Update parameter placeholders in expression to use new names.
+
+        Args:
+            expression: The SQLGlot expression to update
+            param_mapping: Mapping of old parameter names to new names
+
+        Returns:
+            Updated expression with new placeholder names
+        """
+
+        def placeholder_replacer(node: exp.Expression) -> exp.Expression:
+            if isinstance(node, exp.Placeholder) and str(node.this) in param_mapping:
+                return exp.Placeholder(this=param_mapping[str(node.this)])
+            return node
+
+        return expression.transform(placeholder_replacer, copy=False)
+
     def _generate_builder_cache_key(self, config: "Optional[StatementConfig]" = None) -> str:
         """Generate cache key based on builder state and configuration.
 
@@ -276,9 +313,12 @@ class QueryBuilder(ABC):
                 msg = f"CTE query builder expression must be a Select, got {type(query._expression).__name__}."
                 self._raise_sql_builder_error(msg)
             cte_select_expression = query._expression
-            for p_name, p_value in query.parameters.items():
-                unique_name = self._generate_unique_parameter_name(p_name)
-                self.add_parameter(p_value, unique_name)
+            param_mapping = self._merge_cte_parameters(alias, query.parameters)
+            updated_expression = self._update_placeholders_in_expression(cte_select_expression, param_mapping)
+            if not isinstance(updated_expression, exp.Select):
+                msg = f"Updated CTE expression must be a Select, got {type(updated_expression).__name__}."
+                self._raise_sql_builder_error(msg)
+            cte_select_expression = updated_expression
 
         elif isinstance(query, str):
             try:
@@ -297,7 +337,6 @@ class QueryBuilder(ABC):
         else:
             msg = f"Invalid query type for CTE: {type(query).__name__}"
             self._raise_sql_builder_error(msg)
-            return self
 
         self._with_ctes[alias] = exp.CTE(this=cte_select_expression, alias=exp.to_table(alias))
         return self
@@ -416,7 +455,7 @@ class QueryBuilder(ABC):
 
         if isinstance(safe_query.parameters, dict):
             kwargs = safe_query.parameters
-            parameters: Optional[tuple] = None
+            parameters: Optional[tuple[Any, ...]] = None
         else:
             kwargs = None
             parameters = (
@@ -440,7 +479,7 @@ class QueryBuilder(ABC):
             config.dialect is not None
             and config.dialect != safe_query.dialect
             and self._expression is not None
-            and hasattr(self._expression, "sql")
+            and has_sql_method(self._expression)
         ):
             try:
                 sql_string = self._expression.sql(dialect=config.dialect, pretty=True)
@@ -459,26 +498,34 @@ class QueryBuilder(ABC):
         Returns:
             str: The SQL string for this query.
         """
-        try:
-            return self.build().sql
-        except Exception:
-            return super().__str__()
+        return self.build().sql
 
     @property
     def dialect_name(self) -> "Optional[str]":
         """Returns the name of the dialect, if set."""
         if isinstance(self.dialect, str):
             return self.dialect
-        if self.dialect is not None:
-            if isinstance(self.dialect, type) and issubclass(self.dialect, Dialect):
-                return self.dialect.__name__.lower()
-            if isinstance(self.dialect, Dialect):
-                return type(self.dialect).__name__.lower()
-            try:
-                return self.dialect.__name__.lower()
-            except AttributeError:
-                pass
-        return None
+        if self.dialect is None:
+            return None
+        if isinstance(self.dialect, type) and issubclass(self.dialect, Dialect):
+            return self.dialect.__name__.lower()
+        if isinstance(self.dialect, Dialect):
+            return type(self.dialect).__name__.lower()
+        return getattr(self.dialect, "__name__", str(self.dialect)).lower()
+
+    def _merge_sql_object_parameters(self, sql_obj: Any) -> None:
+        """Merge parameters from a SQL object into the builder.
+
+        Args:
+            sql_obj: Object with parameters attribute containing parameter mappings
+        """
+        if not has_expression_and_parameters(sql_obj):
+            return
+
+        sql_parameters = getattr(sql_obj, "parameters", {})
+        for param_name, param_value in sql_parameters.items():
+            unique_name = self._generate_unique_parameter_name(param_name)
+            self.add_parameter(param_value, name=unique_name)
 
     @property
     def parameters(self) -> dict[str, Any]:

sqlspec/builder/_ddl.py

@@ -12,6 +12,7 @@ from typing_extensions import Self
 
 from sqlspec.builder._base import QueryBuilder, SafeQuery
 from sqlspec.core.result import SQLResult
+from sqlspec.utils.type_guards import has_sqlglot_expression, has_with_method
 
 if TYPE_CHECKING:
     from sqlspec.builder._column import ColumnExpression
@@ -436,8 +437,8 @@ class CreateTable(DDLBuilder):
             self._raise_sql_builder_error("Check constraint must have a condition")
 
         condition_str: str
-        if hasattr(condition, "sqlglot_expression"):
-            sqlglot_expr = getattr(condition, "sqlglot_expression", None)
+        if has_sqlglot_expression(condition):
+            sqlglot_expr = condition.sqlglot_expression
             condition_str = sqlglot_expr.sql(dialect=self.dialect) if sqlglot_expr else str(condition)
         else:
             condition_str = str(condition)
@@ -970,15 +971,15 @@ class CreateTableAsSelect(DDLBuilder):
 
         if isinstance(self._select_query, SQL):
             select_expr = self._select_query.expression
-            select_parameters = getattr(self._select_query, "parameters", None)
+            select_parameters = self._select_query.parameters
         elif isinstance(self._select_query, Select):
-            select_expr = getattr(self._select_query, "_expression", None)
-            select_parameters = getattr(self._select_query, "_parameters", None)
+            select_expr = self._select_query._expression
+            select_parameters = self._select_query._parameters
 
-            with_ctes = getattr(self._select_query, "_with_ctes", {})
+            with_ctes = self._select_query._with_ctes
             if with_ctes and select_expr and isinstance(select_expr, exp.Select):
                 for alias, cte in with_ctes.items():
-                    if hasattr(select_expr, "with_"):
+                    if has_with_method(select_expr):
                         select_expr = select_expr.with_(cte.this, as_=alias, copy=False)
         elif isinstance(self._select_query, str):
             select_expr = exp.maybe_parse(self._select_query)
@@ -1097,10 +1098,10 @@ class CreateMaterializedView(DDLBuilder):
 
         if isinstance(self._select_query, SQL):
             select_expr = self._select_query.expression
-            select_parameters = getattr(self._select_query, "parameters", None)
+            select_parameters = self._select_query.parameters
         elif isinstance(self._select_query, Select):
-            select_expr = getattr(self._select_query, "_expression", None)
-            select_parameters = getattr(self._select_query, "_parameters", None)
+            select_expr = self._select_query._expression
+            select_parameters = self._select_query._parameters
         elif isinstance(self._select_query, str):
             select_expr = exp.maybe_parse(self._select_query)
             select_parameters = None
@@ -1195,10 +1196,10 @@ class CreateView(DDLBuilder):
 
         if isinstance(self._select_query, SQL):
             select_expr = self._select_query.expression
-            select_parameters = getattr(self._select_query, "parameters", None)
+            select_parameters = self._select_query.parameters
         elif isinstance(self._select_query, Select):
-            select_expr = getattr(self._select_query, "_expression", None)
-            select_parameters = getattr(self._select_query, "_parameters", None)
+            select_expr = self._select_query._expression
+            select_parameters = self._select_query._parameters
         elif isinstance(self._select_query, str):
             select_expr = exp.maybe_parse(self._select_query)
             select_parameters = None

sqlspec/builder/_insert.py

@@ -13,6 +13,7 @@ from sqlspec.builder._base import QueryBuilder
 from sqlspec.builder.mixins import InsertFromSelectMixin, InsertIntoClauseMixin, InsertValuesMixin, ReturningClauseMixin
 from sqlspec.core.result import SQLResult
 from sqlspec.exceptions import SQLBuilderError
+from sqlspec.utils.type_guards import has_expression_and_sql
 
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
@@ -124,12 +125,9 @@ class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSe
             return self.values_from_dict(kwargs)
 
         if len(values) == 1:
-            try:
-                values_0 = values[0]
-                if hasattr(values_0, "items"):
-                    return self.values_from_dict(values_0)
-            except (AttributeError, TypeError):
-                pass
+            values_0 = values[0]
+            if hasattr(values_0, "items") and hasattr(values_0, "keys"):
+                return self.values_from_dict(values_0)
 
         insert_expr = self._get_insert_expression()
 
@@ -141,24 +139,18 @@ class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSe
         for i, value in enumerate(values):
             if isinstance(value, exp.Expression):
                 value_placeholders.append(value)
-            elif hasattr(value, "expression") and hasattr(value, "sql"):
+            elif has_expression_and_sql(value):
                 # Handle SQL objects (from sql.raw with parameters)
                 expression = getattr(value, "expression", None)
                 if expression is not None and isinstance(expression, exp.Expression):
                     # Merge parameters from SQL object into builder
-                    if hasattr(value, "parameters"):
-                        sql_parameters = getattr(value, "parameters", {})
-                        for param_name, param_value in sql_parameters.items():
-                            self.add_parameter(param_value, name=param_name)
+                    self._merge_sql_object_parameters(value)
                     value_placeholders.append(expression)
                 else:
                     # If expression is None, fall back to parsing the raw SQL
                     sql_text = getattr(value, "sql", "")
                     # Merge parameters even when parsing raw SQL
-                    if hasattr(value, "parameters"):
-                        sql_parameters = getattr(value, "parameters", {})
-                        for param_name, param_value in sql_parameters.items():
-                            self.add_parameter(param_value, name=param_name)
+                    self._merge_sql_object_parameters(value)
                     # Check if sql_text is callable (like Expression.sql method)
                     if callable(sql_text):
                         sql_text = str(value)
@@ -376,7 +368,7 @@ class ConflictBuilder:
         # Create SET expressions for the UPDATE
         set_expressions = []
         for col, val in kwargs.items():
-            if hasattr(val, "expression") and hasattr(val, "sql"):
+            if has_expression_and_sql(val):
                 # Handle SQL objects (from sql.raw with parameters)
                 expression = getattr(val, "expression", None)
                 if expression is not None and isinstance(expression, exp.Expression):

sqlspec/builder/_parsing_utils.py

@@ -10,7 +10,12 @@ from typing import Any, Final, Optional, Union, cast
 from sqlglot import exp, maybe_parse, parse_one
 
 from sqlspec.core.parameters import ParameterStyle
-from sqlspec.utils.type_guards import has_expression_attr, has_parameter_builder
+from sqlspec.utils.type_guards import (
+    has_expression_and_parameters,
+    has_expression_and_sql,
+    has_expression_attr,
+    has_parameter_builder,
+)
 
 
 def parse_column_expression(
@@ -38,12 +43,12 @@ def parse_column_expression(
         return column_input
 
     # Handle SQL objects (from sql.raw with parameters)
-    if hasattr(column_input, "expression") and hasattr(column_input, "sql"):
+    if has_expression_and_sql(column_input):
         # 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"):
+            if builder and has_expression_and_parameters(column_input) 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)
@@ -51,19 +56,16 @@ def parse_column_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"):
+        if builder and has_expression_and_parameters(column_input) 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
+        attr_value = getattr(column_input, "_expression", None)
+        if isinstance(attr_value, exp.Expression):
+            return attr_value
 
     return exp.maybe_parse(column_input) or exp.column(str(column_input))
 
@@ -178,14 +180,10 @@ def parse_condition_expression(
                 )
         condition_input = converted_condition
 
-    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)
+    parsed: Optional[exp.Expression] = exp.maybe_parse(condition_input)
+    if parsed:
+        return parsed
+    return exp.condition(condition_input)
 
 
 __all__ = ("parse_column_expression", "parse_condition_expression", "parse_order_expression", "parse_table_expression")

sqlspec/builder/_update.py

@@ -176,7 +176,7 @@ class 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:
+        if self._expression.this is None:
             msg = "No table specified for UPDATE statement."
             raise SQLBuilderError(msg)
 

sqlspec/builder/mixins/_cte_and_set_ops.py

@@ -31,6 +31,18 @@ class CommonTableExpressionMixin:
         msg = "Method must be provided by QueryBuilder subclass"
         raise NotImplementedError(msg)
 
+    def _generate_unique_parameter_name(self, base_name: str) -> str:
+        """Generate unique parameter name - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
+
+    def _update_placeholders_in_expression(
+        self, expression: exp.Expression, param_mapping: dict[str, str]
+    ) -> exp.Expression:
+        """Update parameter placeholders - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
+
     def with_(
         self, name: str, query: Union[Any, str], recursive: bool = False, columns: Optional[list[str]] = None
     ) -> Self:
@@ -69,8 +81,15 @@ class CommonTableExpressionMixin:
             parameters = built_query.parameters
             if parameters:
                 if isinstance(parameters, dict):
+                    param_mapping = {}
                     for param_name, param_value in parameters.items():
-                        self.add_parameter(param_value, name=param_name)
+                        unique_name = self._generate_unique_parameter_name(f"{name}_{param_name}")
+                        param_mapping[param_name] = unique_name
+                        self.add_parameter(param_value, name=unique_name)
+
+                    # Update placeholders in the parsed expression
+                    if cte_expr and param_mapping:
+                        cte_expr = self._update_placeholders_in_expression(cte_expr, param_mapping)
                 elif isinstance(parameters, (list, tuple)):
                     for param_value in parameters:
                         self.add_parameter(param_value)