sqlspec 0.16.0__tar.gz → 0.16.1__tar.gz

{sqlspec-0.16.0 → sqlspec-0.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.16.0
+Version: 0.16.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.16.0 → sqlspec-0.16.1}/pyproject.toml

@@ -13,7 +13,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.9, <4.0"
-version = "0.16.0"
+version = "0.16.1"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"

{sqlspec-0.16.0 → sqlspec-0.16.1}/sqlspec/_sql.py

@@ -4,9 +4,10 @@ Provides both statement builders (select, insert, update, etc.) and column expre
 """
 
 import logging
-from typing import TYPE_CHECKING, Any, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
 
 import sqlglot
+from mypy_extensions import trait
 from sqlglot import exp
 from sqlglot.dialects.dialect import DialectType
 from sqlglot.errors import ParseError as SQLGlotParseError
@@ -36,6 +37,7 @@ from sqlspec.builder import (
 from sqlspec.exceptions import SQLBuilderError
 
 if TYPE_CHECKING:
+    from sqlspec.builder._column import ColumnExpression
     from sqlspec.core.statement import SQL
 
 __all__ = (
@@ -61,6 +63,7 @@ __all__ = (
     "Select",
     "Truncate",
     "Update",
+    "WindowFunctionBuilder",
     "sql",
 )
 
@@ -188,12 +191,8 @@ class SQLFactory:
                     )
                     raise SQLBuilderError(msg)
                 select_builder = Select(dialect=builder_dialect)
-                if select_builder._expression is None:
-                    select_builder.__post_init__()
                 return self._populate_select_from_sql(select_builder, sql_candidate)
         select_builder = Select(dialect=builder_dialect)
-        if select_builder._expression is None:
-            select_builder.__post_init__()
         if columns_or_sql:
             select_builder.select(*columns_or_sql)
         return select_builder
@@ -201,8 +200,6 @@ class SQLFactory:
     def insert(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Insert":
         builder_dialect = dialect or self.dialect
         builder = Insert(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
@@ -220,8 +217,6 @@ class SQLFactory:
     def update(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Update":
         builder_dialect = dialect or self.dialect
         builder = Update(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
@@ -235,8 +230,6 @@ class SQLFactory:
     def delete(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Delete":
         builder_dialect = dialect or self.dialect
         builder = Delete(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql and self._looks_like_sql(table_or_sql):
             detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
             if detected != "DELETE":
@@ -248,8 +241,6 @@ class SQLFactory:
     def merge(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Merge":
         builder_dialect = dialect or self.dialect
         builder = Merge(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
@@ -563,14 +554,112 @@ class SQLFactory:
         """
         return Column(name, table)
 
-    def __getattr__(self, name: str) -> Column:
+    @property
+    def case_(self) -> "Case":
+        """Create a CASE expression builder with improved syntax.
+
+        Returns:
+            Case builder instance for fluent CASE expression building.
+
+        Example:
+            ```python
+            case_expr = (
+                sql.case_.when("x = 1", "one")
+                .when("x = 2", "two")
+                .else_("other")
+                .end()
+            )
+            aliased_case = (
+                sql.case_.when("status = 'active'", 1)
+                .else_(0)
+                .as_("is_active")
+            )
+            ```
+        """
+        return Case()
+
+    @property
+    def row_number_(self) -> "WindowFunctionBuilder":
+        """Create a ROW_NUMBER() window function builder."""
+        return WindowFunctionBuilder("row_number")
+
+    @property
+    def rank_(self) -> "WindowFunctionBuilder":
+        """Create a RANK() window function builder."""
+        return WindowFunctionBuilder("rank")
+
+    @property
+    def dense_rank_(self) -> "WindowFunctionBuilder":
+        """Create a DENSE_RANK() window function builder."""
+        return WindowFunctionBuilder("dense_rank")
+
+    @property
+    def lag_(self) -> "WindowFunctionBuilder":
+        """Create a LAG() window function builder."""
+        return WindowFunctionBuilder("lag")
+
+    @property
+    def lead_(self) -> "WindowFunctionBuilder":
+        """Create a LEAD() window function builder."""
+        return WindowFunctionBuilder("lead")
+
+    @property
+    def exists_(self) -> "SubqueryBuilder":
+        """Create an EXISTS subquery builder."""
+        return SubqueryBuilder("exists")
+
+    @property
+    def in_(self) -> "SubqueryBuilder":
+        """Create an IN subquery builder."""
+        return SubqueryBuilder("in")
+
+    @property
+    def any_(self) -> "SubqueryBuilder":
+        """Create an ANY subquery builder."""
+        return SubqueryBuilder("any")
+
+    @property
+    def all_(self) -> "SubqueryBuilder":
+        """Create an ALL subquery builder."""
+        return SubqueryBuilder("all")
+
+    @property
+    def inner_join_(self) -> "JoinBuilder":
+        """Create an INNER JOIN builder."""
+        return JoinBuilder("inner join")
+
+    @property
+    def left_join_(self) -> "JoinBuilder":
+        """Create a LEFT JOIN builder."""
+        return JoinBuilder("left join")
+
+    @property
+    def right_join_(self) -> "JoinBuilder":
+        """Create a RIGHT JOIN builder."""
+        return JoinBuilder("right join")
+
+    @property
+    def full_join_(self) -> "JoinBuilder":
+        """Create a FULL OUTER JOIN builder."""
+        return JoinBuilder("full join")
+
+    @property
+    def cross_join_(self) -> "JoinBuilder":
+        """Create a CROSS JOIN builder."""
+        return JoinBuilder("cross join")
+
+    def __getattr__(self, name: str) -> "Column":
         """Dynamically create column references.
 
         Args:
             name: Column name.
 
         Returns:
-            Column object that supports method chaining and operator overloading.
+            Column object for the given name.
+
+        Note:
+            Special SQL constructs like case_, row_number_, etc. are now
+            handled as properties for better type safety.
         """
         return Column(name)
 
@@ -1282,6 +1371,7 @@ class SQLFactory:
         return exp.Window(this=func_expr, **over_args)
 
 
+@trait
 class Case:
     """Builder for CASE expressions using the SQL factory.
 
@@ -1304,6 +1394,19 @@ class Case:
         self._conditions: list[exp.If] = []
         self._default: Optional[exp.Expression] = None
 
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - convert to expression then compare."""
+        from sqlspec.builder._column import ColumnExpression
+
+        case_expr = exp.Case(ifs=self._conditions, default=self._default)
+        if other is None:
+            return ColumnExpression(exp.Is(this=case_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=case_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make Case hashable."""
+        return hash(id(self))
+
     def when(self, condition: Union[str, exp.Expression], value: Union[str, exp.Expression, Any]) -> "Case":
         """Add a WHEN clause.
 
@@ -1342,6 +1445,336 @@ class Case:
         """
         return exp.Case(ifs=self._conditions, default=self._default)
 
+    def as_(self, alias: str) -> exp.Alias:
+        """Complete the CASE expression with an alias.
+
+        Args:
+            alias: Alias name for the CASE expression.
+
+        Returns:
+            Aliased CASE expression.
+        """
+        case_expr = exp.Case(ifs=self._conditions, default=self._default)
+        return cast("exp.Alias", exp.alias_(case_expr, alias))
+
+
+@trait
+class WindowFunctionBuilder:
+    """Builder for window functions with fluent syntax.
+
+    Example:
+        ```python
+        from sqlspec import sql
+
+        # sql.row_number_.partition_by("department").order_by("salary")
+        window_func = (
+            sql.row_number_.partition_by("department")
+            .order_by("salary")
+            .as_("row_num")
+        )
+        ```
+    """
+
+    def __init__(self, function_name: str) -> None:
+        """Initialize the window function builder.
+
+        Args:
+            function_name: Name of the window function (row_number, rank, etc.)
+        """
+        self._function_name = function_name
+        self._partition_by_cols: list[exp.Expression] = []
+        self._order_by_cols: list[exp.Expression] = []
+        self._alias: Optional[str] = None
+
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - convert to expression then compare."""
+        from sqlspec.builder._column import ColumnExpression
+
+        window_expr = self._build_expression()
+        if other is None:
+            return ColumnExpression(exp.Is(this=window_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=window_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make WindowFunctionBuilder hashable."""
+        return hash(id(self))
+
+    def partition_by(self, *columns: Union[str, exp.Expression]) -> "WindowFunctionBuilder":
+        """Add PARTITION BY clause.
+
+        Args:
+            *columns: Columns to partition by.
+
+        Returns:
+            Self for method chaining.
+        """
+        for col in columns:
+            col_expr = exp.column(col) if isinstance(col, str) else col
+            self._partition_by_cols.append(col_expr)
+        return self
+
+    def order_by(self, *columns: Union[str, exp.Expression]) -> "WindowFunctionBuilder":
+        """Add ORDER BY clause.
+
+        Args:
+            *columns: Columns to order by.
+
+        Returns:
+            Self for method chaining.
+        """
+        for col in columns:
+            if isinstance(col, str):
+                col_expr = exp.column(col).asc()
+                self._order_by_cols.append(col_expr)
+            else:
+                # Convert to ordered expression
+                self._order_by_cols.append(exp.Ordered(this=col, desc=False))
+        return self
+
+    def as_(self, alias: str) -> exp.Expression:
+        """Complete the window function with an alias.
+
+        Args:
+            alias: Alias name for the window function.
+
+        Returns:
+            Aliased window function expression.
+        """
+        window_expr = self._build_expression()
+        return cast("exp.Alias", exp.alias_(window_expr, alias))
+
+    def build(self) -> exp.Expression:
+        """Complete the window function without an alias.
+
+        Returns:
+            Window function expression.
+        """
+        return self._build_expression()
+
+    def _build_expression(self) -> exp.Expression:
+        """Build the complete window function expression."""
+        # Create the function expression
+        func_expr = exp.Anonymous(this=self._function_name.upper(), expressions=[])
+
+        # Build the OVER clause arguments
+        over_args: dict[str, Any] = {}
+
+        if self._partition_by_cols:
+            over_args["partition_by"] = self._partition_by_cols
+
+        if self._order_by_cols:
+            over_args["order"] = exp.Order(expressions=self._order_by_cols)
+
+        return exp.Window(this=func_expr, **over_args)
+
+
+@trait
+class SubqueryBuilder:
+    """Builder for subquery operations with fluent syntax.
+
+    Example:
+        ```python
+        from sqlspec import sql
+
+        # sql.exists_(subquery)
+        exists_check = sql.exists_(
+            sql.select("1")
+            .from_("orders")
+            .where_eq("user_id", sql.users.id)
+        )
+
+        # sql.in_(subquery)
+        in_check = sql.in_(
+            sql.select("category_id")
+            .from_("categories")
+            .where_eq("active", True)
+        )
+        ```
+    """
+
+    def __init__(self, operation: str) -> None:
+        """Initialize the subquery builder.
+
+        Args:
+            operation: Type of subquery operation (exists, in, any, all)
+        """
+        self._operation = operation
+
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - not typically used but needed for type consistency."""
+        from sqlspec.builder._column import ColumnExpression
+
+        # SubqueryBuilder doesn't have a direct expression, so this is a placeholder
+        # In practice, this shouldn't be called as subqueries are used differently
+        placeholder_expr = exp.Literal.string(f"subquery_{self._operation}")
+        if other is None:
+            return ColumnExpression(exp.Is(this=placeholder_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=placeholder_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make SubqueryBuilder hashable."""
+        return hash(id(self))
+
+    def __call__(self, subquery: Union[str, exp.Expression, Any]) -> exp.Expression:
+        """Build the subquery expression.
+
+        Args:
+            subquery: The subquery - can be a SQL string, SelectBuilder, or expression
+
+        Returns:
+            The subquery expression (EXISTS, IN, ANY, ALL, etc.)
+        """
+        subquery_expr: exp.Expression
+        if isinstance(subquery, str):
+            # Parse as SQL
+            parsed: Optional[exp.Expression] = exp.maybe_parse(subquery)
+            if not parsed:
+                msg = f"Could not parse subquery SQL: {subquery}"
+                raise SQLBuilderError(msg)
+            subquery_expr = parsed
+        elif hasattr(subquery, "build") and callable(getattr(subquery, "build", None)):
+            # It's a query builder - build it to get the SQL and parse
+            built_query = subquery.build()  # pyright: ignore[reportAttributeAccessIssue]
+            subquery_expr = exp.maybe_parse(built_query.sql)
+            if not subquery_expr:
+                msg = f"Could not parse built query: {built_query.sql}"
+                raise SQLBuilderError(msg)
+        elif isinstance(subquery, exp.Expression):
+            subquery_expr = subquery
+        else:
+            # Try to convert to expression
+            parsed = exp.maybe_parse(str(subquery))
+            if not parsed:
+                msg = f"Could not convert subquery to expression: {subquery}"
+                raise SQLBuilderError(msg)
+            subquery_expr = parsed
+
+        # Build the appropriate expression based on operation
+        if self._operation == "exists":
+            return exp.Exists(this=subquery_expr)
+        if self._operation == "in":
+            # For IN, we create a subquery that can be used with WHERE column IN (subquery)
+            return exp.In(expressions=[subquery_expr])
+        if self._operation == "any":
+            return exp.Any(this=subquery_expr)
+        if self._operation == "all":
+            return exp.All(this=subquery_expr)
+        msg = f"Unknown subquery operation: {self._operation}"
+        raise SQLBuilderError(msg)
+
+
+@trait
+class JoinBuilder:
+    """Builder for JOIN operations with fluent syntax.
+
+    Example:
+        ```python
+        from sqlspec import sql
+
+        # sql.left_join_("posts").on("users.id = posts.user_id")
+        join_clause = sql.left_join_("posts").on(
+            "users.id = posts.user_id"
+        )
+
+        # Or with query builder
+        query = (
+            sql.select("users.name", "posts.title")
+            .from_("users")
+            .join(
+                sql.left_join_("posts").on(
+                    "users.id = posts.user_id"
+                )
+            )
+        )
+        ```
+    """
+
+    def __init__(self, join_type: str) -> None:
+        """Initialize the join builder.
+
+        Args:
+            join_type: Type of join (inner, left, right, full, cross)
+        """
+        self._join_type = join_type.upper()
+        self._table: Optional[Union[str, exp.Expression]] = None
+        self._condition: Optional[exp.Expression] = None
+        self._alias: Optional[str] = None
+
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - not typically used but needed for type consistency."""
+        from sqlspec.builder._column import ColumnExpression
+
+        # JoinBuilder doesn't have a direct expression, so this is a placeholder
+        # In practice, this shouldn't be called as joins are used differently
+        placeholder_expr = exp.Literal.string(f"join_{self._join_type.lower()}")
+        if other is None:
+            return ColumnExpression(exp.Is(this=placeholder_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=placeholder_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make JoinBuilder hashable."""
+        return hash(id(self))
+
+    def __call__(self, table: Union[str, exp.Expression], alias: Optional[str] = None) -> "JoinBuilder":
+        """Set the table to join.
+
+        Args:
+            table: Table name or expression to join
+            alias: Optional alias for the table
+
+        Returns:
+            Self for method chaining
+        """
+        self._table = table
+        self._alias = alias
+        return self
+
+    def on(self, condition: Union[str, exp.Expression]) -> exp.Expression:
+        """Set the join condition and build the JOIN expression.
+
+        Args:
+            condition: JOIN condition (e.g., "users.id = posts.user_id")
+
+        Returns:
+            Complete JOIN expression
+        """
+        if not self._table:
+            msg = "Table must be set before calling .on()"
+            raise SQLBuilderError(msg)
+
+        # Parse the condition
+        condition_expr: exp.Expression
+        if isinstance(condition, str):
+            parsed: Optional[exp.Expression] = exp.maybe_parse(condition)
+            condition_expr = parsed or exp.condition(condition)
+        else:
+            condition_expr = condition
+
+        # Build table expression
+        table_expr: exp.Expression
+        if isinstance(self._table, str):
+            table_expr = exp.to_table(self._table)
+            if self._alias:
+                table_expr = cast("exp.Expression", exp.alias_(table_expr, self._alias))
+        else:
+            table_expr = self._table
+            if self._alias:
+                table_expr = cast("exp.Expression", exp.alias_(table_expr, self._alias))
+
+        # Create the appropriate join type using same pattern as existing JoinClauseMixin
+        if self._join_type == "INNER JOIN":
+            return exp.Join(this=table_expr, on=condition_expr)
+        if self._join_type == "LEFT JOIN":
+            return exp.Join(this=table_expr, on=condition_expr, side="LEFT")
+        if self._join_type == "RIGHT JOIN":
+            return exp.Join(this=table_expr, on=condition_expr, side="RIGHT")
+        if self._join_type == "FULL JOIN":
+            return exp.Join(this=table_expr, on=condition_expr, side="FULL", kind="OUTER")
+        if self._join_type == "CROSS JOIN":
+            # CROSS JOIN doesn't use ON condition
+            return exp.Join(this=table_expr, kind="CROSS")
+        return exp.Join(this=table_expr, on=condition_expr)
+
 
 # Create a default SQL factory instance
 sql = SQLFactory()