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

sqlspec/__init__.py

@@ -1,4 +1,4 @@
-"""SQLSpec: Safe and elegant SQL query building for Python."""
+"""SQLSpec: Type-safe SQL query mapper for Python."""
 
 from sqlspec import adapters, base, builder, core, driver, exceptions, extensions, loader, migrations, typing, utils
 from sqlspec.__metadata__ import __version__

sqlspec/_sql.py

@@ -1,6 +1,6 @@
-"""Unified SQL factory for creating SQL builders and column expressions with a clean API.
+"""SQL factory for creating SQL builders and column expressions.
 
-Provides both statement builders (select, insert, update, etc.) and column expressions.
+Provides statement builders (select, insert, update, etc.) and column expressions.
 """
 
 import logging
@@ -42,11 +42,11 @@ from sqlspec.builder._expression_wrappers import (
 )
 from sqlspec.builder.mixins._join_operations import JoinBuilder
 from sqlspec.builder.mixins._select_operations import Case, SubqueryBuilder, WindowFunctionBuilder
+from sqlspec.core.statement import SQL
 from sqlspec.exceptions import SQLBuilderError
 
 if TYPE_CHECKING:
     from sqlspec.builder._expression_wrappers import ExpressionWrapper
-    from sqlspec.core.statement import SQL
 
 
 __all__ = (
@@ -109,7 +109,7 @@ SQL_STARTERS = {
 
 
 class SQLFactory:
-    """Unified factory for creating SQL builders and column expressions with a fluent API."""
+    """Factory for creating SQL builders and column expressions."""
 
     @classmethod
     def detect_sql_type(cls, sql: str, dialect: DialectType = None) -> str:
@@ -136,9 +136,6 @@ class SQLFactory:
         """
         self.dialect = dialect
 
-    # ===================
-    # Callable Interface
-    # ===================
     def __call__(self, statement: str, dialect: DialectType = None) -> "Any":
         """Create a SelectBuilder from a SQL string, only allowing SELECT/CTE queries.
 
@@ -184,9 +181,6 @@ class SQLFactory:
         )
         raise SQLBuilderError(msg)
 
-    # ===================
-    # Statement Builders
-    # ===================
     def select(
         self, *columns_or_sql: Union[str, exp.Expression, Column, "SQL", "Case"], dialect: DialectType = None
     ) -> "Select":
@@ -271,10 +265,6 @@ class SQLFactory:
             return builder.into(table_or_sql)
         return builder
 
-    # ===================
-    # DDL Statement Builders
-    # ===================
-
     def create_table(self, table_name: str, dialect: DialectType = None) -> "CreateTable":
         """Create a CREATE TABLE builder.
 
@@ -285,9 +275,7 @@ class SQLFactory:
         Returns:
             CreateTable builder instance
         """
-        builder = CreateTable(table_name)
-        builder.dialect = dialect or self.dialect
-        return builder
+        return CreateTable(table_name, dialect=dialect or self.dialect)
 
     def create_table_as_select(self, dialect: DialectType = None) -> "CreateTableAsSelect":
         """Create a CREATE TABLE AS SELECT builder.
@@ -298,35 +286,31 @@ class SQLFactory:
         Returns:
             CreateTableAsSelect builder instance
         """
-        builder = CreateTableAsSelect()
-        builder.dialect = dialect or self.dialect
-        return builder
+        return CreateTableAsSelect(dialect=dialect or self.dialect)
 
-    def create_view(self, dialect: DialectType = None) -> "CreateView":
+    def create_view(self, view_name: str, dialect: DialectType = None) -> "CreateView":
         """Create a CREATE VIEW builder.
 
         Args:
+            view_name: Name of the view to create
             dialect: Optional SQL dialect
 
         Returns:
             CreateView builder instance
         """
-        builder = CreateView()
-        builder.dialect = dialect or self.dialect
-        return builder
+        return CreateView(view_name, dialect=dialect or self.dialect)
 
-    def create_materialized_view(self, dialect: DialectType = None) -> "CreateMaterializedView":
+    def create_materialized_view(self, view_name: str, dialect: DialectType = None) -> "CreateMaterializedView":
         """Create a CREATE MATERIALIZED VIEW builder.
 
         Args:
+            view_name: Name of the materialized view to create
             dialect: Optional SQL dialect
 
         Returns:
             CreateMaterializedView builder instance
         """
-        builder = CreateMaterializedView()
-        builder.dialect = dialect or self.dialect
-        return builder
+        return CreateMaterializedView(view_name, dialect=dialect or self.dialect)
 
     def create_index(self, index_name: str, dialect: DialectType = None) -> "CreateIndex":
         """Create a CREATE INDEX builder.
@@ -340,18 +324,17 @@ class SQLFactory:
         """
         return CreateIndex(index_name, dialect=dialect or self.dialect)
 
-    def create_schema(self, dialect: DialectType = None) -> "CreateSchema":
+    def create_schema(self, schema_name: str, dialect: DialectType = None) -> "CreateSchema":
         """Create a CREATE SCHEMA builder.
 
         Args:
+            schema_name: Name of the schema to create
             dialect: Optional SQL dialect
 
         Returns:
             CreateSchema builder instance
         """
-        builder = CreateSchema()
-        builder.dialect = dialect or self.dialect
-        return builder
+        return CreateSchema(schema_name, dialect=dialect or self.dialect)
 
     def drop_table(self, table_name: str, dialect: DialectType = None) -> "DropTable":
         """Create a DROP TABLE builder.
@@ -365,16 +348,17 @@ class SQLFactory:
         """
         return DropTable(table_name, dialect=dialect or self.dialect)
 
-    def drop_view(self, dialect: DialectType = None) -> "DropView":
+    def drop_view(self, view_name: str, dialect: DialectType = None) -> "DropView":
         """Create a DROP VIEW builder.
 
         Args:
+            view_name: Name of the view to drop
             dialect: Optional SQL dialect
 
         Returns:
             DropView builder instance
         """
-        return DropView(dialect=dialect or self.dialect)
+        return DropView(view_name, dialect=dialect or self.dialect)
 
     def drop_index(self, index_name: str, dialect: DialectType = None) -> "DropIndex":
         """Create a DROP INDEX builder.
@@ -388,16 +372,17 @@ class SQLFactory:
         """
         return DropIndex(index_name, dialect=dialect or self.dialect)
 
-    def drop_schema(self, dialect: DialectType = None) -> "DropSchema":
+    def drop_schema(self, schema_name: str, dialect: DialectType = None) -> "DropSchema":
         """Create a DROP SCHEMA builder.
 
         Args:
+            schema_name: Name of the schema to drop
             dialect: Optional SQL dialect
 
         Returns:
             DropSchema builder instance
         """
-        return DropSchema(dialect=dialect or self.dialect)
+        return DropSchema(schema_name, dialect=dialect or self.dialect)
 
     def alter_table(self, table_name: str, dialect: DialectType = None) -> "AlterTable":
         """Create an ALTER TABLE builder.
@@ -409,22 +394,19 @@ class SQLFactory:
         Returns:
             AlterTable builder instance
         """
-        builder = AlterTable(table_name)
-        builder.dialect = dialect or self.dialect
-        return builder
+        return AlterTable(table_name, dialect=dialect or self.dialect)
 
-    def rename_table(self, dialect: DialectType = None) -> "RenameTable":
+    def rename_table(self, old_name: str, dialect: DialectType = None) -> "RenameTable":
         """Create a RENAME TABLE builder.
 
         Args:
+            old_name: Current name of the table
             dialect: Optional SQL dialect
 
         Returns:
             RenameTable builder instance
         """
-        builder = RenameTable()
-        builder.dialect = dialect or self.dialect
-        return builder
+        return RenameTable(old_name, dialect=dialect or self.dialect)
 
     def comment_on(self, dialect: DialectType = None) -> "CommentOn":
         """Create a COMMENT ON builder.
@@ -435,17 +417,11 @@ class SQLFactory:
         Returns:
             CommentOn builder instance
         """
-        builder = CommentOn()
-        builder.dialect = dialect or self.dialect
-        return builder
-
-    # ===================
-    # SQL Analysis Helpers
-    # ===================
+        return CommentOn(dialect=dialect or self.dialect)
 
     @staticmethod
     def _looks_like_sql(candidate: str, expected_type: Optional[str] = None) -> bool:
-        """Efficiently determine if a string looks like SQL.
+        """Determine if a string looks like SQL.
 
         Args:
             candidate: String to check
@@ -462,12 +438,7 @@ class SQLFactory:
         if expected_type:
             return candidate_upper.startswith(expected_type.upper())
 
-        # More sophisticated check for SQL vs column names
-        # Column names that start with SQL keywords are common (user_id, insert_date, etc.)
         if any(candidate_upper.startswith(starter) for starter in SQL_STARTERS):
-            # Additional checks to distinguish real SQL from column names:
-            # 1. Real SQL typically has spaces (SELECT ... FROM, INSERT INTO, etc.)
-            # 2. Check for common SQL syntax patterns
             return " " in candidate
 
         return False
@@ -475,19 +446,16 @@ class SQLFactory:
     def _populate_insert_from_sql(self, builder: "Insert", sql_string: str) -> "Insert":
         """Parse SQL string and populate INSERT builder using SQLGlot directly."""
         try:
-            # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Insert):
                 builder._expression = parsed_expr
                 return builder
 
             if isinstance(parsed_expr, exp.Select):
-                # The actual conversion logic can be handled by the builder itself
                 logger.info("Detected SELECT statement for INSERT - may need target table specification")
                 return builder
 
-            # For other statement types, just return the builder as-is
             logger.warning("Cannot create INSERT from %s statement", type(parsed_expr).__name__)
 
         except Exception as e:
@@ -497,8 +465,7 @@ class SQLFactory:
     def _populate_select_from_sql(self, builder: "Select", sql_string: str) -> "Select":
         """Parse SQL string and populate SELECT builder using SQLGlot directly."""
         try:
-            # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Select):
                 builder._expression = parsed_expr
@@ -513,8 +480,7 @@ class SQLFactory:
     def _populate_update_from_sql(self, builder: "Update", sql_string: str) -> "Update":
         """Parse SQL string and populate UPDATE builder using SQLGlot directly."""
         try:
-            # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Update):
                 builder._expression = parsed_expr
@@ -529,8 +495,7 @@ class SQLFactory:
     def _populate_delete_from_sql(self, builder: "Delete", sql_string: str) -> "Delete":
         """Parse SQL string and populate DELETE builder using SQLGlot directly."""
         try:
-            # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Delete):
                 builder._expression = parsed_expr
@@ -545,8 +510,7 @@ class SQLFactory:
     def _populate_merge_from_sql(self, builder: "Merge", sql_string: str) -> "Merge":
         """Parse SQL string and populate MERGE builder using SQLGlot directly."""
         try:
-            # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Merge):
                 builder._expression = parsed_expr
@@ -558,10 +522,6 @@ class SQLFactory:
             logger.warning("Failed to parse MERGE SQL, falling back to traditional mode: %s", e)
         return builder
 
-    # ===================
-    # Column References
-    # ===================
-
     def column(self, name: str, table: Optional[str] = None) -> Column:
         """Create a column reference.
 
@@ -576,10 +536,10 @@ class SQLFactory:
 
     @property
     def case_(self) -> "Case":
-        """Create a CASE expression builder with improved syntax.
+        """Create a CASE expression builder.
 
         Returns:
-            Case builder instance for fluent CASE expression building.
+            Case builder instance for CASE expression building.
 
         Example:
             ```python
@@ -678,23 +638,15 @@ class SQLFactory:
             Column object for the given name.
 
         Note:
-            Special SQL constructs like case_, row_number_, etc. are now
-            handled as properties for better type safety.
+            Special SQL constructs like case_, row_number_, etc. are
+            handled as properties for type safety.
         """
         return Column(name)
 
-    # ===================
-    # Raw SQL Expressions
-    # ===================
-
     @staticmethod
     def raw(sql_fragment: str, **parameters: Any) -> "Union[exp.Expression, SQL]":
         """Create a raw SQL expression from a string fragment with optional parameters.
 
-        This method makes it explicit that you are passing raw SQL that should
-        be parsed and included directly in the query. Useful for complex expressions,
-        database-specific functions, or when you need precise control over the SQL.
-
         Args:
             sql_fragment: Raw SQL string to parse into an expression.
             **parameters: Named parameters for parameter binding.
@@ -708,22 +660,21 @@ class SQLFactory:
 
         Example:
             ```python
-            # Raw expression without parameters (current behavior)
             expr = sql.raw("COALESCE(name, 'Unknown')")
 
-            # Raw SQL with named parameters (new functionality)
+
             stmt = sql.raw(
                 "LOWER(name) LIKE LOWER(:pattern)", pattern=f"%{query}%"
             )
 
-            # Raw complex expression with parameters
+
             expr = sql.raw(
                 "price BETWEEN :min_price AND :max_price",
                 min_price=100,
                 max_price=500,
             )
 
-            # Raw window function
+
             query = sql.select(
                 "name",
                 sql.raw(
@@ -733,11 +684,9 @@ class SQLFactory:
             ```
         """
         if not parameters:
-            # Original behavior - return pure expression
             try:
-                parsed: Optional[exp.Expression] = exp.maybe_parse(sql_fragment)
-                if parsed is not None:
-                    return parsed
+                parsed: exp.Expression = exp.maybe_parse(sql_fragment)
+                return parsed
                 if sql_fragment.strip().replace("_", "").replace(".", "").isalnum():
                     return exp.to_identifier(sql_fragment)
                 return exp.Literal.string(sql_fragment)
@@ -745,15 +694,8 @@ class SQLFactory:
                 msg = f"Failed to parse raw SQL fragment '{sql_fragment}': {e}"
                 raise SQLBuilderError(msg) from e
 
-        # New behavior - return SQL statement with parameters
-        from sqlspec.core.statement import SQL
-
         return SQL(sql_fragment, parameters)
 
-    # ===================
-    # Aggregate Functions
-    # ===================
-
     @staticmethod
     def count(
         column: Union[str, exp.Expression, "ExpressionWrapper", "Case", "Column"] = "*", distinct: bool = False
@@ -840,10 +782,6 @@ class SQLFactory:
         col_expr = SQLFactory._extract_expression(column)
         return AggregateExpression(exp.Min(this=col_expr))
 
-    # ===================
-    # Advanced SQL Operations
-    # ===================
-
     @staticmethod
     def rollup(*columns: Union[str, exp.Expression]) -> FunctionExpression:
         """Create a ROLLUP expression for GROUP BY clauses.
@@ -856,7 +794,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # GROUP BY ROLLUP(product, region)
             query = (
                 sql.select("product", "region", sql.sum("sales"))
                 .from_("sales_data")
@@ -879,7 +816,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # GROUP BY CUBE(product, region)
             query = (
                 sql.select("product", "region", sql.sum("sales"))
                 .from_("sales_data")
@@ -902,7 +838,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # GROUP BY GROUPING SETS ((product), (region), ())
             query = (
                 sql.select("product", "region", sql.sum("sales"))
                 .from_("sales_data")
@@ -937,7 +872,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # WHERE id = ANY(subquery)
             subquery = sql.select("user_id").from_("active_users")
             query = (
                 sql.select("*")
@@ -950,11 +884,8 @@ class SQLFactory:
             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 FunctionExpression(exp.Any(this=parsed))
-            return FunctionExpression(exp.Any(this=exp.Literal.string(values)))
+            parsed: exp.Expression = exp.maybe_parse(values)
+            return FunctionExpression(exp.Any(this=parsed))
         return FunctionExpression(exp.Any(this=values))
 
     @staticmethod
@@ -969,7 +900,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # WHERE id <> ANY(subquery)
             subquery = sql.select("user_id").from_("blocked_users")
             query = (
                 sql.select("*")
@@ -980,10 +910,6 @@ class SQLFactory:
         """
         return SQLFactory.any(values)
 
-    # ===================
-    # String Functions
-    # ===================
-
     @staticmethod
     def concat(*expressions: Union[str, exp.Expression]) -> StringExpression:
         """Create a CONCAT expression.
@@ -1036,10 +962,6 @@ class SQLFactory:
         col_expr = exp.column(column) if isinstance(column, str) else column
         return StringExpression(exp.Length(this=col_expr))
 
-    # ===================
-    # Math Functions
-    # ===================
-
     @staticmethod
     def round(column: Union[str, exp.Expression], decimals: int = 0) -> MathExpression:
         """Create a ROUND expression.
@@ -1056,16 +978,12 @@ class SQLFactory:
             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) -> FunctionExpression:
         """Convert a Python value to a SQLGlot literal expression.
 
-        Uses SQLGlot's built-in exp.convert() function for optimal dialect-agnostic
-        literal creation. Handles all Python primitive types correctly:
+        Uses SQLGlot's built-in exp.convert() function for literal creation.
+        Handles all Python primitive types:
         - None -> exp.Null (renders as NULL)
         - bool -> exp.Boolean (renders as TRUE/FALSE or 1/0 based on dialect)
         - int/float -> exp.Literal with is_number=True
@@ -1116,7 +1034,6 @@ class SQLFactory:
         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
@@ -1142,7 +1059,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # DECODE(status, 'A', 'Active', 'I', 'Inactive', 'Unknown')
             sql.decode(
                 "status", "A", "Active", "I", "Inactive", "Unknown"
             )
@@ -1159,7 +1075,6 @@ 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_expression(args[i])
                 break
 
@@ -1239,7 +1154,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # NVL2(salary, 'Has Salary', 'No Salary')
             sql.nvl2("salary", "Has Salary", "No Salary")
             ```
         """
@@ -1247,23 +1161,18 @@ class SQLFactory:
         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 ConversionExpression(exp.Case(ifs=[when_clause], default=null_expr))
 
-    # ===================
-    # Bulk Operations
-    # ===================
-
     @staticmethod
     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
-        we need an INSERT expression with placeholders for executemany().
+        For bulk loading operations like CSV ingestion where
+        an INSERT expression with placeholders for executemany() is needed.
 
         Args:
             table_name: Name of the table to insert into
@@ -1271,27 +1180,24 @@ class SQLFactory:
             placeholder_style: Placeholder style ("?" for SQLite/PostgreSQL, "%s" for MySQL, ":1" for Oracle)
 
         Returns:
-            INSERT expression with proper placeholders for bulk operations
+            INSERT expression with placeholders for bulk operations
 
         Example:
             ```python
             from sqlspec import sql
 
-            # SQLite/PostgreSQL style
+
             insert_expr = sql.bulk_insert("my_table", 3)
-            # Creates: INSERT INTO "my_table" VALUES (?, ?, ?)
 
-            # MySQL style
+
             insert_expr = sql.bulk_insert(
                 "my_table", 3, placeholder_style="%s"
             )
-            # Creates: INSERT INTO "my_table" VALUES (%s, %s, %s)
 
-            # Oracle style
+
             insert_expr = sql.bulk_insert(
                 "my_table", 3, placeholder_style=":1"
             )
-            # Creates: INSERT INTO "my_table" VALUES (:1, :2, :3)
             ```
         """
         return FunctionExpression(
@@ -1318,10 +1224,10 @@ class SQLFactory:
             ```python
             from sqlspec import sql
 
-            # Simple truncate
+
             truncate_sql = sql.truncate_table("my_table").build().sql
 
-            # Truncate with options
+
             truncate_sql = (
                 sql.truncate_table("my_table")
                 .cascade()
@@ -1331,13 +1237,7 @@ class SQLFactory:
             )
             ```
         """
-        builder = Truncate(dialect=self.dialect)
-        builder._table_name = table_name
-        return builder
-
-    # ===================
-    # Case Expressions
-    # ===================
+        return Truncate(table_name, dialect=self.dialect)
 
     @staticmethod
     def case() -> "Case":
@@ -1348,10 +1248,6 @@ class SQLFactory:
         """
         return Case()
 
-    # ===================
-    # Window Functions
-    # ===================
-
     def row_number(
         self,
         partition_by: Optional[Union[str, list[str], exp.Expression]] = None,
@@ -1441,5 +1337,4 @@ class SQLFactory:
         return FunctionExpression(exp.Window(this=func_expr, **over_args))
 
 
-# Create a default SQL factory instance
 sql = SQLFactory()