sqlspec 0.19.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

sqlspec/builder/_parsing_utils.py

@@ -1,7 +1,7 @@
-"""Centralized parsing utilities for SQLSpec builders.
+"""Parsing utilities for SQL builders.
 
-This module provides common parsing functions to handle complex SQL expressions
-that users might pass as strings to various builder methods.
+Provides common parsing functions to handle SQL expressions
+passed as strings to builder methods.
 """
 
 import contextlib

sqlspec/builder/_select.py

@@ -1,7 +1,7 @@
-"""Safe SQL query builder with validation and parameter binding.
+"""SELECT statement builder.
 
-This module provides a fluent interface for building SQL queries safely,
-with automatic parameter binding and validation.
+Provides a fluent interface for building SQL SELECT queries with
+parameter binding and validation.
 """
 
 import re
@@ -44,9 +44,10 @@ class Select(
     PivotClauseMixin,
     UnpivotClauseMixin,
 ):
-    """Type-safe builder for SELECT queries with schema/model integration.
+    """Builder for SELECT queries.
 
-    This builder provides a fluent, safe interface for constructing SQL SELECT statements.
+    Provides a fluent interface for constructing SQL SELECT statements
+    with parameter binding and validation.
 
     Example:
         >>> class User(BaseModel):

sqlspec/builder/_update.py

@@ -1,7 +1,7 @@
-"""Safe SQL query builder with validation and parameter binding.
+"""UPDATE statement builder.
 
-This module provides a fluent interface for building SQL queries safely,
-with automatic parameter binding and validation.
+Provides a fluent interface for building SQL UPDATE queries with
+parameter binding and validation.
 """
 
 from typing import TYPE_CHECKING, Any, Optional, Union
@@ -36,8 +36,7 @@ class Update(
 ):
     """Builder for UPDATE statements.
 
-    This builder provides a fluent interface for constructing SQL UPDATE statements
-    with automatic parameter binding and validation.
+    Constructs SQL UPDATE statements with parameter binding and validation.
 
     Example:
         ```python

sqlspec/builder/mixins/_cte_and_set_ops.py

@@ -1,4 +1,8 @@
-"""CTE (Common Table Expression) and Set Operations mixins for SQL builders."""
+"""CTE and set operation mixins.
+
+Provides mixins for Common Table Expressions (WITH clause) and
+set operations (UNION, INTERSECT, EXCEPT).
+"""
 
 from typing import Any, Optional, Union
 

sqlspec/builder/mixins/_delete_operations.py

@@ -1,4 +1,8 @@
-"""Delete operation mixins for SQL builders."""
+"""DELETE operation mixins.
+
+Provides mixins for DELETE statement functionality including
+FROM clause specification.
+"""
 
 from typing import Optional
 

sqlspec/builder/mixins/_insert_operations.py

@@ -1,4 +1,8 @@
-"""Insert operation mixins for SQL builders."""
+"""INSERT operation mixins.
+
+Provides mixins for INSERT statement functionality including
+INTO clauses, VALUES clauses, and INSERT FROM SELECT operations.
+"""
 
 from collections.abc import Sequence
 from typing import Any, Optional, TypeVar, Union

sqlspec/builder/mixins/_join_operations.py

@@ -1,3 +1,8 @@
+"""JOIN operation mixins.
+
+Provides mixins for JOIN operations in SELECT statements.
+"""
+
 from typing import TYPE_CHECKING, Any, Optional, Union, cast
 
 from mypy_extensions import trait

sqlspec/builder/mixins/_merge_operations.py

@@ -1,4 +1,8 @@
-"""Merge operation mixins for SQL builders."""
+"""MERGE operation mixins.
+
+Provides mixins for MERGE statement functionality including INTO,
+USING, ON, WHEN MATCHED, and WHEN NOT MATCHED clauses.
+"""
 
 from typing import Any, Optional, Union
 

sqlspec/builder/mixins/_order_limit_operations.py

@@ -1,4 +1,8 @@
-"""Order, Limit, Offset and Returning operations mixins for SQL builders."""
+"""ORDER BY, LIMIT, OFFSET, and RETURNING clause mixins.
+
+Provides mixins for query result ordering, limiting, and result
+returning functionality.
+"""
 
 from typing import TYPE_CHECKING, Optional, Union, cast
 

sqlspec/builder/mixins/_pivot_operations.py

@@ -1,4 +1,7 @@
-"""Pivot and Unpivot operations mixins for SQL builders."""
+"""PIVOT and UNPIVOT operation mixins.
+
+Provides mixins for PIVOT and UNPIVOT operations in SELECT statements.
+"""
 
 from typing import TYPE_CHECKING, Optional, Union, cast
 

sqlspec/builder/mixins/_select_operations.py

@@ -1,4 +1,8 @@
-"""SELECT clause mixins consolidated into a single module."""
+"""SELECT clause mixins.
+
+Provides mixins for SELECT statement functionality including column selection,
+CASE expressions, subqueries, and window functions.
+"""
 
 from typing import TYPE_CHECKING, Any, Optional, Union, cast
 

sqlspec/builder/mixins/_update_operations.py

@@ -1,4 +1,8 @@
-"""Update operation mixins for SQL builders."""
+"""UPDATE operation mixins.
+
+Provides mixins for UPDATE statement functionality including
+table specification, SET clauses, and FROM clauses.
+"""
 
 from collections.abc import Mapping
 from typing import Any, Optional, Union, cast

sqlspec/builder/mixins/_where_clause.py

@@ -1,5 +1,9 @@
 # ruff: noqa: PLR2004
-"""Consolidated WHERE and HAVING clause mixins."""
+"""WHERE and HAVING clause mixins.
+
+Provides mixins for WHERE and HAVING clause functionality with
+parameter binding and various condition operators.
+"""
 
 from typing import TYPE_CHECKING, Any, Optional, Union, cast
 

sqlspec/config.py

@@ -48,7 +48,7 @@ logger = get_logger("config")
 
 
 class LifecycleConfig(TypedDict, total=False):
-    """Lifecycle hooks for all adapters.
+    """Lifecycle hooks for database adapters.
 
     Each hook accepts a list of callables to support multiple handlers.
     """
@@ -67,7 +67,7 @@ class LifecycleConfig(TypedDict, total=False):
 class MigrationConfig(TypedDict, total=False):
     """Configuration options for database migrations.
 
-    All fields are optional with sensible defaults.
+    All fields are optional with default values.
     """
 
     script_location: NotRequired[str]
@@ -160,9 +160,9 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     def get_signature_namespace(self) -> "dict[str, type[Any]]":
         """Get the signature namespace for this database configuration.
 
-        This method returns a dictionary of type names to types that should be
-        registered with Litestar's signature namespace to prevent serialization
-        attempts on database-specific types.
+        Returns a dictionary of type names to types that should be registered
+        with Litestar's signature namespace to prevent serialization attempts
+        on database-specific types.
 
         Returns:
             Dictionary mapping type names to types.
@@ -172,8 +172,8 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     def _initialize_migration_components(self) -> None:
         """Initialize migration loader and commands with necessary imports.
 
-        This method handles the circular import between config and commands
-        by importing at runtime when needed.
+        Handles the circular import between config and commands by importing
+        at runtime when needed.
         """
         from sqlspec.loader import SQLFileLoader
         from sqlspec.migrations.commands import MigrationCommands
@@ -185,7 +185,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         """Get the migration SQL loader and auto-load files if needed.
 
         Returns:
-            The SQLFileLoader instance for migration files.
+            SQLFileLoader instance for migration files.
         """
         # Auto-load migration files from configured migration path if it exists
         migration_config = self.migration_config or {}
@@ -204,14 +204,14 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         """Get the migration commands instance.
 
         Returns:
-            The MigrationCommands instance for this config.
+            MigrationCommands instance for this config.
         """
         return self._migration_commands
 
     def get_migration_loader(self) -> "SQLFileLoader":
         """Get the SQL loader for migration files.
 
-        This provides access to migration SQL files loaded from the configured
+        Provides access to migration SQL files loaded from the configured
         script_location directory. Files are loaded lazily on first access.
 
         Returns:
@@ -269,7 +269,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
             verbose: Whether to show detailed migration history.
 
         Returns:
-            The current migration version or None if no migrations applied.
+            Current migration version or None if no migrations applied.
         """
         commands = self._ensure_migration_commands()
         return commands.current(verbose=verbose)
@@ -301,7 +301,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
 
 
 class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
-    """Base class for a sync database configurations that do not implement a pool."""
+    """Base class for sync database configurations that do not implement a pool."""
 
     __slots__ = ("connection_config",)
     is_async: "ClassVar[bool]" = False
@@ -355,7 +355,7 @@ class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
 
 
 class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
-    """Base class for an async database configurations that do not implement a pool."""
+    """Base class for async database configurations that do not implement a pool."""
 
     __slots__ = ("connection_config",)
     is_async: "ClassVar[bool]" = True
@@ -409,7 +409,7 @@ class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
 
 
 class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
-    """Generic Sync Database Configuration."""
+    """Base class for sync database configurations with connection pooling."""
 
     __slots__ = ("pool_config",)
     is_async: "ClassVar[bool]" = False
@@ -486,7 +486,7 @@ class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
 
 
 class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
-    """Generic Async Database Configuration."""
+    """Base class for async database configurations with connection pooling."""
 
     __slots__ = ("pool_config",)
     is_async: "ClassVar[bool]" = True

sqlspec/core/compiler.py

@@ -17,6 +17,7 @@ from sqlglot.errors import ParseError
 from typing_extensions import Literal
 
 from sqlspec.core.parameters import ParameterProcessor
+from sqlspec.exceptions import SQLSpecError
 from sqlspec.utils.logging import get_logger
 
 if TYPE_CHECKING:
@@ -61,6 +62,8 @@ class CompiledSQL:
     """Compiled SQL result.
 
     Contains the result of SQL compilation with information needed for execution.
+    Immutable container holding compiled SQL text, processed parameters, operation
+    type, and execution metadata.
     """
 
     __slots__ = (
@@ -133,7 +136,9 @@ class CompiledSQL:
 class SQLProcessor:
     """SQL processor with compilation and caching.
 
-    Processes SQL statements with parameter processing and caching.
+    Processes SQL statements by compiling them into executable format with
+    parameter substitution. Includes LRU-style caching for compilation results
+    to avoid re-processing identical statements.
     """
 
     __slots__ = ("_cache", "_cache_hits", "_cache_misses", "_config", "_max_cache_size", "_parameter_processor")
@@ -157,7 +162,7 @@ class SQLProcessor:
 
         Args:
             sql: SQL string for compilation
-            parameters: Parameter values
+            parameters: Parameter values for substitution
             is_many: Whether this is for execute_many operation
 
         Returns:
@@ -261,6 +266,9 @@ class SQLProcessor:
                 supports_many=isinstance(final_params, list) and len(final_params) > 0,
             )
 
+        except SQLSpecError:
+            # Re-raise SQLSpecError (validation errors, parameter mismatches) - these should fail hard
+            raise
         except Exception as e:
             logger.warning("Compilation failed, using fallback: %s", e)
             return CompiledSQL(compiled_sql=sql, execution_parameters=parameters, operation_type="UNKNOWN")
@@ -340,7 +348,7 @@ class SQLProcessor:
         return sql, parameters
 
     def clear_cache(self) -> None:
-        """Clear cache."""
+        """Clear compilation cache and reset statistics."""
         self._cache.clear()
         self._cache_hits = 0
         self._cache_misses = 0

sqlspec/core/filters.py

@@ -196,7 +196,10 @@ class BeforeAfterFilter(StatementFilter):
 
 
 class OnBeforeAfterFilter(StatementFilter):
-    """Data required to filter a query on a ``datetime`` column."""
+    """Filter for inclusive datetime range queries.
+
+    Applies WHERE clauses for on-or-before/on-or-after datetime filtering.
+    """
 
     __slots__ = ("_param_name_on_or_after", "_param_name_on_or_before", "field_name", "on_or_after", "on_or_before")
 
@@ -277,7 +280,7 @@ class OnBeforeAfterFilter(StatementFilter):
 
 
 class InAnyFilter(StatementFilter, ABC, Generic[T]):
-    """Subclass for methods that have a `prefer_any` attribute."""
+    """Base class for collection-based filters that support ANY operations."""
 
     __slots__ = ()
 
@@ -346,7 +349,10 @@ class InCollectionFilter(InAnyFilter[T]):
 
 
 class NotInCollectionFilter(InAnyFilter[T]):
-    """Data required to construct a ``WHERE ... NOT IN (...)`` clause."""
+    """Filter for NOT IN clause queries.
+
+    Constructs WHERE ... NOT IN (...) clauses.
+    """
 
     __slots__ = ("_param_names", "field_name", "values")
 
@@ -401,7 +407,10 @@ class NotInCollectionFilter(InAnyFilter[T]):
 
 
 class AnyCollectionFilter(InAnyFilter[T]):
-    """Data required to construct a ``WHERE column_name = ANY (array_expression)`` clause."""
+    """Filter for PostgreSQL-style ANY clause queries.
+
+    Constructs WHERE column_name = ANY (array_expression) clauses.
+    """
 
     __slots__ = ("_param_names", "field_name", "values")
 
@@ -460,7 +469,10 @@ class AnyCollectionFilter(InAnyFilter[T]):
 
 
 class NotAnyCollectionFilter(InAnyFilter[T]):
-    """Data required to construct a ``WHERE NOT (column_name = ANY (array_expression))`` clause."""
+    """Filter for PostgreSQL-style NOT ANY clause queries.
+
+    Constructs WHERE NOT (column_name = ANY (array_expression)) clauses.
+    """
 
     __slots__ = ("_param_names", "field_name", "values")
 
@@ -514,7 +526,7 @@ class NotAnyCollectionFilter(InAnyFilter[T]):
 
 
 class PaginationFilter(StatementFilter, ABC):
-    """Subclass for methods that function as a pagination type."""
+    """Base class for pagination-related filters."""
 
     __slots__ = ()
 
@@ -524,7 +536,10 @@ class PaginationFilter(StatementFilter, ABC):
 
 
 class LimitOffsetFilter(PaginationFilter):
-    """Data required to add limit/offset filtering to a query."""
+    """Filter for LIMIT and OFFSET clauses.
+
+    Adds pagination support through LIMIT/OFFSET SQL clauses.
+    """
 
     __slots__ = ("_limit_param_name", "_offset_param_name", "limit", "offset")
 
@@ -576,7 +591,10 @@ class LimitOffsetFilter(PaginationFilter):
 
 
 class OrderByFilter(StatementFilter):
-    """Data required to construct a ``ORDER BY ...`` clause."""
+    """Filter for ORDER BY clauses.
+
+    Adds sorting capability to SQL queries.
+    """
 
     __slots__ = ("field_name", "sort_order")
 
@@ -694,7 +712,10 @@ class SearchFilter(StatementFilter):
 
 
 class NotInSearchFilter(SearchFilter):
-    """Data required to construct a ``WHERE field_name NOT LIKE '%' || :value || '%'`` clause."""
+    """Filter for negated text search queries.
+
+    Constructs WHERE field_name NOT LIKE '%value%' clauses.
+    """
 
     __slots__ = ()