sqlspec 0.10.1__py3-none-any.whl → 0.11.1__py3-none-any.whl

sqlspec/base.py

@@ -21,11 +21,13 @@ from typing import (
 from sqlspec.exceptions import NotFoundError
 from sqlspec.statement import SQLStatement
 from sqlspec.typing import ConnectionT, ModelDTOT, PoolT, StatementParameterType, T
-from sqlspec.utils.sync_tools import maybe_async_
+from sqlspec.utils.sync_tools import ensure_async_
 
 if TYPE_CHECKING:
     from contextlib import AbstractAsyncContextManager, AbstractContextManager
 
+    from sqlspec.filters import StatementFilter
+
 
 __all__ = (
     "AsyncDatabaseConfig",
@@ -206,7 +208,7 @@ class SQLSpec:
         for config in self._configs.values():
             if config.support_connection_pooling and config.pool_instance is not None:
                 with contextlib.suppress(Exception):
-                    maybe_async_(config.close_pool)()
+                    ensure_async_(config.close_pool)()
 
     @overload
     def add_config(self, config: "SyncConfigT") -> "type[SyncConfigT]": ...
@@ -533,22 +535,33 @@ class CommonDriverAttributes(Generic[ConnectionT]):
         return item_or_none
 
     def _process_sql_params(
-        self, sql: str, parameters: "Optional[StatementParameterType]" = None, /, **kwargs: Any
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        *filters: "StatementFilter",
+        **kwargs: Any,
     ) -> "tuple[str, Optional[Union[tuple[Any, ...], list[Any], dict[str, Any]]]]":
         """Process SQL query and parameters using SQLStatement for validation and formatting.
 
         Args:
             sql: The SQL query string.
             parameters: Parameters for the query.
+            *filters: Statement filters to apply.
             **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
         Returns:
             A tuple containing the processed SQL query and parameters.
         """
         # Instantiate SQLStatement with parameters and kwargs for internal merging
-        stmt = SQLStatement(sql=sql, parameters=parameters, dialect=self.dialect, kwargs=kwargs or None)
+        stmt = SQLStatement(sql=sql, parameters=parameters, kwargs=kwargs or None)
+
+        # Apply all statement filters
+        for filter_obj in filters:
+            stmt = stmt.apply_filter(filter_obj)
+
         # Process uses the merged parameters internally
-        return stmt.process()
+        processed = stmt.process()
+        return processed[0], processed[1]  # Return only the SQL and parameters, discard the third element
 
 
 class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generic[ConnectionT]):
@@ -563,8 +576,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -576,8 +588,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -588,8 +599,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: Optional[type[ModelDTOT]] = None,
         **kwargs: Any,
@@ -601,8 +611,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -614,8 +623,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -626,8 +634,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: Optional[ConnectionT] = None,
         schema_type: Optional[type[ModelDTOT]] = None,
         **kwargs: Any,
@@ -639,8 +646,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -652,8 +658,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -664,8 +669,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: Optional[ConnectionT] = None,
         schema_type: Optional[type[ModelDTOT]] = None,
         **kwargs: Any,
@@ -677,8 +681,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -690,8 +693,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -702,8 +704,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: Optional[ConnectionT] = None,
         schema_type: Optional[type[T]] = None,
         **kwargs: Any,
@@ -715,8 +716,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -728,8 +728,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -740,8 +739,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: Optional[ConnectionT] = None,
         schema_type: Optional[type[T]] = None,
         **kwargs: Any,
@@ -752,8 +750,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: Optional[ConnectionT] = None,
         **kwargs: Any,
     ) -> int: ...
@@ -764,8 +761,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -777,8 +773,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -789,8 +784,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: Optional[ConnectionT] = None,
         schema_type: Optional[type[ModelDTOT]] = None,
         **kwargs: Any,
@@ -801,8 +795,6 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
-        /,
-        *,
         connection: Optional[ConnectionT] = None,
         **kwargs: Any,
     ) -> str: ...
@@ -820,8 +812,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -833,8 +824,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -845,8 +835,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -858,8 +847,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -871,8 +859,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -883,8 +870,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -896,8 +882,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -909,8 +894,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -921,8 +905,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -934,8 +917,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -947,8 +929,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -959,8 +940,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
@@ -972,8 +952,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -985,8 +964,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -997,8 +975,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
@@ -1009,8 +986,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         **kwargs: Any,
     ) -> int: ...
@@ -1021,8 +997,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -1034,8 +1009,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -1046,8 +1020,7 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[ConnectionT]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -1058,8 +1031,6 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Gener
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
         connection: "Optional[ConnectionT]" = None,
         **kwargs: Any,
     ) -> str: ...

sqlspec/extensions/litestar/__init__.py

@@ -1,19 +1,10 @@
+from sqlspec.extensions.litestar import handlers, providers
 from sqlspec.extensions.litestar.config import DatabaseConfig
-from sqlspec.extensions.litestar.handlers import (
-    autocommit_handler_maker,
-    connection_provider_maker,
-    lifespan_handler_maker,
-    manual_handler_maker,
-    pool_provider_maker,
-)
 from sqlspec.extensions.litestar.plugin import SQLSpec
 
 __all__ = (
     "DatabaseConfig",
     "SQLSpec",
-    "autocommit_handler_maker",
-    "connection_provider_maker",
-    "lifespan_handler_maker",
-    "manual_handler_maker",
-    "pool_provider_maker",
+    "handlers",
+    "providers",
 )

sqlspec/extensions/litestar/config.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Callable, Literal, Optional, Union
+from typing import TYPE_CHECKING, Any, Callable, Literal, Optional, Union
 
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.extensions.litestar.handlers import (
@@ -12,7 +12,7 @@ from sqlspec.extensions.litestar.handlers import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Awaitable
+    from collections.abc import AsyncGenerator, Awaitable
     from contextlib import AbstractAsyncContextManager
 
     from litestar import Litestar
@@ -29,6 +29,15 @@ DEFAULT_CONNECTION_KEY = "db_connection"
 DEFAULT_POOL_KEY = "db_pool"
 DEFAULT_SESSION_KEY = "db_session"
 
+__all__ = (
+    "DEFAULT_COMMIT_MODE",
+    "DEFAULT_CONNECTION_KEY",
+    "DEFAULT_POOL_KEY",
+    "DEFAULT_SESSION_KEY",
+    "CommitMode",
+    "DatabaseConfig",
+)
+
 
 @dataclass
 class DatabaseConfig:
@@ -39,9 +48,11 @@ class DatabaseConfig:
     commit_mode: "CommitMode" = field(default=DEFAULT_COMMIT_MODE)
     extra_commit_statuses: "Optional[set[int]]" = field(default=None)
     extra_rollback_statuses: "Optional[set[int]]" = field(default=None)
-    connection_provider: "Callable[[State,Scope], Awaitable[ConnectionT]]" = field(init=False, repr=False, hash=False)  # pyright: ignore[reportGeneralTypeIssues]
+    connection_provider: "Callable[[State, Scope], AsyncGenerator[ConnectionT, None]]" = field(  # pyright: ignore[reportGeneralTypeIssues]
+        init=False, repr=False, hash=False
+    )
     pool_provider: "Callable[[State,Scope], Awaitable[PoolT]]" = field(init=False, repr=False, hash=False)  # pyright: ignore[reportGeneralTypeIssues]
-    session_provider: "Callable[[State,Scope], Awaitable[DriverT]]" = field(init=False, repr=False, hash=False)  # pyright: ignore[reportGeneralTypeIssues]
+    session_provider: "Callable[[Any], AsyncGenerator[DriverT, None]]" = field(init=False, repr=False, hash=False)  # pyright: ignore[reportGeneralTypeIssues]
     before_send_handler: "BeforeMessageSendHookHandler" = field(init=False, repr=False, hash=False)
     lifespan_handler: "Callable[[Litestar], AbstractAsyncContextManager[None]]" = field(
         init=False,
@@ -74,6 +85,10 @@ class DatabaseConfig:
             msg = f"Invalid commit mode: {self.commit_mode}"  # type: ignore[unreachable]
             raise ImproperConfigurationError(detail=msg)
         self.lifespan_handler = lifespan_handler_maker(config=self.config, pool_key=self.pool_key)
-        self.connection_provider = connection_provider_maker(connection_key=self.connection_key, config=self.config)
-        self.pool_provider = pool_provider_maker(pool_key=self.pool_key, config=self.config)
-        self.session_provider = session_provider_maker(session_key=self.session_key, config=self.config)
+        self.connection_provider = connection_provider_maker(
+            connection_key=self.connection_key, pool_key=self.pool_key, config=self.config
+        )
+        self.pool_provider = pool_provider_maker(config=self.config, pool_key=self.pool_key)
+        self.session_provider = session_provider_maker(
+            config=self.config, connection_dependency_key=self.connection_key
+        )