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

sqlspec/statement/builder/mixins/_insert_from_select.py

@@ -1,47 +0,0 @@
-from typing import Any, Optional
-
-from sqlglot import exp
-from typing_extensions import Self
-
-from sqlspec.exceptions import SQLBuilderError
-
-__all__ = ("InsertFromSelectMixin",)
-
-
-class InsertFromSelectMixin:
-    """Mixin providing INSERT ... SELECT support for INSERT builders."""
-
-    _expression: Optional[exp.Expression] = None
-
-    def from_select(self, select_builder: Any) -> Self:
-        """Sets the INSERT source to a SELECT statement.
-
-        Args:
-            select_builder: A SelectBuilder instance representing the SELECT query.
-
-        Returns:
-            The current builder instance for method chaining.
-
-        Raises:
-            SQLBuilderError: If the table is not set or the select_builder is invalid.
-        """
-        if not getattr(self, "_table", None):
-            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):
-            msg = "Cannot set INSERT source on a non-INSERT expression."
-            raise SQLBuilderError(msg)
-        # Merge parameters from the SELECT builder
-        subquery_params = getattr(select_builder, "_parameters", None)
-        if subquery_params:
-            for p_name, p_value in subquery_params.items():
-                self.add_parameter(p_value, name=p_name)  # type: ignore[attr-defined]
-        select_expr = getattr(select_builder, "_expression", None)
-        if select_expr and isinstance(select_expr, exp.Select):
-            self._expression.set("expression", select_expr.copy())
-        else:
-            msg = "SelectBuilder must have a valid SELECT expression."
-            raise SQLBuilderError(msg)
-        return self

sqlspec/statement/builder/mixins/_insert_into.py

@@ -1,36 +0,0 @@
-from typing import Optional
-
-from sqlglot import exp
-from typing_extensions import Self
-
-from sqlspec.exceptions import SQLBuilderError
-
-__all__ = ("InsertIntoClauseMixin",)
-
-
-class InsertIntoClauseMixin:
-    """Mixin providing INTO clause for INSERT builders."""
-
-    _expression: Optional[exp.Expression] = None
-
-    def into(self, table: str) -> Self:
-        """Set the target table for the INSERT statement.
-
-        Args:
-            table: The name of the table to insert data into.
-
-        Raises:
-            SQLBuilderError: If the current expression is not an INSERT statement.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        if self._expression is None:
-            self._expression = exp.Insert()
-        if not isinstance(self._expression, 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))
-        return self

sqlspec/statement/builder/mixins/_insert_values.py

@@ -1,67 +0,0 @@
-from collections.abc import Sequence
-from typing import Any, Optional, Union
-
-from sqlglot import exp
-from typing_extensions import Self
-
-from sqlspec.exceptions import SQLBuilderError
-
-__all__ = ("InsertValuesMixin",)
-
-
-class InsertValuesMixin:
-    """Mixin providing VALUES and columns methods for INSERT builders."""
-
-    _expression: Optional[exp.Expression] = None
-
-    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):
-            msg = "Cannot set columns on a non-INSERT expression."
-            raise SQLBuilderError(msg)
-        column_exprs = [exp.column(col) if isinstance(col, str) else col for col in columns]
-        self._expression.set("columns", column_exprs)
-        # Synchronize the _columns attribute on the builder (if present)
-        if hasattr(self, "_columns"):
-            # If no columns, clear the list
-            if not columns:
-                self._columns.clear()  # pyright: ignore
-            else:
-                self._columns[:] = [col.name if isinstance(col, exp.Column) else str(col) for col in columns]  # pyright: ignore
-        return self
-
-    def values(self, *values: Any) -> Self:
-        """Add a row of values to the INSERT statement, validating against _columns if set."""
-        if self._expression is None:
-            self._expression = exp.Insert()
-        if not isinstance(self._expression, exp.Insert):
-            msg = "Cannot add values to a non-INSERT expression."
-            raise SQLBuilderError(msg)
-        if (
-            hasattr(self, "_columns") and getattr(self, "_columns", []) and len(values) != len(self._columns)  # pyright: ignore
-        ):
-            msg = f"Number of values ({len(values)}) does not match the number of specified columns ({len(self._columns)})."  # pyright: ignore
-            raise SQLBuilderError(msg)
-        row_exprs = []
-        for v in values:
-            if isinstance(v, exp.Expression):
-                row_exprs.append(v)
-            else:
-                _, param_name = self.add_parameter(v)  # type: ignore[attr-defined]
-                row_exprs.append(exp.var(param_name))
-        values_expr = exp.Values(expressions=[row_exprs])
-        self._expression.set("expression", values_expr)
-        return self
-
-    def add_values(self, values: Sequence[Any]) -> Self:
-        """Add a row of values to the INSERT statement (alternative signature).
-
-        Args:
-            values: Sequence of values for the row.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        return self.values(*values)

sqlspec/statement/builder/mixins/_limit_offset.py

@@ -1,53 +0,0 @@
-from typing import TYPE_CHECKING, cast
-
-from sqlglot import exp
-from typing_extensions import Self
-
-if TYPE_CHECKING:
-    from sqlspec.protocols import SQLBuilderProtocol
-
-from sqlspec.exceptions import SQLBuilderError
-
-__all__ = ("LimitOffsetClauseMixin",)
-
-
-class LimitOffsetClauseMixin:
-    """Mixin providing LIMIT and OFFSET clauses for SELECT builders."""
-
-    def limit(self, value: int) -> Self:
-        """Add LIMIT clause.
-
-        Args:
-            value: The maximum number of rows to return.
-
-        Raises:
-            SQLBuilderError: If the current expression is not a SELECT statement.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SQLBuilderProtocol", self)
-        if not isinstance(builder._expression, exp.Select):
-            msg = "LIMIT is only supported for SELECT statements."
-            raise SQLBuilderError(msg)
-        builder._expression = builder._expression.limit(exp.Literal.number(value), copy=False)
-        return cast("Self", builder)
-
-    def offset(self, value: int) -> Self:
-        """Add OFFSET clause.
-
-        Args:
-            value: The number of rows to skip before starting to return rows.
-
-        Raises:
-            SQLBuilderError: If the current expression is not a SELECT statement.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SQLBuilderProtocol", self)
-        if not isinstance(builder._expression, exp.Select):
-            msg = "OFFSET is only supported for SELECT statements."
-            raise SQLBuilderError(msg)
-        builder._expression = builder._expression.offset(exp.Literal.number(value), copy=False)
-        return cast("Self", builder)

sqlspec/statement/builder/mixins/_order_by.py

@@ -1,46 +0,0 @@
-from typing import TYPE_CHECKING, Union, cast
-
-from sqlglot import exp
-from typing_extensions import Self
-
-from sqlspec.exceptions import SQLBuilderError
-from sqlspec.statement.builder._parsing_utils import parse_order_expression
-
-if TYPE_CHECKING:
-    from sqlspec.protocols import SQLBuilderProtocol
-
-__all__ = ("OrderByClauseMixin",)
-
-
-class OrderByClauseMixin:
-    """Mixin providing ORDER BY clause for SELECT builders."""
-
-    def order_by(self, *items: Union[str, exp.Ordered], desc: bool = False) -> Self:
-        """Add ORDER BY clause.
-
-        Args:
-            *items: Columns to order by. Can be strings (column names) or sqlglot.exp.Ordered instances for specific directions (e.g., exp.column("name").desc()).
-            desc: Whether to order in descending order (applies to all items if they are strings).
-
-        Raises:
-            SQLBuilderError: If the current expression is not a SELECT statement or if the item type is unsupported.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SQLBuilderProtocol", self)
-        if not isinstance(builder._expression, exp.Select):
-            msg = "ORDER BY is only supported for SELECT statements."
-            raise SQLBuilderError(msg)
-
-        current_expr = builder._expression
-        for item in items:
-            if isinstance(item, str):
-                order_item = parse_order_expression(item)
-                if desc:
-                    order_item = order_item.desc()
-            else:
-                order_item = item
-            current_expr = current_expr.order_by(order_item, copy=False)
-        builder._expression = current_expr
-        return cast("Self", builder)

sqlspec/statement/builder/mixins/_pivot.py

@@ -1,79 +0,0 @@
-from typing import TYPE_CHECKING, Optional, Union, cast
-
-from sqlglot import exp
-
-if TYPE_CHECKING:
-    from sqlglot.dialects.dialect import DialectType
-
-    from sqlspec.statement.builder.select import Select
-
-__all__ = ("PivotClauseMixin",)
-
-
-class PivotClauseMixin:
-    """Mixin class to add PIVOT functionality to a Select."""
-
-    _expression: "Optional[exp.Expression]" = None
-    dialect: "DialectType" = None
-
-    def pivot(
-        self: "PivotClauseMixin",
-        aggregate_function: Union[str, exp.Expression],
-        aggregate_column: Union[str, exp.Expression],
-        pivot_column: Union[str, exp.Expression],
-        pivot_values: list[Union[str, int, float, exp.Expression]],
-        alias: Optional[str] = None,
-    ) -> "Select":
-        """Adds a PIVOT clause to the SELECT statement.
-
-        Example:
-            `query.pivot(aggregate_function="SUM", aggregate_column="Sales", pivot_column="Quarter", pivot_values=["Q1", "Q2", "Q3", "Q4"], alias="PivotTable")`
-
-        Args:
-            aggregate_function: The aggregate function to use (e.g., "SUM", "AVG").
-            aggregate_column: The column to be aggregated.
-            pivot_column: The column whose unique values will become new column headers.
-            pivot_values: A list of specific values from the pivot_column to be turned into columns.
-            alias: Optional alias for the pivoted table/subquery.
-
-        Returns:
-            The SelectBuilder instance for chaining.
-        """
-        current_expr = self._expression
-        if not isinstance(current_expr, exp.Select):
-            msg = "Pivot can only be applied to a Select expression managed by SelectBuilder."
-            raise TypeError(msg)
-
-        agg_func_name = aggregate_function if isinstance(aggregate_function, str) else aggregate_function.name
-        agg_col_expr = exp.column(aggregate_column) if isinstance(aggregate_column, str) else aggregate_column
-        pivot_col_expr = exp.column(pivot_column) if isinstance(pivot_column, str) else pivot_column
-
-        pivot_agg_expr = exp.func(agg_func_name, agg_col_expr)
-
-        pivot_value_exprs: list[exp.Expression] = []
-        for val in pivot_values:
-            if isinstance(val, exp.Expression):
-                pivot_value_exprs.append(val)
-            elif isinstance(val, str):
-                pivot_value_exprs.append(exp.Literal.string(val))
-            elif isinstance(val, (int, float)):
-                pivot_value_exprs.append(exp.Literal.number(val))
-            else:
-                pivot_value_exprs.append(exp.Literal.string(str(val)))
-
-        in_expr = exp.In(this=pivot_col_expr, expressions=pivot_value_exprs)
-
-        pivot_node = exp.Pivot(expressions=[pivot_agg_expr], fields=[in_expr], unpivot=False)
-
-        if alias:
-            pivot_node.set("alias", exp.TableAlias(this=exp.to_identifier(alias)))
-
-        from_clause = current_expr.args.get("from")
-        if from_clause and isinstance(from_clause, exp.From):
-            table = from_clause.this
-            if isinstance(table, exp.Table):
-                existing_pivots = table.args.get("pivots", [])
-                existing_pivots.append(pivot_node)
-                table.set("pivots", existing_pivots)
-
-        return cast("Select", self)

sqlspec/statement/builder/mixins/_returning.py

@@ -1,37 +0,0 @@
-from typing import Optional, Union
-
-from sqlglot import exp
-from typing_extensions import Self
-
-from sqlspec.exceptions import SQLBuilderError
-
-__all__ = ("ReturningClauseMixin",)
-
-
-class ReturningClauseMixin:
-    """Mixin providing RETURNING clause for INSERT, UPDATE, and DELETE builders."""
-
-    _expression: Optional[exp.Expression] = None
-
-    def returning(self, *columns: Union[str, exp.Expression]) -> Self:
-        """Add RETURNING clause to the statement.
-
-        Args:
-            *columns: Columns to return. Can be strings or sqlglot expressions.
-
-        Raises:
-            SQLBuilderError: If the current expression is not INSERT, UPDATE, or DELETE.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        if self._expression is None:
-            msg = "Cannot add RETURNING: expression is not initialized."
-            raise SQLBuilderError(msg)
-        valid_types = (exp.Insert, exp.Update, exp.Delete)
-        if not isinstance(self._expression, valid_types):
-            msg = "RETURNING is only supported for INSERT, UPDATE, and DELETE statements."
-            raise SQLBuilderError(msg)
-        returning_exprs = [exp.column(c) if isinstance(c, str) else c for c in columns]
-        self._expression.set("returning", exp.Returning(expressions=returning_exprs))
-        return self

sqlspec/statement/builder/mixins/_select_columns.py

@@ -1,61 +0,0 @@
-from typing import TYPE_CHECKING, Union, cast
-
-from sqlglot import exp
-from typing_extensions import Self
-
-from sqlspec.exceptions import SQLBuilderError
-from sqlspec.statement.builder._parsing_utils import parse_column_expression
-
-if TYPE_CHECKING:
-    from sqlspec.protocols import SQLBuilderProtocol
-    from sqlspec.statement.builder.column import Column, FunctionColumn
-
-__all__ = ("SelectColumnsMixin",)
-
-
-class SelectColumnsMixin:
-    """Mixin providing SELECT column and DISTINCT clauses for SELECT builders."""
-
-    def select(self, *columns: Union[str, exp.Expression, "Column", "FunctionColumn"]) -> Self:
-        """Add columns to SELECT clause.
-
-        Raises:
-            SQLBuilderError: If the current expression is not a SELECT statement.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SQLBuilderProtocol", self)
-        if builder._expression is None:
-            builder._expression = exp.Select()
-        if not isinstance(builder._expression, exp.Select):
-            msg = "Cannot add select columns to a non-SELECT expression."
-            raise SQLBuilderError(msg)
-        for column in columns:
-            builder._expression = builder._expression.select(parse_column_expression(column), copy=False)
-        return cast("Self", builder)
-
-    def distinct(self, *columns: Union[str, exp.Expression, "Column", "FunctionColumn"]) -> Self:
-        """Add DISTINCT clause to SELECT.
-
-        Args:
-            *columns: Optional columns to make distinct. If none provided, applies DISTINCT to all selected columns.
-
-        Raises:
-            SQLBuilderError: If the current expression is not a SELECT statement.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SQLBuilderProtocol", self)
-        if builder._expression is None:
-            builder._expression = exp.Select()
-        if not isinstance(builder._expression, exp.Select):
-            msg = "Cannot add DISTINCT to a non-SELECT expression."
-            raise SQLBuilderError(msg)
-        if not columns:
-            builder._expression.set("distinct", exp.Distinct())
-        else:
-            distinct_columns = [parse_column_expression(column) for column in columns]
-            builder._expression.set("distinct", exp.Distinct(expressions=distinct_columns))
-        return cast("Self", builder)

sqlspec/statement/builder/mixins/_set_ops.py

@@ -1,122 +0,0 @@
-from typing import Any, Optional
-
-from sqlglot import exp
-from typing_extensions import Self
-
-from sqlspec.exceptions import SQLBuilderError
-
-__all__ = ("SetOperationMixin",)
-
-
-class SetOperationMixin:
-    """Mixin providing set operations (UNION, INTERSECT, EXCEPT) for SELECT builders."""
-
-    _expression: Any = None
-    _parameters: dict[str, Any] = {}
-    dialect: Any = None
-
-    def union(self, other: Any, all_: bool = False) -> Self:
-        """Combine this query with another using UNION.
-
-        Args:
-            other: Another SelectBuilder or compatible builder to union with.
-            all_: If True, use UNION ALL instead of UNION.
-
-        Raises:
-            SQLBuilderError: If the current expression is not a SELECT statement.
-
-        Returns:
-            The new builder instance for the union query.
-        """
-        left_query = self.build()  # type: ignore[attr-defined]
-        right_query = other.build()
-        left_expr: Optional[exp.Expression] = exp.maybe_parse(left_query.sql, dialect=getattr(self, "dialect", None))
-        right_expr: Optional[exp.Expression] = exp.maybe_parse(right_query.sql, dialect=getattr(self, "dialect", None))
-        if not left_expr or not right_expr:
-            msg = "Could not parse queries for UNION operation"
-            raise SQLBuilderError(msg)
-        union_expr = exp.union(left_expr, right_expr, distinct=not all_)
-        new_builder = type(self)()
-        new_builder.dialect = getattr(self, "dialect", None)
-        new_builder._expression = union_expr
-        merged_params = dict(left_query.parameters)
-        for param_name, param_value in right_query.parameters.items():
-            if param_name in merged_params:
-                counter = 1
-                new_param_name = f"{param_name}_right_{counter}"
-                while new_param_name in merged_params:
-                    counter += 1
-                    new_param_name = f"{param_name}_right_{counter}"
-
-                # Use AST transformation instead of string manipulation
-                def rename_parameter(node: exp.Expression) -> exp.Expression:
-                    if isinstance(node, exp.Placeholder) and node.name == param_name:  # noqa: B023
-                        return exp.Placeholder(this=new_param_name)  # noqa: B023
-                    return node
-
-                right_expr = right_expr.transform(rename_parameter)
-                union_expr = exp.union(left_expr, right_expr, distinct=not all_)
-                new_builder._expression = union_expr
-                merged_params[new_param_name] = param_value
-            else:
-                merged_params[param_name] = param_value
-        new_builder._parameters = merged_params
-        return new_builder
-
-    def intersect(self, other: Any) -> Self:
-        """Add INTERSECT clause.
-
-        Args:
-            other: Another SelectBuilder or compatible builder to intersect with.
-
-        Raises:
-            SQLBuilderError: If the current expression is not a SELECT statement.
-
-        Returns:
-            The new builder instance for the intersect query.
-        """
-        left_query = self.build()  # type: ignore[attr-defined]
-        right_query = other.build()
-        left_expr: Optional[exp.Expression] = exp.maybe_parse(left_query.sql, dialect=getattr(self, "dialect", None))
-        right_expr: Optional[exp.Expression] = exp.maybe_parse(right_query.sql, dialect=getattr(self, "dialect", None))
-        if not left_expr or not right_expr:
-            msg = "Could not parse queries for INTERSECT operation"
-            raise SQLBuilderError(msg)
-        intersect_expr = exp.intersect(left_expr, right_expr, distinct=True)
-        new_builder = type(self)()
-        new_builder.dialect = getattr(self, "dialect", None)
-        new_builder._expression = intersect_expr
-        # Merge parameters
-        merged_params = dict(left_query.parameters)
-        merged_params.update(right_query.parameters)
-        new_builder._parameters = merged_params
-        return new_builder
-
-    def except_(self, other: Any) -> Self:
-        """Combine this query with another using EXCEPT.
-
-        Args:
-            other: Another SelectBuilder or compatible builder to except with.
-
-        Raises:
-            SQLBuilderError: If the current expression is not a SELECT statement.
-
-        Returns:
-            The new builder instance for the except query.
-        """
-        left_query = self.build()  # type: ignore[attr-defined]
-        right_query = other.build()
-        left_expr: Optional[exp.Expression] = exp.maybe_parse(left_query.sql, dialect=getattr(self, "dialect", None))
-        right_expr: Optional[exp.Expression] = exp.maybe_parse(right_query.sql, dialect=getattr(self, "dialect", None))
-        if not left_expr or not right_expr:
-            msg = "Could not parse queries for EXCEPT operation"
-            raise SQLBuilderError(msg)
-        except_expr = exp.except_(left_expr, right_expr)
-        new_builder = type(self)()
-        new_builder.dialect = getattr(self, "dialect", None)
-        new_builder._expression = except_expr
-        # Merge parameters
-        merged_params = dict(left_query.parameters)
-        merged_params.update(right_query.parameters)
-        new_builder._parameters = merged_params
-        return new_builder

sqlspec/statement/builder/mixins/_unpivot.py

@@ -1,77 +0,0 @@
-from typing import TYPE_CHECKING, Optional, Union, cast
-
-from sqlglot import exp
-
-if TYPE_CHECKING:
-    from sqlglot.dialects.dialect import DialectType
-
-    from sqlspec.statement.builder.select import Select
-
-__all__ = ("UnpivotClauseMixin",)
-
-
-class UnpivotClauseMixin:
-    """Mixin class to add UNPIVOT functionality to a Select."""
-
-    _expression: "Optional[exp.Expression]" = None
-    dialect: "DialectType" = None
-
-    def unpivot(
-        self: "UnpivotClauseMixin",
-        value_column_name: str,
-        name_column_name: str,
-        columns_to_unpivot: list[Union[str, exp.Expression]],
-        alias: Optional[str] = None,
-    ) -> "Select":
-        """Adds an UNPIVOT clause to the SELECT statement.
-
-        Example:
-            `query.unpivot(value_column_name="Sales", name_column_name="Quarter", columns_to_unpivot=["Q1Sales", "Q2Sales"], alias="UnpivotTable")`
-
-        Args:
-            value_column_name: The name for the new column that will hold the values from the unpivoted columns.
-            name_column_name: The name for the new column that will hold the names of the original unpivoted columns.
-            columns_to_unpivot: A list of columns to be unpivoted into rows.
-            alias: Optional alias for the unpivoted table/subquery.
-
-        Raises:
-            TypeError: If the current expression is not a Select expression.
-
-        Returns:
-            The Select instance for chaining.
-        """
-        current_expr = self._expression
-        if not isinstance(current_expr, exp.Select):
-            # SelectBuilder's __init__ ensures _expression is exp.Select.
-            msg = "Unpivot can only be applied to a Select expression managed by Select."
-            raise TypeError(msg)
-
-        value_col_ident = exp.to_identifier(value_column_name)
-        name_col_ident = exp.to_identifier(name_column_name)
-
-        unpivot_cols_exprs: list[exp.Expression] = []
-        for col_name_or_expr in columns_to_unpivot:
-            if isinstance(col_name_or_expr, exp.Expression):
-                unpivot_cols_exprs.append(col_name_or_expr)
-            elif isinstance(col_name_or_expr, str):
-                unpivot_cols_exprs.append(exp.column(col_name_or_expr))
-            else:
-                # Fallback for other types, should ideally be an error or more specific handling
-                unpivot_cols_exprs.append(exp.column(str(col_name_or_expr)))
-
-        in_expr = exp.In(this=name_col_ident, expressions=unpivot_cols_exprs)
-
-        unpivot_node = exp.Pivot(expressions=[value_col_ident], fields=[in_expr], unpivot=True)
-
-        if alias:
-            unpivot_node.set("alias", exp.TableAlias(this=exp.to_identifier(alias)))
-
-        from_clause = current_expr.args.get("from")
-        if from_clause and isinstance(from_clause, exp.From):
-            table = from_clause.this
-            if isinstance(table, exp.Table):
-                existing_pivots = table.args.get("pivots", [])
-                existing_pivots.append(unpivot_node)
-                table.set("pivots", existing_pivots)
-
-        return cast("Select", self)