sqlspec 0.17.0__py3-none-any.whl → 0.17.1__py3-none-any.whl

sqlspec/_sql.py

@@ -33,13 +33,22 @@ from sqlspec.builder import (
     Truncate,
     Update,
 )
+from sqlspec.builder._expression_wrappers import (
+    AggregateExpression,
+    ConversionExpression,
+    FunctionExpression,
+    MathExpression,
+    StringExpression,
+)
 from sqlspec.builder.mixins._join_operations import JoinBuilder
 from sqlspec.builder.mixins._select_operations import Case, SubqueryBuilder, WindowFunctionBuilder
 from sqlspec.exceptions import SQLBuilderError
 
 if TYPE_CHECKING:
+    from sqlspec.builder._expression_wrappers import ExpressionWrapper
     from sqlspec.core.statement import SQL
 
+
 __all__ = (
     "AlterTable",
     "Case",
@@ -746,7 +755,9 @@ class SQLFactory:
     # ===================
 
     @staticmethod
-    def count(column: Union[str, exp.Expression] = "*", distinct: bool = False) -> exp.Expression:
+    def count(
+        column: Union[str, exp.Expression, "ExpressionWrapper", "Case", "Column"] = "*", distinct: bool = False
+    ) -> AggregateExpression:
         """Create a COUNT expression.
 
         Args:
@@ -756,12 +767,14 @@ class SQLFactory:
         Returns:
             COUNT expression.
         """
-        if column == "*":
-            return exp.Count(this=exp.Star(), distinct=distinct)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Count(this=col_expr, distinct=distinct)
-
-    def count_distinct(self, column: Union[str, exp.Expression]) -> exp.Expression:
+        if isinstance(column, str) and column == "*":
+            expr = exp.Count(this=exp.Star(), distinct=distinct)
+        else:
+            col_expr = SQLFactory._extract_expression(column)
+            expr = exp.Count(this=col_expr, distinct=distinct)
+        return AggregateExpression(expr)
+
+    def count_distinct(self, column: Union[str, exp.Expression, "ExpressionWrapper", "Case"]) -> AggregateExpression:
         """Create a COUNT(DISTINCT column) expression.
 
         Args:
@@ -773,7 +786,9 @@ class SQLFactory:
         return self.count(column, distinct=True)
 
     @staticmethod
-    def sum(column: Union[str, exp.Expression], distinct: bool = False) -> exp.Expression:
+    def sum(
+        column: Union[str, exp.Expression, "ExpressionWrapper", "Case"], distinct: bool = False
+    ) -> AggregateExpression:
         """Create a SUM expression.
 
         Args:
@@ -783,11 +798,11 @@ class SQLFactory:
         Returns:
             SUM expression.
         """
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Sum(this=col_expr, distinct=distinct)
+        col_expr = SQLFactory._extract_expression(column)
+        return AggregateExpression(exp.Sum(this=col_expr, distinct=distinct))
 
     @staticmethod
-    def avg(column: Union[str, exp.Expression]) -> exp.Expression:
+    def avg(column: Union[str, exp.Expression, "ExpressionWrapper", "Case"]) -> AggregateExpression:
         """Create an AVG expression.
 
         Args:
@@ -796,11 +811,11 @@ class SQLFactory:
         Returns:
             AVG expression.
         """
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Avg(this=col_expr)
+        col_expr = SQLFactory._extract_expression(column)
+        return AggregateExpression(exp.Avg(this=col_expr))
 
     @staticmethod
-    def max(column: Union[str, exp.Expression]) -> exp.Expression:
+    def max(column: Union[str, exp.Expression, "ExpressionWrapper", "Case"]) -> AggregateExpression:
         """Create a MAX expression.
 
         Args:
@@ -809,11 +824,11 @@ class SQLFactory:
         Returns:
             MAX expression.
         """
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Max(this=col_expr)
+        col_expr = SQLFactory._extract_expression(column)
+        return AggregateExpression(exp.Max(this=col_expr))
 
     @staticmethod
-    def min(column: Union[str, exp.Expression]) -> exp.Expression:
+    def min(column: Union[str, exp.Expression, "ExpressionWrapper", "Case"]) -> AggregateExpression:
         """Create a MIN expression.
 
         Args:
@@ -822,15 +837,15 @@ class SQLFactory:
         Returns:
             MIN expression.
         """
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Min(this=col_expr)
+        col_expr = SQLFactory._extract_expression(column)
+        return AggregateExpression(exp.Min(this=col_expr))
 
     # ===================
     # Advanced SQL Operations
     # ===================
 
     @staticmethod
-    def rollup(*columns: Union[str, exp.Expression]) -> exp.Expression:
+    def rollup(*columns: Union[str, exp.Expression]) -> FunctionExpression:
         """Create a ROLLUP expression for GROUP BY clauses.
 
         Args:
@@ -850,10 +865,10 @@ class SQLFactory:
             ```
         """
         column_exprs = [exp.column(col) if isinstance(col, str) else col for col in columns]
-        return exp.Rollup(expressions=column_exprs)
+        return FunctionExpression(exp.Rollup(expressions=column_exprs))
 
     @staticmethod
-    def cube(*columns: Union[str, exp.Expression]) -> exp.Expression:
+    def cube(*columns: Union[str, exp.Expression]) -> FunctionExpression:
         """Create a CUBE expression for GROUP BY clauses.
 
         Args:
@@ -873,10 +888,10 @@ class SQLFactory:
             ```
         """
         column_exprs = [exp.column(col) if isinstance(col, str) else col for col in columns]
-        return exp.Cube(expressions=column_exprs)
+        return FunctionExpression(exp.Cube(expressions=column_exprs))
 
     @staticmethod
-    def grouping_sets(*column_sets: Union[tuple[str, ...], list[str]]) -> exp.Expression:
+    def grouping_sets(*column_sets: Union[tuple[str, ...], list[str]]) -> FunctionExpression:
         """Create a GROUPING SETS expression for GROUP BY clauses.
 
         Args:
@@ -908,10 +923,10 @@ class SQLFactory:
             else:
                 set_expressions.append(exp.column(column_set))
 
-        return exp.GroupingSets(expressions=set_expressions)
+        return FunctionExpression(exp.GroupingSets(expressions=set_expressions))
 
     @staticmethod
-    def any(values: Union[list[Any], exp.Expression, str]) -> exp.Expression:
+    def any(values: Union[list[Any], exp.Expression, str]) -> FunctionExpression:
         """Create an ANY expression for use with comparison operators.
 
         Args:
@@ -932,18 +947,18 @@ class SQLFactory:
             ```
         """
         if isinstance(values, list):
-            literals = [SQLFactory._to_literal(v) for v in values]
-            return exp.Any(this=exp.Array(expressions=literals))
+            literals = [SQLFactory.to_literal(v) for v in values]
+            return FunctionExpression(exp.Any(this=exp.Array(expressions=literals)))
         if isinstance(values, str):
             # Parse as SQL
             parsed = exp.maybe_parse(values)  # type: ignore[var-annotated]
             if parsed:
-                return exp.Any(this=parsed)
-            return exp.Any(this=exp.Literal.string(values))
-        return exp.Any(this=values)
+                return FunctionExpression(exp.Any(this=parsed))
+            return FunctionExpression(exp.Any(this=exp.Literal.string(values)))
+        return FunctionExpression(exp.Any(this=values))
 
     @staticmethod
-    def not_any_(values: Union[list[Any], exp.Expression, str]) -> exp.Expression:
+    def not_any_(values: Union[list[Any], exp.Expression, str]) -> FunctionExpression:
         """Create a NOT ANY expression for use with comparison operators.
 
         Args:
@@ -963,14 +978,14 @@ class SQLFactory:
             )
             ```
         """
-        return SQLFactory.any(values)  # NOT ANY is handled by the comparison operator
+        return SQLFactory.any(values)
 
     # ===================
     # String Functions
     # ===================
 
     @staticmethod
-    def concat(*expressions: Union[str, exp.Expression]) -> exp.Expression:
+    def concat(*expressions: Union[str, exp.Expression]) -> StringExpression:
         """Create a CONCAT expression.
 
         Args:
@@ -980,10 +995,10 @@ class SQLFactory:
             CONCAT expression.
         """
         exprs = [exp.column(expr) if isinstance(expr, str) else expr for expr in expressions]
-        return exp.Concat(expressions=exprs)
+        return StringExpression(exp.Concat(expressions=exprs))
 
     @staticmethod
-    def upper(column: Union[str, exp.Expression]) -> exp.Expression:
+    def upper(column: Union[str, exp.Expression]) -> StringExpression:
         """Create an UPPER expression.
 
         Args:
@@ -993,10 +1008,10 @@ class SQLFactory:
             UPPER expression.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Upper(this=col_expr)
+        return StringExpression(exp.Upper(this=col_expr))
 
     @staticmethod
-    def lower(column: Union[str, exp.Expression]) -> exp.Expression:
+    def lower(column: Union[str, exp.Expression]) -> StringExpression:
         """Create a LOWER expression.
 
         Args:
@@ -1006,10 +1021,10 @@ class SQLFactory:
             LOWER expression.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Lower(this=col_expr)
+        return StringExpression(exp.Lower(this=col_expr))
 
     @staticmethod
-    def length(column: Union[str, exp.Expression]) -> exp.Expression:
+    def length(column: Union[str, exp.Expression]) -> StringExpression:
         """Create a LENGTH expression.
 
         Args:
@@ -1019,14 +1034,14 @@ class SQLFactory:
             LENGTH expression.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Length(this=col_expr)
+        return StringExpression(exp.Length(this=col_expr))
 
     # ===================
     # Math Functions
     # ===================
 
     @staticmethod
-    def round(column: Union[str, exp.Expression], decimals: int = 0) -> exp.Expression:
+    def round(column: Union[str, exp.Expression], decimals: int = 0) -> MathExpression:
         """Create a ROUND expression.
 
         Args:
@@ -1038,15 +1053,15 @@ class SQLFactory:
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
         if decimals == 0:
-            return exp.Round(this=col_expr)
-        return exp.Round(this=col_expr, expression=exp.Literal.number(decimals))
+            return MathExpression(exp.Round(this=col_expr))
+        return MathExpression(exp.Round(this=col_expr, expression=exp.Literal.number(decimals)))
 
     # ===================
     # Conversion Functions
     # ===================
 
     @staticmethod
-    def _to_literal(value: Any) -> exp.Expression:
+    def to_literal(value: Any) -> FunctionExpression:
         """Convert a Python value to a SQLGlot literal expression.
 
         Uses SQLGlot's built-in exp.convert() function for optimal dialect-agnostic
@@ -1063,12 +1078,52 @@ class SQLFactory:
         Returns:
             SQLGlot expression representing the literal value.
         """
+        if isinstance(value, exp.Expression):
+            return FunctionExpression(value)
+        return FunctionExpression(exp.convert(value))
+
+    @staticmethod
+    def _to_expression(value: Any) -> exp.Expression:
+        """Convert a Python value to a raw SQLGlot expression.
+
+        Args:
+            value: Python value or SQLGlot expression to convert.
+
+        Returns:
+            Raw SQLGlot expression.
+        """
+        if isinstance(value, exp.Expression):
+            return value
+        return exp.convert(value)
+
+    @staticmethod
+    def _extract_expression(value: Any) -> exp.Expression:
+        """Extract SQLGlot expression from value, handling our wrapper types.
+
+        Args:
+            value: String, SQLGlot expression, or our wrapper type.
+
+        Returns:
+            Raw SQLGlot expression.
+        """
+        from sqlspec.builder._expression_wrappers import ExpressionWrapper
+        from sqlspec.builder.mixins._select_operations import Case
+
+        if isinstance(value, str):
+            return exp.column(value)
+        if isinstance(value, Column):
+            return value._expression
+        if isinstance(value, ExpressionWrapper):
+            return value.expression
+        if isinstance(value, Case):
+            # Case has _expression property via trait
+            return exp.Case(ifs=value._conditions, default=value._default)
         if isinstance(value, exp.Expression):
             return value
         return exp.convert(value)
 
     @staticmethod
-    def decode(column: Union[str, exp.Expression], *args: Union[str, exp.Expression, Any]) -> exp.Expression:
+    def decode(column: Union[str, exp.Expression], *args: Union[str, exp.Expression, Any]) -> FunctionExpression:
         """Create a DECODE expression (Oracle-style conditional logic).
 
         DECODE compares column to each search value and returns the corresponding result.
@@ -1105,22 +1160,22 @@ class SQLFactory:
         for i in range(0, len(args) - 1, 2):
             if i + 1 >= len(args):
                 # Odd number of args means last one is default
-                default = SQLFactory._to_literal(args[i])
+                default = SQLFactory._to_expression(args[i])
                 break
 
             search_val = args[i]
             result_val = args[i + 1]
 
-            search_expr = SQLFactory._to_literal(search_val)
-            result_expr = SQLFactory._to_literal(result_val)
+            search_expr = SQLFactory._to_expression(search_val)
+            result_expr = SQLFactory._to_expression(result_val)
 
             condition = exp.EQ(this=col_expr, expression=search_expr)
-            conditions.append(exp.When(this=condition, then=result_expr))
+            conditions.append(exp.If(this=condition, true=result_expr))
 
-        return exp.Case(ifs=conditions, default=default)
+        return FunctionExpression(exp.Case(ifs=conditions, default=default))
 
     @staticmethod
-    def cast(column: Union[str, exp.Expression], data_type: str) -> exp.Expression:
+    def cast(column: Union[str, exp.Expression], data_type: str) -> ConversionExpression:
         """Create a CAST expression for type conversion.
 
         Args:
@@ -1131,10 +1186,10 @@ class SQLFactory:
             CAST expression.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Cast(this=col_expr, to=exp.DataType.build(data_type))
+        return ConversionExpression(exp.Cast(this=col_expr, to=exp.DataType.build(data_type)))
 
     @staticmethod
-    def coalesce(*expressions: Union[str, exp.Expression]) -> exp.Expression:
+    def coalesce(*expressions: Union[str, exp.Expression]) -> ConversionExpression:
         """Create a COALESCE expression.
 
         Args:
@@ -1144,10 +1199,12 @@ class SQLFactory:
             COALESCE expression.
         """
         exprs = [exp.column(expr) if isinstance(expr, str) else expr for expr in expressions]
-        return exp.Coalesce(expressions=exprs)
+        return ConversionExpression(exp.Coalesce(expressions=exprs))
 
     @staticmethod
-    def nvl(column: Union[str, exp.Expression], substitute_value: Union[str, exp.Expression, Any]) -> exp.Expression:
+    def nvl(
+        column: Union[str, exp.Expression], substitute_value: Union[str, exp.Expression, Any]
+    ) -> ConversionExpression:
         """Create an NVL (Oracle-style) expression using COALESCE.
 
         Args:
@@ -1158,15 +1215,15 @@ class SQLFactory:
             COALESCE expression equivalent to NVL.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        sub_expr = SQLFactory._to_literal(substitute_value)
-        return exp.Coalesce(expressions=[col_expr, sub_expr])
+        sub_expr = SQLFactory._to_expression(substitute_value)
+        return ConversionExpression(exp.Coalesce(expressions=[col_expr, sub_expr]))
 
     @staticmethod
     def nvl2(
         column: Union[str, exp.Expression],
         value_if_not_null: Union[str, exp.Expression, Any],
         value_if_null: Union[str, exp.Expression, Any],
-    ) -> exp.Expression:
+    ) -> ConversionExpression:
         """Create an NVL2 (Oracle-style) expression using CASE.
 
         NVL2 returns value_if_not_null if column is not NULL,
@@ -1187,22 +1244,22 @@ class SQLFactory:
             ```
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        not_null_expr = SQLFactory._to_literal(value_if_not_null)
-        null_expr = SQLFactory._to_literal(value_if_null)
+        not_null_expr = SQLFactory._to_expression(value_if_not_null)
+        null_expr = SQLFactory._to_expression(value_if_null)
 
         # Create CASE WHEN column IS NOT NULL THEN value_if_not_null ELSE value_if_null END
         is_null = exp.Is(this=col_expr, expression=exp.Null())
         condition = exp.Not(this=is_null)
         when_clause = exp.If(this=condition, true=not_null_expr)
 
-        return exp.Case(ifs=[when_clause], default=null_expr)
+        return ConversionExpression(exp.Case(ifs=[when_clause], default=null_expr))
 
     # ===================
     # Bulk Operations
     # ===================
 
     @staticmethod
-    def bulk_insert(table_name: str, column_count: int, placeholder_style: str = "?") -> exp.Expression:
+    def bulk_insert(table_name: str, column_count: int, placeholder_style: str = "?") -> FunctionExpression:
         """Create bulk INSERT expression for executemany operations.
 
         This is specifically for bulk loading operations like CSV ingestion where
@@ -1237,13 +1294,15 @@ class SQLFactory:
             # Creates: INSERT INTO "my_table" VALUES (:1, :2, :3)
             ```
         """
-        return exp.Insert(
-            this=exp.Table(this=exp.to_identifier(table_name)),
-            expression=exp.Values(
-                expressions=[
-                    exp.Tuple(expressions=[exp.Placeholder(this=placeholder_style) for _ in range(column_count)])
-                ]
-            ),
+        return FunctionExpression(
+            exp.Insert(
+                this=exp.Table(this=exp.to_identifier(table_name)),
+                expression=exp.Values(
+                    expressions=[
+                        exp.Tuple(expressions=[exp.Placeholder(this=placeholder_style) for _ in range(column_count)])
+                    ]
+                ),
+            )
         )
 
     def truncate(self, table_name: str) -> "Truncate":
@@ -1297,7 +1356,7 @@ class SQLFactory:
         self,
         partition_by: Optional[Union[str, list[str], exp.Expression]] = None,
         order_by: Optional[Union[str, list[str], exp.Expression]] = None,
-    ) -> exp.Expression:
+    ) -> FunctionExpression:
         """Create a ROW_NUMBER() window function.
 
         Args:
@@ -1313,7 +1372,7 @@ class SQLFactory:
         self,
         partition_by: Optional[Union[str, list[str], exp.Expression]] = None,
         order_by: Optional[Union[str, list[str], exp.Expression]] = None,
-    ) -> exp.Expression:
+    ) -> FunctionExpression:
         """Create a RANK() window function.
 
         Args:
@@ -1329,7 +1388,7 @@ class SQLFactory:
         self,
         partition_by: Optional[Union[str, list[str], exp.Expression]] = None,
         order_by: Optional[Union[str, list[str], exp.Expression]] = None,
-    ) -> exp.Expression:
+    ) -> FunctionExpression:
         """Create a DENSE_RANK() window function.
 
         Args:
@@ -1347,7 +1406,7 @@ class SQLFactory:
         func_args: list[exp.Expression],
         partition_by: Optional[Union[str, list[str], exp.Expression]] = None,
         order_by: Optional[Union[str, list[str], exp.Expression]] = None,
-    ) -> exp.Expression:
+    ) -> FunctionExpression:
         """Helper to create window function expressions.
 
         Args:
@@ -1373,13 +1432,13 @@ class SQLFactory:
 
         if order_by:
             if isinstance(order_by, str):
-                over_args["order"] = [exp.column(order_by).asc()]
+                over_args["order"] = exp.Order(expressions=[exp.column(order_by).asc()])
             elif isinstance(order_by, list):
-                over_args["order"] = [exp.column(col).asc() for col in order_by]
+                over_args["order"] = exp.Order(expressions=[exp.column(col).asc() for col in order_by])
             elif isinstance(order_by, exp.Expression):
-                over_args["order"] = [order_by]
+                over_args["order"] = exp.Order(expressions=[order_by])
 
-        return exp.Window(this=func_expr, **over_args)
+        return FunctionExpression(exp.Window(this=func_expr, **over_args))
 
 
 # Create a default SQL factory instance

sqlspec/builder/_column.py

@@ -5,7 +5,7 @@ for building SQL conditions with type safety and parameter binding.
 """
 
 from collections.abc import Iterable
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
 from sqlglot import exp
 
@@ -241,6 +241,10 @@ class Column:
         """Create a DESC ordering expression."""
         return exp.Ordered(this=self._expression, desc=True)
 
+    def as_(self, alias: str) -> exp.Alias:
+        """Create an aliased expression."""
+        return cast("exp.Alias", exp.alias_(self._expression, alias))
+
     def __repr__(self) -> str:
         if self.table:
             return f"Column<{self.table}.{self.name}>"

sqlspec/builder/_expression_wrappers.py

@@ -0,0 +1,46 @@
+"""Expression wrapper classes for proper type annotations."""
+
+from typing import cast
+
+from sqlglot import exp
+
+__all__ = ("AggregateExpression", "ConversionExpression", "FunctionExpression", "MathExpression", "StringExpression")
+
+
+class ExpressionWrapper:
+    """Base wrapper for SQLGlot expressions."""
+
+    def __init__(self, expression: exp.Expression) -> None:
+        self._expression = expression
+
+    def as_(self, alias: str) -> exp.Alias:
+        """Create an aliased expression."""
+        return cast("exp.Alias", exp.alias_(self._expression, alias))
+
+    @property
+    def expression(self) -> exp.Expression:
+        """Get the underlying SQLGlot expression."""
+        return self._expression
+
+    def __str__(self) -> str:
+        return str(self._expression)
+
+
+class AggregateExpression(ExpressionWrapper):
+    """Aggregate functions like COUNT, SUM, AVG."""
+
+
+class FunctionExpression(ExpressionWrapper):
+    """General SQL functions."""
+
+
+class MathExpression(ExpressionWrapper):
+    """Mathematical functions like ROUND."""
+
+
+class StringExpression(ExpressionWrapper):
+    """String functions like UPPER, LOWER, LENGTH."""
+
+
+class ConversionExpression(ExpressionWrapper):
+    """Conversion functions like CAST, COALESCE."""

sqlspec/builder/_insert.py

@@ -412,9 +412,7 @@ class ConflictBuilder:
         # Create ON CONFLICT with proper structure
         conflict_keys = [exp.to_identifier(col) for col in self._columns] if self._columns else None
         on_conflict = exp.OnConflict(
-            conflict_keys=conflict_keys,
-            action=exp.var("DO UPDATE"),
-            expressions=set_expressions if set_expressions else None,
+            conflict_keys=conflict_keys, action=exp.var("DO UPDATE"), expressions=set_expressions or None
         )
 
         insert_expr.set("conflict", on_conflict)

sqlspec/builder/_update.py

@@ -44,26 +44,26 @@ class Update(
         update_query = (
             Update()
             .table("users")
-            .set(name="John Doe")
-            .set(email="john@example.com")
+            .set_(name="John Doe")
+            .set_(email="john@example.com")
             .where("id = 1")
         )
 
         update_query = (
-            Update("users").set(name="John Doe").where("id = 1")
+            Update("users").set_(name="John Doe").where("id = 1")
         )
 
         update_query = (
             Update()
             .table("users")
-            .set(status="active")
+            .set_(status="active")
             .where_eq("id", 123)
         )
 
         update_query = (
             Update()
             .table("users", "u")
-            .set(name="Updated Name")
+            .set_(name="Updated Name")
             .from_("profiles", "p")
             .where("u.id = p.user_id AND p.is_verified = true")
         )

sqlspec/builder/mixins/_order_limit_operations.py

@@ -10,6 +10,9 @@ from sqlspec.builder._parsing_utils import parse_order_expression
 from sqlspec.exceptions import SQLBuilderError
 
 if TYPE_CHECKING:
+    from sqlspec.builder._column import Column
+    from sqlspec.builder._expression_wrappers import ExpressionWrapper
+    from sqlspec.builder.mixins._select_operations import Case
     from sqlspec.protocols import SQLBuilderProtocol
 
 __all__ = ("LimitOffsetClauseMixin", "OrderByClauseMixin", "ReturningClauseMixin")
@@ -24,7 +27,7 @@ class OrderByClauseMixin:
     # Type annotation for PyRight - this will be provided by the base class
     _expression: Optional[exp.Expression]
 
-    def order_by(self, *items: Union[str, exp.Ordered], desc: bool = False) -> Self:
+    def order_by(self, *items: Union[str, exp.Ordered, "Column"], desc: bool = False) -> Self:
         """Add ORDER BY clause.
 
         Args:
@@ -49,7 +52,13 @@ class OrderByClauseMixin:
                 if desc:
                     order_item = order_item.desc()
             else:
-                order_item = item
+                # Extract expression from Column objects or use as-is for sqlglot expressions
+                from sqlspec._sql import SQLFactory
+
+                extracted_item = SQLFactory._extract_expression(item)
+                order_item = extracted_item
+                if desc and not isinstance(item, exp.Ordered):
+                    order_item = order_item.desc()
             current_expr = current_expr.order_by(order_item, copy=False)
         builder._expression = current_expr
         return cast("Self", builder)
@@ -111,7 +120,7 @@ class ReturningClauseMixin:
     # Type annotation for PyRight - this will be provided by the base class
     _expression: Optional[exp.Expression]
 
-    def returning(self, *columns: Union[str, exp.Expression]) -> Self:
+    def returning(self, *columns: Union[str, exp.Expression, "Column", "ExpressionWrapper", "Case"]) -> Self:
         """Add RETURNING clause to the statement.
 
         Args:
@@ -130,6 +139,9 @@ class ReturningClauseMixin:
         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]
+        # Extract expressions from various wrapper types
+        from sqlspec._sql import SQLFactory
+
+        returning_exprs = [SQLFactory._extract_expression(c) for c in columns]
         self._expression.set("returning", exp.Returning(expressions=returning_exprs))
         return self

sqlspec/builder/mixins/_select_operations.py

@@ -858,7 +858,7 @@ class Case:
         from sqlspec._sql import SQLFactory
 
         cond_expr = exp.maybe_parse(condition) or exp.column(condition) if isinstance(condition, str) else condition
-        val_expr = SQLFactory._to_literal(value)
+        val_expr = SQLFactory._to_expression(value)
 
         # SQLGlot uses exp.If for CASE WHEN clauses, not exp.When
         when_clause = exp.If(this=cond_expr, true=val_expr)
@@ -876,7 +876,7 @@ class Case:
         """
         from sqlspec._sql import SQLFactory
 
-        self._default = SQLFactory._to_literal(value)
+        self._default = SQLFactory._to_expression(value)
         return self
 
     def end(self) -> Self:

sqlspec/builder/mixins/_update_operations.py

@@ -111,10 +111,10 @@ class UpdateSetClauseMixin:
         """Set columns and values for the UPDATE statement.
 
         Supports:
-        - set(column, value)
-        - set(mapping)
-        - set(**kwargs)
-        - set(mapping, **kwargs)
+        - set_(column, value)
+        - set_(mapping)
+        - set_(**kwargs)
+        - set_(mapping, **kwargs)
 
         Args:
             *args: Either (column, value) or a mapping.

sqlspec/protocols.py

@@ -20,6 +20,7 @@ if TYPE_CHECKING:
 __all__ = (
     "BytesConvertibleProtocol",
     "DictProtocol",
+    "ExpressionWithAliasProtocol",
     "FilterAppenderProtocol",
     "FilterParameterProtocol",
     "HasExpressionProtocol",
@@ -172,6 +173,15 @@ class BytesConvertibleProtocol(Protocol):
         ...
 
 
+@runtime_checkable
+class ExpressionWithAliasProtocol(Protocol):
+    """Protocol for SQL expressions that support aliasing with as_() method."""
+
+    def as_(self, alias: str, **kwargs: Any) -> "exp.Alias":
+        """Create an aliased expression."""
+        ...
+
+
 @runtime_checkable
 class ObjectStoreItemProtocol(Protocol):
     """Protocol for object store items with path/key attributes."""

{sqlspec-0.17.0.dist-info → sqlspec-0.17.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.17.0
+Version: 0.17.1
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/

{sqlspec-0.17.0.dist-info → sqlspec-0.17.1.dist-info}/RECORD

@@ -2,14 +2,14 @@ sqlspec/__init__.py,sha256=wy9ZqukBvr2WZkUmrljRHPGFjpUKWkEXxFWlTLuciJc,2123
 sqlspec/__main__.py,sha256=lXBKZMOXA1uY735Rnsb-GS7aXy0nt22tYmd2X9FcxrY,253
 sqlspec/__metadata__.py,sha256=IUw6MCTy1oeUJ1jAVYbuJLkOWbiAWorZ5W-E-SAD9N4,395
 sqlspec/_serialization.py,sha256=6U5-smk2h2yl0i6am2prtOLJTdu4NJQdcLlSfSUMaUQ,2590
-sqlspec/_sql.py,sha256=UrJCc_iriWw9Dm1eeGswWoFvkeRtfueuTG_f01O7CAk,46623
+sqlspec/_sql.py,sha256=M1sirpRds7Bs3r72gRUTxO8Yp7qup-GPD3WLiEEAwVg,49135
 sqlspec/_typing.py,sha256=jv-7QHGLrJLfnP86bR-Xcmj3PDoddNZEKDz_vYRBiAU,22684
 sqlspec/base.py,sha256=OhFSpDaweCjZEabpTtl95pg91WzMko76d7sFOjyZSoo,25730
 sqlspec/cli.py,sha256=3ZxPwl4neNWyrAkM9J9ccC_gaFigDJbhuZfx15JVE7E,9903
 sqlspec/config.py,sha256=s7csxGK0SlTvB9jOvHlKKm4Y272RInQrUd6hGXwy31Q,14974
 sqlspec/exceptions.py,sha256=mCqNJ0JSPA-TUPpAfdctwwqJWbiNsWap5ATNNRdczwU,6159
 sqlspec/loader.py,sha256=KSL5OsjPsuZZJrgohdhdmimwDqVPj_BvHqHIpP2Fq_0,25818
-sqlspec/protocols.py,sha256=iwwy7zdIBV7TcoxIYpKuTvN5fGiULQac2f4a-saxyKU,12937
+sqlspec/protocols.py,sha256=GxKDn-Uw4fBVaKprYE3rCuhSz1CF2yV4awIrXbV2_j4,13236
 sqlspec/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sqlspec/typing.py,sha256=yj8D8O-pkfUVZDfVHEgQaB95-5alwgQbp_sqNJOVhvQ,6301
 sqlspec/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -58,25 +58,26 @@ sqlspec/adapters/sqlite/driver.py,sha256=uAhasoCNOV30gTvl1EUpofRcm8YiEW5RnVy07Xy
 sqlspec/adapters/sqlite/pool.py,sha256=FxlnBksmiPDLyMB0C7j3wjfc45PU_RrukTwNAzN3DDQ,4977
 sqlspec/builder/__init__.py,sha256=AY_D6TlSpYFJ7sU39S9xubq-eXZTpuNDlisoeK0LojU,1675
 sqlspec/builder/_base.py,sha256=yz-6e-x66vrNne6z5zq4Ae0C3p0mHEEIe1Y8er-A0pg,17812
-sqlspec/builder/_column.py,sha256=46baZj403BKfGjZcMc9LtQfMLeMQ7ROPyFL64V7dDM0,13124
+sqlspec/builder/_column.py,sha256=GfTMFPzJIhwDVKefMbyom-HoEj-KSKB92-XoZfchnEo,13289
 sqlspec/builder/_ddl.py,sha256=A_fV4d92o2ZOhX150YMSsQDm3veQTQrwlxgLdFMBBfg,48184
 sqlspec/builder/_ddl_utils.py,sha256=1mFSNe9w5rZXA1Ud4CTuca7eibi0XayHrIPcnEgRB7s,4034
 sqlspec/builder/_delete.py,sha256=xWA5nQB3UB8kpEGXN2k5ynt4cGZ7blkNoURpI0bKoeg,2264
-sqlspec/builder/_insert.py,sha256=rARWh5olbur6oPP_3FoAuJp8irj5cRLW0mKdWEx2cqU,16896
+sqlspec/builder/_expression_wrappers.py,sha256=HTl8qAFD4sZNXLD2akkJWGCPse2HWS237mTGE4Cx_7I,1244
+sqlspec/builder/_insert.py,sha256=p0UegiB9WNkHWafTPgfyWsQlt76oRp7VvuMK3_zIjDw,16850
 sqlspec/builder/_merge.py,sha256=95PLQSKA3zjk0wTZG3m817fTZpsS95PrS2qF34iLAP8,2004
 sqlspec/builder/_parsing_utils.py,sha256=RH8OFBFAetalEgHW5JLcEyyCdW_awVdy07MjboOkqL4,8383
 sqlspec/builder/_select.py,sha256=m5sfyuAssjlNimLLNBAeFooVIfM2FgKN1boPfdsOkaA,5785
-sqlspec/builder/_update.py,sha256=UFHM_uWVY5RnZQ6winiyjKNtBryKRAXJlXtCVQdifyw,6015
+sqlspec/builder/_update.py,sha256=QieiguEq9T_UECv10f1xwQJp58gc3w246cvtCDpPwuw,6020
 sqlspec/builder/mixins/__init__.py,sha256=YXhAzKmQbQtne5j26SKWY8PUxwosl0RhlhLoahAdkj0,1885
 sqlspec/builder/mixins/_cte_and_set_ops.py,sha256=p5O9m_jvpaWxv1XP9Ys2DRI-qOTq30rr2EwYjAbIT8o,9088
 sqlspec/builder/mixins/_delete_operations.py,sha256=l0liajnoAfRgtWtyStuAIfxreEFRkNO4DtBwyGqAfic,1198
 sqlspec/builder/mixins/_insert_operations.py,sha256=3ZuVNAPgJG0fzOPaprwUPa0Un3NP7erHwtCg8AGZWD8,9500
 sqlspec/builder/mixins/_join_operations.py,sha256=8o_aApK5cmJbNCNfWa4bs5fR2zgQUjon5p-oyiW41Qw,11440
 sqlspec/builder/mixins/_merge_operations.py,sha256=e9QDv1s84-2F2ZAZrr7UJtKXhy3X0NDN7AZ--8mOTKw,24193
-sqlspec/builder/mixins/_order_limit_operations.py,sha256=ABPuFSqHRv7XaS9-3HNZO3Jn0QovhJrkYT158xxduns,4835
+sqlspec/builder/mixins/_order_limit_operations.py,sha256=KrTXE0HmKCMn4AkNFyMhEZrmJ2Dl-o5kSiCjk2jNIKM,5499
 sqlspec/builder/mixins/_pivot_operations.py,sha256=j5vdzXuEqB1Jn3Ie_QjVwSH2_OEi65oZ64bQJHd3jXo,6108
-sqlspec/builder/mixins/_select_operations.py,sha256=m7iejdCw04mfxohNiHWeQSKQyI94vrhJ_JcYRhUPYw8,35314
-sqlspec/builder/mixins/_update_operations.py,sha256=lk9VRM0KGmYhofbWChemJxSZF6I0LhrRgqMXVmXZMeU,8650
+sqlspec/builder/mixins/_select_operations.py,sha256=JznnA0bS6yXlylSLpLQ9xNdnWOo0ckqirOSDkceRmJw,35320
+sqlspec/builder/mixins/_update_operations.py,sha256=rcmnmSSwHSujqe0gd-dKsWHLX9nPMS1we1Y3_h4S7G4,8654
 sqlspec/builder/mixins/_where_clause.py,sha256=1iz7Y2x_ooG2bOCu2zX0v5_bkGFpAckVQKvnyrR1JNQ,36373
 sqlspec/core/__init__.py,sha256=rU_xGsXhqIOnBbyB2InhJknYePm5NQ2DSWdBigror4g,1775
 sqlspec/core/cache.py,sha256=cLL9bd5wn1oeMzn5E5Ym0sAemA8U4QP6B55x4L9-26I,27044
@@ -129,9 +130,9 @@ sqlspec/utils/singleton.py,sha256=SKnszJi1NPeERgX7IjVIGYAYx4XqR1E_rph3bU6olAU,10
 sqlspec/utils/sync_tools.py,sha256=WRuk1ZEhb_0CRrumAdnmi-i-dV6qVd3cgJyZw8RY9QQ,7390
 sqlspec/utils/text.py,sha256=n5K0gvXvyCc8jNteNKsBOymwf_JnQ65f3lu0YaYq4Ys,2898
 sqlspec/utils/type_guards.py,sha256=9C4SRebO4JiQrMzcJZFUA0KjSU48G26RmX6lbijyjBg,30476
-sqlspec-0.17.0.dist-info/METADATA,sha256=3VTksHJXA8Azr2boYZpQtPO27y_QXZq_jYk-zuftYzE,16822
-sqlspec-0.17.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sqlspec-0.17.0.dist-info/entry_points.txt,sha256=G-ZqY1Nuuw3Iys7nXw23f6ILenk_Lt47VdK2mhJCWHg,53
-sqlspec-0.17.0.dist-info/licenses/LICENSE,sha256=MdujfZ6l5HuLz4mElxlu049itenOR3gnhN1_Nd3nVcM,1078
-sqlspec-0.17.0.dist-info/licenses/NOTICE,sha256=Lyir8ozXWov7CyYS4huVaOCNrtgL17P-bNV-5daLntQ,1634
-sqlspec-0.17.0.dist-info/RECORD,,
+sqlspec-0.17.1.dist-info/METADATA,sha256=mjoS62X8qL5LIdUs0VRuK1kCZPw2Rsk8GVjyGByNQzg,16822
+sqlspec-0.17.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sqlspec-0.17.1.dist-info/entry_points.txt,sha256=G-ZqY1Nuuw3Iys7nXw23f6ILenk_Lt47VdK2mhJCWHg,53
+sqlspec-0.17.1.dist-info/licenses/LICENSE,sha256=MdujfZ6l5HuLz4mElxlu049itenOR3gnhN1_Nd3nVcM,1078
+sqlspec-0.17.1.dist-info/licenses/NOTICE,sha256=Lyir8ozXWov7CyYS4huVaOCNrtgL17P-bNV-5daLntQ,1634
+sqlspec-0.17.1.dist-info/RECORD,,