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

sqlspec/builder/mixins/_cte_and_set_ops.py

@@ -1,10 +1,11 @@
+# pyright: reportPrivateUsage=false
 """CTE and set operation mixins.
 
 Provides mixins for Common Table Expressions (WITH clause) and
 set operations (UNION, INTERSECT, EXCEPT).
 """
 
-from typing import Any, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
 
 from mypy_extensions import trait
 from sqlglot import exp
@@ -12,6 +13,9 @@ from typing_extensions import Self
 
 from sqlspec.exceptions import SQLBuilderError
 
+if TYPE_CHECKING:
+    from sqlspec.builder._base import QueryBuilder
+
 __all__ = ("CommonTableExpressionMixin", "SetOperationMixin")
 
 
@@ -20,8 +24,10 @@ class CommonTableExpressionMixin:
     """Mixin providing WITH clause (Common Table Expressions) support for SQL builders."""
 
     __slots__ = ()
-    # Type annotation for PyRight - this will be provided by the base class
-    _expression: Optional[exp.Expression]
+
+    # Type annotations for PyRight - these will be provided by the base class
+    def get_expression(self) -> Optional[exp.Expression]: ...
+    def set_expression(self, expression: exp.Expression) -> None: ...
 
     _with_ctes: Any  # Provided by QueryBuilder
     dialect: Any  # Provided by QueryBuilder
@@ -60,12 +66,14 @@ class CommonTableExpressionMixin:
         Returns:
             The current builder instance for method chaining.
         """
-        if self._expression is None:
+        builder = cast("QueryBuilder", self)
+        expression = builder.get_expression()
+        if expression is None:
             msg = "Cannot add WITH clause: expression not initialized."
             raise SQLBuilderError(msg)
 
-        if not isinstance(self._expression, (exp.Select, exp.Insert, exp.Update, exp.Delete)):
-            msg = f"Cannot add WITH clause to {type(self._expression).__name__} expression."
+        if not isinstance(expression, (exp.Select, exp.Insert, exp.Update, exp.Delete)):
+            msg = f"Cannot add WITH clause to {type(expression).__name__} expression."
             raise SQLBuilderError(msg)
 
         cte_expr: Optional[exp.Expression] = None
@@ -103,19 +111,17 @@ class CommonTableExpressionMixin:
         else:
             cte_alias_expr = exp.alias_(cte_expr, name)
 
-        existing_with = self._expression.args.get("with")
+        existing_with = expression.args.get("with")
         if existing_with:
             existing_with.expressions.append(cte_alias_expr)
             if recursive:
                 existing_with.set("recursive", recursive)
         else:
-            # Only SELECT, INSERT, UPDATE support WITH clauses
-            if hasattr(self._expression, "with_") and isinstance(
-                self._expression, (exp.Select, exp.Insert, exp.Update)
-            ):
-                self._expression = self._expression.with_(cte_alias_expr, as_=name, copy=False)
+            if isinstance(expression, (exp.Select, exp.Insert, exp.Update)):
+                updated_expression = expression.with_(cte_alias_expr, as_=name, copy=False)
+                builder.set_expression(updated_expression)
                 if recursive:
-                    with_clause = self._expression.find(exp.With)
+                    with_clause = updated_expression.find(exp.With)
                     if with_clause:
                         with_clause.set("recursive", recursive)
             self._with_ctes[name] = exp.CTE(this=cte_expr, alias=exp.to_table(name))
@@ -128,10 +134,12 @@ class SetOperationMixin:
     """Mixin providing set operations (UNION, INTERSECT, EXCEPT) for SELECT builders."""
 
     __slots__ = ()
-    # Type annotation for PyRight - this will be provided by the base class
-    _expression: Optional[exp.Expression]
 
-    _parameters: dict[str, Any]
+    # Type annotations for PyRight - these will be provided by the base class
+    def get_expression(self) -> Optional[exp.Expression]: ...
+    def set_expression(self, expression: exp.Expression) -> None: ...
+    def set_parameters(self, parameters: "dict[str, Any]") -> None: ...
+
     dialect: Any = None
 
     def build(self) -> Any:
@@ -162,7 +170,7 @@ class SetOperationMixin:
         union_expr = exp.union(left_expr, right_expr, distinct=not all_)
         new_builder = type(self)()
         new_builder.dialect = self.dialect
-        new_builder._expression = union_expr
+        cast("QueryBuilder", new_builder).set_expression(union_expr)
         merged_parameters = dict(left_query.parameters)
         for param_name, param_value in right_query.parameters.items():
             if param_name in merged_parameters:
@@ -181,11 +189,11 @@ class SetOperationMixin:
 
                 right_expr = right_expr.transform(rename_parameter)
                 union_expr = exp.union(left_expr, right_expr, distinct=not all_)
-                new_builder._expression = union_expr
+                cast("QueryBuilder", new_builder).set_expression(union_expr)
                 merged_parameters[new_param_name] = param_value
             else:
                 merged_parameters[param_name] = param_value
-        new_builder._parameters = merged_parameters
+        new_builder.set_parameters(merged_parameters)
         return new_builder
 
     def intersect(self, other: Any) -> Self:
@@ -210,10 +218,10 @@ class SetOperationMixin:
         intersect_expr = exp.intersect(left_expr, right_expr, distinct=True)
         new_builder = type(self)()
         new_builder.dialect = self.dialect
-        new_builder._expression = intersect_expr
+        cast("QueryBuilder", new_builder).set_expression(intersect_expr)
         merged_parameters = dict(left_query.parameters)
         merged_parameters.update(right_query.parameters)
-        new_builder._parameters = merged_parameters
+        new_builder.set_parameters(merged_parameters)
         return new_builder
 
     def except_(self, other: Any) -> Self:
@@ -238,8 +246,8 @@ class SetOperationMixin:
         except_expr = exp.except_(left_expr, right_expr)
         new_builder = type(self)()
         new_builder.dialect = self.dialect
-        new_builder._expression = except_expr
+        cast("QueryBuilder", new_builder).set_expression(except_expr)
         merged_parameters = dict(left_query.parameters)
         merged_parameters.update(right_query.parameters)
-        new_builder._parameters = merged_parameters
+        new_builder.set_parameters(merged_parameters)
         return new_builder

sqlspec/builder/mixins/_delete_operations.py

@@ -1,3 +1,4 @@
+# pyright: reportPrivateUsage=false
 """DELETE operation mixins.
 
 Provides mixins for DELETE statement functionality including
@@ -21,8 +22,9 @@ class DeleteFromClauseMixin:
 
     __slots__ = ()
 
-    # Type annotation for PyRight - this will be provided by the base class
-    _expression: Optional[exp.Expression]
+    # Type annotations for PyRight - these will be provided by the base class
+    def get_expression(self) -> Optional[exp.Expression]: ...
+    def set_expression(self, expression: exp.Expression) -> None: ...
 
     def from_(self, table: str) -> Self:
         """Set the target table for the DELETE statement.
@@ -33,13 +35,16 @@ class DeleteFromClauseMixin:
         Returns:
             The current builder instance for method chaining.
         """
-        if self._expression is None:
-            self._expression = exp.Delete()
-        if not isinstance(self._expression, exp.Delete):
-            current_expr_type = type(self._expression).__name__
+        current_expr = self.get_expression()
+        if current_expr is None:
+            self.set_expression(exp.Delete())
+            current_expr = self.get_expression()
+
+        if not isinstance(current_expr, exp.Delete):
+            current_expr_type = type(current_expr).__name__
             msg = f"Base expression for Delete is {current_expr_type}, expected Delete."
             raise SQLBuilderError(msg)
 
         setattr(self, "_table", table)
-        self._expression.set("this", exp.to_table(table))
+        current_expr.set("this", exp.to_table(table))
         return self

sqlspec/builder/mixins/_insert_operations.py

@@ -1,3 +1,4 @@
+# pyright: reportPrivateUsage=false
 """INSERT operation mixins.
 
 Provides mixins for INSERT statement functionality including
@@ -25,8 +26,9 @@ class InsertIntoClauseMixin:
 
     __slots__ = ()
 
-    # Type annotation for PyRight - this will be provided by the base class
-    _expression: Optional[exp.Expression]
+    # Type annotations for PyRight - these will be provided by the base class
+    def get_expression(self) -> Optional[exp.Expression]: ...
+    def set_expression(self, expression: exp.Expression) -> None: ...
 
     def into(self, table: str) -> Self:
         """Set the target table for the INSERT statement.
@@ -40,14 +42,17 @@ class InsertIntoClauseMixin:
         Returns:
             The current builder instance for method chaining.
         """
-        if self._expression is None:
-            self._expression = exp.Insert()
-        if not isinstance(self._expression, exp.Insert):
+        current_expr = self.get_expression()
+        if current_expr is None:
+            self.set_expression(exp.Insert())
+            current_expr = self.get_expression()
+
+        if not isinstance(current_expr, exp.Insert):
             msg = "Cannot set target table on a non-INSERT expression."
             raise SQLBuilderError(msg)
 
         setattr(self, "_table", table)
-        self._expression.set("this", exp.to_table(table))
+        current_expr.set("this", exp.to_table(table))
         return self
 
 
@@ -57,8 +62,9 @@ class InsertValuesMixin:
 
     __slots__ = ()
 
-    # Type annotation for PyRight - this will be provided by the base class
-    _expression: Optional[exp.Expression]
+    # Type annotations for PyRight - these will be provided by the base class
+    def get_expression(self) -> Optional[exp.Expression]: ...
+    def set_expression(self, expression: exp.Expression) -> None: ...
 
     _columns: Any  # Provided by QueryBuilder
 
@@ -74,14 +80,17 @@ class InsertValuesMixin:
 
     def columns(self, *columns: Union[str, exp.Expression]) -> Self:
         """Set the columns for the INSERT statement and synchronize the _columns attribute on the builder."""
-        if self._expression is None:
-            self._expression = exp.Insert()
-        if not isinstance(self._expression, exp.Insert):
+        current_expr = self.get_expression()
+        if current_expr is None:
+            self.set_expression(exp.Insert())
+            current_expr = self.get_expression()
+
+        if not isinstance(current_expr, exp.Insert):
             msg = "Cannot set columns on a non-INSERT expression."
             raise SQLBuilderError(msg)
 
         # Get the current table from the expression
-        current_this = self._expression.args.get("this")
+        current_this = current_expr.args.get("this")
         if current_this is None:
             msg = "Table must be set using .into() before setting columns."
             raise SQLBuilderError(msg)
@@ -95,11 +104,11 @@ class InsertValuesMixin:
 
             # Create Schema object with table and columns
             schema = exp.Schema(this=table_name, expressions=column_identifiers)
-            self._expression.set("this", schema)
+            current_expr.set("this", schema)
         # No columns specified - ensure we have just a Table object
         elif isinstance(current_this, exp.Schema):
             table_name = current_this.this
-            self._expression.set("this", exp.Table(this=table_name))
+            current_expr.set("this", exp.Table(this=table_name))
 
         try:
             cols = self._columns
@@ -126,9 +135,12 @@ class InsertValuesMixin:
         Returns:
             The current builder instance for method chaining.
         """
-        if self._expression is None:
-            self._expression = exp.Insert()
-        if not isinstance(self._expression, exp.Insert):
+        current_expr = self.get_expression()
+        if current_expr is None:
+            self.set_expression(exp.Insert())
+            current_expr = self.get_expression()
+
+        if not isinstance(current_expr, exp.Insert):
             msg = "Cannot add values to a non-INSERT expression."
             raise SQLBuilderError(msg)
 
@@ -137,8 +149,8 @@ class InsertValuesMixin:
                 msg = "Cannot mix positional values with keyword values."
                 raise SQLBuilderError(msg)
             try:
-                _columns = self._columns
-                if not _columns:
+                cols = self._columns
+                if not cols:
                     self.columns(*kwargs.keys())
             except AttributeError:
                 pass
@@ -156,8 +168,8 @@ class InsertValuesMixin:
         elif len(values) == 1 and hasattr(values[0], "items"):
             mapping = values[0]
             try:
-                _columns = self._columns
-                if not _columns:
+                cols = self._columns
+                if not cols:
                     self.columns(*mapping.keys())
             except AttributeError:
                 pass
@@ -174,9 +186,9 @@ class InsertValuesMixin:
                     row_exprs.append(exp.Placeholder(this=param_name))
         else:
             try:
-                _columns = self._columns
-                if _columns and len(values) != len(_columns):
-                    msg = f"Number of values ({len(values)}) does not match the number of specified columns ({len(_columns)})."
+                cols = self._columns
+                if cols and len(values) != len(cols):
+                    msg = f"Number of values ({len(values)}) does not match the number of specified columns ({len(cols)})."
                     raise SQLBuilderError(msg)
             except AttributeError:
                 pass
@@ -186,11 +198,9 @@ class InsertValuesMixin:
                     row_exprs.append(v)
                 else:
                     try:
-                        _columns = self._columns
-                        if _columns and i < len(_columns):
-                            column_name = (
-                                str(_columns[i]).split(".")[-1] if "." in str(_columns[i]) else str(_columns[i])
-                            )
+                        cols = self._columns
+                        if cols and i < len(cols):
+                            column_name = str(cols[i]).split(".")[-1] if "." in str(cols[i]) else str(cols[i])
                             param_name = self._generate_unique_parameter_name(column_name)
                         else:
                             param_name = self._generate_unique_parameter_name(f"value_{i + 1}")
@@ -200,7 +210,7 @@ class InsertValuesMixin:
                     row_exprs.append(exp.Placeholder(this=param_name))
 
         values_expr = exp.Values(expressions=[row_exprs])
-        self._expression.set("expression", values_expr)
+        current_expr.set("expression", values_expr)
         return self
 
     def add_values(self, values: Sequence[Any]) -> Self:
@@ -221,8 +231,9 @@ class InsertFromSelectMixin:
 
     __slots__ = ()
 
-    # Type annotation for PyRight - this will be provided by the base class
-    _expression: Optional[exp.Expression]
+    # Type annotations for PyRight - these will be provided by the base class
+    def get_expression(self) -> Optional[exp.Expression]: ...
+    def set_expression(self, expression: exp.Expression) -> None: ...
 
     _table: Any  # Provided by QueryBuilder
 
@@ -250,9 +261,12 @@ class InsertFromSelectMixin:
         except AttributeError:
             msg = "The target table must be set using .into() before adding values."
             raise SQLBuilderError(msg)
-        if self._expression is None:
-            self._expression = exp.Insert()
-        if not isinstance(self._expression, exp.Insert):
+        current_expr = self.get_expression()
+        if current_expr is None:
+            self.set_expression(exp.Insert())
+            current_expr = self.get_expression()
+
+        if not isinstance(current_expr, exp.Insert):
             msg = "Cannot set INSERT source on a non-INSERT expression."
             raise SQLBuilderError(msg)
         subquery_parameters = select_builder._parameters
@@ -261,7 +275,7 @@ class InsertFromSelectMixin:
                 self.add_parameter(p_value, name=p_name)
         select_expr = select_builder._expression
         if select_expr and isinstance(select_expr, exp.Select):
-            self._expression.set("expression", select_expr.copy())
+            current_expr.set("expression", select_expr.copy())
         else:
             msg = "SelectBuilder must have a valid SELECT expression."
             raise SQLBuilderError(msg)

sqlspec/builder/mixins/_join_operations.py

@@ -1,3 +1,4 @@
+# pyright: reportPrivateUsage=false
 """JOIN operation mixins.
 
 Provides mixins for JOIN operations in SELECT statements.
@@ -81,16 +82,12 @@ class JoinClauseMixin:
         self, table: Any, alias: Optional[str], builder: "SQLBuilderProtocol"
     ) -> exp.Expression:
         """Handle table parameters that are query builders."""
-        if hasattr(table, "_expression") and getattr(table, "_expression", None) is not None:
-            table_expr_value = getattr(table, "_expression", None)
-            if table_expr_value is not None:
-                subquery_exp = exp.paren(table_expr_value)
-            else:
-                subquery_exp = exp.paren(exp.Anonymous(this=""))
+        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=getattr(builder, "dialect", None)))
+        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(
@@ -106,28 +103,20 @@ class JoinClauseMixin:
             return self._handle_sql_object_condition(on, builder)
         if isinstance(on, exp.Expression):
             return on
-        # Last resort - convert to string and parse
         return exp.condition(str(on))
 
     def _handle_sql_object_condition(self, on: Any, builder: "SQLBuilderProtocol") -> exp.Expression:
         """Handle SQL object conditions with parameter binding."""
-        expression = getattr(on, "expression", None)
-        if expression is not None and isinstance(expression, exp.Expression):
-            # Merge parameters from SQL object into builder
-            if hasattr(on, "parameters") and hasattr(builder, "add_parameter"):
-                sql_parameters = getattr(on, "parameters", {})
-                for param_name, param_value in sql_parameters.items():
+        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", expression)
-        # If expression is None, fall back to parsing the raw SQL
-        sql_text = getattr(on, "sql", "")
-        # Merge parameters even when parsing raw SQL
-        if hasattr(on, "parameters") and hasattr(builder, "add_parameter"):
-            sql_parameters = getattr(on, "parameters", {})
-            for param_name, param_value in sql_parameters.items():
+            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(sql_text)
-        return parsed_expr if parsed_expr is not None else exp.condition(str(sql_text))
+        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
@@ -194,17 +183,13 @@ class JoinClauseMixin:
         if isinstance(table, str):
             table_expr = parse_table_expression(table, alias)
         elif has_query_builder_parameters(table):
-            if hasattr(table, "_expression") and getattr(table, "_expression", None) is not None:
-                table_expr_value = getattr(table, "_expression", None)
-                if table_expr_value is not None:
-                    subquery_exp = exp.paren(table_expr_value)
-                else:
-                    subquery_exp = exp.paren(exp.Anonymous(this=""))
+            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=getattr(builder, "dialect", None)))
+                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