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

sqlspec/statement/builder/mixins/_aggregate_functions.py

@@ -1,250 +0,0 @@
-from typing import TYPE_CHECKING, Optional, Union, cast
-
-from sqlglot import exp
-from typing_extensions import Self
-
-if TYPE_CHECKING:
-    from sqlspec.protocols import SelectBuilderProtocol
-
-__all__ = ("AggregateFunctionsMixin",)
-
-
-class AggregateFunctionsMixin:
-    """Mixin providing aggregate function methods for SQL builders."""
-
-    def count_(self, column: "Union[str, exp.Expression]" = "*", alias: Optional[str] = None) -> Self:
-        """Add COUNT function to SELECT clause.
-
-        Args:
-            column: The column to count (default is "*").
-            alias: Optional alias for the count.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        if column == "*":
-            count_expr = exp.Count(this=exp.Star())
-        else:
-            col_expr = exp.column(column) if isinstance(column, str) else column
-            count_expr = exp.Count(this=col_expr)
-
-        select_expr = exp.alias_(count_expr, alias) if alias else count_expr
-        return cast("Self", builder.select(select_expr))
-
-    def sum_(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add SUM function to SELECT clause.
-
-        Args:
-            column: The column to sum.
-            alias: Optional alias for the sum.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        sum_expr = exp.Sum(this=col_expr)
-        select_expr = exp.alias_(sum_expr, alias) if alias else sum_expr
-        return cast("Self", builder.select(select_expr))
-
-    def avg_(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add AVG function to SELECT clause.
-
-        Args:
-            column: The column to average.
-            alias: Optional alias for the average.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        avg_expr = exp.Avg(this=col_expr)
-        select_expr = exp.alias_(avg_expr, alias) if alias else avg_expr
-        return cast("Self", builder.select(select_expr))
-
-    def max_(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add MAX function to SELECT clause.
-
-        Args:
-            column: The column to find the maximum of.
-            alias: Optional alias for the maximum.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        max_expr = exp.Max(this=col_expr)
-        select_expr = exp.alias_(max_expr, alias) if alias else max_expr
-        return cast("Self", builder.select(select_expr))
-
-    def min_(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add MIN function to SELECT clause.
-
-        Args:
-            column: The column to find the minimum of.
-            alias: Optional alias for the minimum.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        min_expr = exp.Min(this=col_expr)
-        select_expr = exp.alias_(min_expr, alias) if alias else min_expr
-        return cast("Self", builder.select(select_expr))
-
-    def array_agg(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add ARRAY_AGG aggregate function to SELECT clause.
-
-        Args:
-            column: The column to aggregate into an array.
-            alias: Optional alias for the result.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        array_agg_expr = exp.ArrayAgg(this=col_expr)
-        select_expr = exp.alias_(array_agg_expr, alias) if alias else array_agg_expr
-        return cast("Self", builder.select(select_expr))
-
-    def count_distinct(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add COUNT(DISTINCT column) to SELECT clause.
-
-        Args:
-            column: The column to count distinct values of.
-            alias: Optional alias for the count.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        count_expr = exp.Count(this=exp.Distinct(expressions=[col_expr]))
-        select_expr = exp.alias_(count_expr, alias) if alias else count_expr
-        return cast("Self", builder.select(select_expr))
-
-    def stddev(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add STDDEV aggregate function to SELECT clause.
-
-        Args:
-            column: The column to calculate standard deviation of.
-            alias: Optional alias for the result.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        stddev_expr = exp.Stddev(this=col_expr)
-        select_expr = exp.alias_(stddev_expr, alias) if alias else stddev_expr
-        return cast("Self", builder.select(select_expr))
-
-    def stddev_pop(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add STDDEV_POP aggregate function to SELECT clause.
-
-        Args:
-            column: The column to calculate population standard deviation of.
-            alias: Optional alias for the result.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        stddev_pop_expr = exp.StddevPop(this=col_expr)
-        select_expr = exp.alias_(stddev_pop_expr, alias) if alias else stddev_pop_expr
-        return cast("Self", builder.select(select_expr))
-
-    def stddev_samp(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add STDDEV_SAMP aggregate function to SELECT clause.
-
-        Args:
-            column: The column to calculate sample standard deviation of.
-            alias: Optional alias for the result.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        stddev_samp_expr = exp.StddevSamp(this=col_expr)
-        select_expr = exp.alias_(stddev_samp_expr, alias) if alias else stddev_samp_expr
-        return cast("Self", builder.select(select_expr))
-
-    def variance(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add VARIANCE aggregate function to SELECT clause.
-
-        Args:
-            column: The column to calculate variance of.
-            alias: Optional alias for the result.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        variance_expr = exp.Variance(this=col_expr)
-        select_expr = exp.alias_(variance_expr, alias) if alias else variance_expr
-        return cast("Self", builder.select(select_expr))
-
-    def var_pop(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add VAR_POP aggregate function to SELECT clause.
-
-        Args:
-            column: The column to calculate population variance of.
-            alias: Optional alias for the result.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        var_pop_expr = exp.VariancePop(this=col_expr)
-        select_expr = exp.alias_(var_pop_expr, alias) if alias else var_pop_expr
-        return cast("Self", builder.select(select_expr))
-
-    def string_agg(self, column: Union[str, exp.Expression], separator: str = ",", alias: Optional[str] = None) -> Self:
-        """Add STRING_AGG aggregate function to SELECT clause.
-
-        Args:
-            column: The column to aggregate into a string.
-            separator: The separator between values (default is comma).
-            alias: Optional alias for the result.
-
-        Returns:
-            The current builder instance for method chaining.
-
-        Note:
-            Different databases have different names for this function:
-            - PostgreSQL: STRING_AGG
-            - MySQL: GROUP_CONCAT
-            - SQLite: GROUP_CONCAT
-            SQLGlot will handle the translation.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        # Use GroupConcat which SQLGlot can translate to STRING_AGG for Postgres
-        string_agg_expr = exp.GroupConcat(this=col_expr, separator=exp.Literal.string(separator))
-        select_expr = exp.alias_(string_agg_expr, alias) if alias else string_agg_expr
-        return cast("Self", builder.select(select_expr))
-
-    def json_agg(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
-        """Add JSON_AGG aggregate function to SELECT clause.
-
-        Args:
-            column: The column to aggregate into a JSON array.
-            alias: Optional alias for the result.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        builder = cast("SelectBuilderProtocol", self)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        json_agg_expr = exp.JSONArrayAgg(this=col_expr)
-        select_expr = exp.alias_(json_agg_expr, alias) if alias else json_agg_expr
-        return cast("Self", builder.select(select_expr))

sqlspec/statement/builder/mixins/_case_builder.py

@@ -1,91 +0,0 @@
-# mypy: disable-error-code="valid-type,type-var"
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
-
-from sqlglot import exp
-
-if TYPE_CHECKING:
-    from sqlspec.statement.builder.base import QueryBuilder
-    from sqlspec.typing import RowT
-
-__all__ = ("CaseBuilder", "CaseBuilderMixin")
-
-
-class CaseBuilderMixin:
-    """Mixin providing CASE expression functionality for SQL builders."""
-
-    def case_(self, alias: "Optional[str]" = None) -> "CaseBuilder":
-        """Create a CASE expression for the SELECT clause.
-
-        Args:
-            alias: Optional alias for the CASE expression.
-
-        Returns:
-            CaseBuilder: A CaseBuilder instance for building the CASE expression.
-        """
-        builder = cast("QueryBuilder[RowT]", self)  # pyright: ignore
-        return CaseBuilder(builder, alias)
-
-
-@dataclass
-class CaseBuilder:
-    """Builder for CASE expressions."""
-
-    _parent: "QueryBuilder[RowT]"  # pyright: ignore
-    _alias: Optional[str]
-    _case_expr: exp.Case
-
-    def __init__(self, parent: "QueryBuilder[RowT]", alias: "Optional[str]" = None) -> None:
-        """Initialize CaseBuilder.
-
-        Args:
-            parent: The parent builder.
-            alias: Optional alias for the CASE expression.
-        """
-        self._parent = parent
-        self._alias = alias
-        self._case_expr = exp.Case()
-
-    def when(self, condition: "Union[str, exp.Expression]", value: "Any") -> "CaseBuilder":
-        """Add WHEN clause to CASE expression.
-
-        Args:
-            condition: The condition to test.
-            value: The value to return if condition is true.
-
-        Returns:
-            CaseBuilder: The current builder instance for method chaining.
-        """
-        cond_expr = exp.condition(condition) if isinstance(condition, str) else condition
-        param_name = self._parent.add_parameter(value)[1]
-        value_expr = exp.Placeholder(this=param_name)
-
-        when_clause = exp.When(this=cond_expr, then=value_expr)
-
-        if not self._case_expr.args.get("ifs"):
-            self._case_expr.set("ifs", [])
-        self._case_expr.args["ifs"].append(when_clause)
-        return self
-
-    def else_(self, value: "Any") -> "CaseBuilder":
-        """Add ELSE clause to CASE expression.
-
-        Args:
-            value: The value to return if no conditions match.
-
-        Returns:
-            CaseBuilder: The current builder instance for method chaining.
-        """
-        param_name = self._parent.add_parameter(value)[1]
-        value_expr = exp.Placeholder(this=param_name)
-        self._case_expr.set("default", value_expr)
-        return self
-
-    def end(self) -> "QueryBuilder[RowT]":
-        """Finalize the CASE expression and add it to the SELECT clause.
-
-        Returns:
-            The parent builder instance.
-        """
-        select_expr = exp.alias_(self._case_expr, self._alias) if self._alias else self._case_expr
-        return cast("QueryBuilder[RowT]", self._parent.select(select_expr))  # type: ignore[attr-defined]

sqlspec/statement/builder/mixins/_common_table_expr.py

@@ -1,90 +0,0 @@
-from typing import Any, Optional, Union
-
-from sqlglot import exp
-from typing_extensions import Self
-
-from sqlspec.exceptions import SQLBuilderError
-
-__all__ = ("CommonTableExpressionMixin",)
-
-
-class CommonTableExpressionMixin:
-    """Mixin providing WITH clause (Common Table Expressions) support for SQL builders."""
-
-    _expression: Optional[exp.Expression] = None
-
-    def with_(
-        self, name: str, query: Union[Any, str], recursive: bool = False, columns: Optional[list[str]] = None
-    ) -> Self:
-        """Add WITH clause (Common Table Expression).
-
-        Args:
-            name: The name of the CTE.
-            query: The query for the CTE (builder instance or SQL string).
-            recursive: Whether this is a recursive CTE.
-            columns: Optional column names for the CTE.
-
-        Raises:
-            SQLBuilderError: If the query type is unsupported.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        if self._expression is None:
-            msg = "Cannot add WITH clause: expression not initialized."
-            raise SQLBuilderError(msg)
-
-        if not hasattr(self._expression, "with_") and not isinstance(
-            self._expression, (exp.Select, exp.Insert, exp.Update, exp.Delete)
-        ):
-            msg = f"Cannot add WITH clause to {type(self._expression).__name__} expression."
-            raise SQLBuilderError(msg)
-
-        cte_expr: Optional[exp.Expression] = None
-        if hasattr(query, "to_statement"):
-            # Query is a builder instance
-            built_query = query.to_statement()  # pyright: ignore
-            cte_sql = built_query.to_sql()
-            cte_expr = exp.maybe_parse(cte_sql, dialect=getattr(self, "dialect", None))
-
-            # Merge parameters
-            if hasattr(self, "add_parameter"):
-                parameters = getattr(built_query, "parameters", None) or {}
-                for param_name, param_value in parameters.items():
-                    self.add_parameter(param_value, name=param_name)  # pyright: ignore
-        elif isinstance(query, str):
-            cte_expr = exp.maybe_parse(query, dialect=getattr(self, "dialect", None))
-        elif isinstance(query, exp.Expression):
-            cte_expr = query
-
-        if not cte_expr:
-            msg = f"Could not parse CTE query: {query}"
-            raise SQLBuilderError(msg)
-
-        if columns:
-            # CTE with explicit column list: name(col1, col2, ...)
-            cte_alias_expr = exp.alias_(cte_expr, name, table=[exp.to_identifier(col) for col in columns])
-        else:
-            # Simple CTE alias: name
-            cte_alias_expr = exp.alias_(cte_expr, name)
-
-        # Different handling for different expression types
-        if hasattr(self._expression, "with_"):
-            existing_with = self._expression.args.get("with")  # pyright: ignore
-            if existing_with:
-                existing_with.expressions.append(cte_alias_expr)
-                if recursive:
-                    existing_with.set("recursive", recursive)
-            else:
-                self._expression = self._expression.with_(cte_alias_expr, as_=name, copy=False)  # pyright: ignore
-                if recursive:
-                    with_clause = self._expression.find(exp.With)
-                    if with_clause:
-                        with_clause.set("recursive", recursive)
-        else:
-            # Store CTEs for later application during build
-            if not hasattr(self, "_with_ctes"):
-                setattr(self, "_with_ctes", {})
-            self._with_ctes[name] = exp.CTE(this=cte_expr, alias=exp.to_table(name))  # type: ignore[attr-defined]
-
-        return self

sqlspec/statement/builder/mixins/_from.py

@@ -1,63 +0,0 @@
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
-
-from sqlglot import exp
-from typing_extensions import Self
-
-from sqlspec.exceptions import SQLBuilderError
-from sqlspec.statement.builder._parsing_utils import parse_table_expression
-from sqlspec.utils.type_guards import has_query_builder_parameters, is_expression
-
-if TYPE_CHECKING:
-    from sqlspec.protocols import SQLBuilderProtocol
-
-__all__ = ("FromClauseMixin",)
-
-
-class FromClauseMixin:
-    """Mixin providing FROM clause for SELECT builders."""
-
-    def from_(self, table: Union[str, exp.Expression, Any], alias: Optional[str] = None) -> Self:
-        """Add FROM clause.
-
-        Args:
-            table: The table name, expression, or subquery to select from.
-            alias: Optional alias for the table.
-
-        Raises:
-            SQLBuilderError: If the current expression is not a SELECT statement or if the table type is unsupported.
-
-        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 = "FROM clause is only supported for SELECT statements."
-            raise SQLBuilderError(msg)
-        from_expr: exp.Expression
-        if isinstance(table, str):
-            from_expr = parse_table_expression(table, alias)
-        elif is_expression(table):
-            # Direct sqlglot expression - use as is
-            from_expr = exp.alias_(table, alias) if alias else table
-        elif has_query_builder_parameters(table):
-            # Query builder with build() method
-            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)))
-            from_expr = exp.alias_(subquery_exp, alias) if alias else subquery_exp
-            current_params = getattr(builder, "_parameters", None)
-            merged_params = getattr(type(builder), "ParameterConverter", None)
-            if merged_params and hasattr(subquery, "parameters"):
-                subquery_params = getattr(subquery, "parameters", {})
-                merged_params = merged_params.merge_parameters(
-                    parameters=subquery_params,
-                    args=current_params if isinstance(current_params, list) else None,
-                    kwargs=current_params if isinstance(current_params, dict) else {},
-                )
-                setattr(builder, "_parameters", merged_params)
-        else:
-            from_expr = table
-        builder._expression = builder._expression.from_(from_expr, copy=False)
-        return cast("Self", builder)

sqlspec/statement/builder/mixins/_group_by.py

@@ -1,118 +0,0 @@
-from typing import Optional, Union
-
-from sqlglot import exp
-from typing_extensions import Self
-
-__all__ = ("GroupByClauseMixin",)
-
-
-class GroupByClauseMixin:
-    """Mixin providing GROUP BY clause functionality for SQL builders."""
-
-    _expression: Optional[exp.Expression] = None
-
-    def group_by(self, *columns: Union[str, exp.Expression]) -> Self:
-        """Add GROUP BY clause.
-
-        Args:
-            *columns: Columns to group by. Can be column names, expressions,
-                     or special grouping expressions like ROLLUP, CUBE, etc.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        if self._expression is None or not isinstance(self._expression, exp.Select):
-            return self
-
-        for column in columns:
-            self._expression = self._expression.group_by(
-                exp.column(column) if isinstance(column, str) else column, copy=False
-            )
-        return self
-
-    def group_by_rollup(self, *columns: Union[str, exp.Expression]) -> Self:
-        """Add GROUP BY ROLLUP clause.
-
-        ROLLUP generates subtotals and grand totals for a hierarchical set of columns.
-
-        Args:
-            *columns: Columns to include in the rollup hierarchy.
-
-        Returns:
-            The current builder instance for method chaining.
-
-        Example:
-            ```python
-            # GROUP BY ROLLUP(product, region)
-            query = (
-                sql.select("product", "region", sql.sum("sales"))
-                .from_("sales_data")
-                .group_by_rollup("product", "region")
-            )
-            ```
-        """
-        column_exprs = [exp.column(col) if isinstance(col, str) else col for col in columns]
-        rollup_expr = exp.Rollup(expressions=column_exprs)
-        return self.group_by(rollup_expr)
-
-    def group_by_cube(self, *columns: Union[str, exp.Expression]) -> Self:
-        """Add GROUP BY CUBE clause.
-
-        CUBE generates subtotals for all possible combinations of the specified columns.
-
-        Args:
-            *columns: Columns to include in the cube.
-
-        Returns:
-            The current builder instance for method chaining.
-
-        Example:
-            ```python
-            # GROUP BY CUBE(product, region)
-            query = (
-                sql.select("product", "region", sql.sum("sales"))
-                .from_("sales_data")
-                .group_by_cube("product", "region")
-            )
-            ```
-        """
-        column_exprs = [exp.column(col) if isinstance(col, str) else col for col in columns]
-        cube_expr = exp.Cube(expressions=column_exprs)
-        return self.group_by(cube_expr)
-
-    def group_by_grouping_sets(self, *column_sets: Union[tuple[str, ...], list[str]]) -> Self:
-        """Add GROUP BY GROUPING SETS clause.
-
-        GROUPING SETS allows you to specify multiple grouping sets in a single query.
-
-        Args:
-            *column_sets: Sets of columns to group by. Each set can be a tuple or list.
-                         Empty tuple/list creates a grand total grouping.
-
-        Returns:
-            The current builder instance for method chaining.
-
-        Example:
-            ```python
-            # GROUP BY GROUPING SETS ((product), (region), ())
-            query = (
-                sql.select("product", "region", sql.sum("sales"))
-                .from_("sales_data")
-                .group_by_grouping_sets(("product",), ("region",), ())
-            )
-            ```
-        """
-        set_expressions = []
-        for column_set in column_sets:
-            if isinstance(column_set, (tuple, list)):
-                if len(column_set) == 0:
-                    set_expressions.append(exp.Tuple(expressions=[]))
-                else:
-                    columns = [exp.column(col) for col in column_set]
-                    set_expressions.append(exp.Tuple(expressions=columns))
-            else:
-                # Single column
-                set_expressions.append(exp.column(column_set))
-
-        grouping_sets_expr = exp.GroupingSets(expressions=set_expressions)
-        return self.group_by(grouping_sets_expr)

sqlspec/statement/builder/mixins/_having.py

@@ -1,35 +0,0 @@
-from typing import Optional, Union
-
-from sqlglot import exp
-from typing_extensions import Self
-
-from sqlspec.exceptions import SQLBuilderError
-
-__all__ = ("HavingClauseMixin",)
-
-
-class HavingClauseMixin:
-    """Mixin providing HAVING clause for SELECT builders."""
-
-    _expression: Optional[exp.Expression] = None
-
-    def having(self, condition: Union[str, exp.Expression]) -> Self:
-        """Add HAVING clause.
-
-        Args:
-            condition: The condition for the HAVING clause.
-
-        Raises:
-            SQLBuilderError: If the current expression is not a SELECT statement.
-
-        Returns:
-            The current builder instance for method chaining.
-        """
-        if self._expression is None:
-            self._expression = exp.Select()
-        if not isinstance(self._expression, exp.Select):
-            msg = "Cannot add HAVING to a non-SELECT expression."
-            raise SQLBuilderError(msg)
-        having_expr = exp.condition(condition) if isinstance(condition, str) else condition
-        self._expression = self._expression.having(having_expr, copy=False)
-        return self