sqlspec 0.26.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

sqlspec/extensions/litestar/providers.py

@@ -7,7 +7,7 @@ This module contains functions to create dependency providers for services and f
 import datetime
 import inspect
 from collections.abc import Callable
-from typing import Any, Literal, NamedTuple, Optional, TypedDict, Union, cast
+from typing import Any, Literal, NamedTuple, TypedDict, cast
 from uuid import UUID
 
 from litestar.di import Provide
@@ -44,15 +44,15 @@ __all__ = (
     "dep_cache",
 )
 
-DTorNone = Optional[datetime.datetime]
-StringOrNone = Optional[str]
-UuidOrNone = Optional[UUID]
-IntOrNone = Optional[int]
-BooleanOrNone = Optional[bool]
+DTorNone = datetime.datetime | None
+StringOrNone = str | None
+UuidOrNone = UUID | None
+IntOrNone = int | None
+BooleanOrNone = bool | None
 SortOrder = Literal["asc", "desc"]
-SortOrderOrNone = Optional[SortOrder]
-HashableValue = Union[str, int, float, bool, None]
-HashableType = Union[HashableValue, tuple[Any, ...], tuple[tuple[str, Any], ...], tuple[HashableValue, ...]]
+SortOrderOrNone = SortOrder | None
+HashableValue = str | int | float | bool | None
+HashableType = HashableValue | tuple[Any, ...] | tuple[tuple[str, Any], ...] | tuple[HashableValue, ...]
 
 
 class DependencyDefaults:
@@ -79,30 +79,30 @@ class FieldNameType(NamedTuple):
 class FilterConfig(TypedDict):
     """Configuration for generating dynamic filters."""
 
-    id_filter: NotRequired[type[Union[UUID, int, str]]]
+    id_filter: NotRequired[type[UUID | int | str]]
     id_field: NotRequired[str]
     sort_field: NotRequired[str]
     sort_order: NotRequired[SortOrder]
     pagination_type: NotRequired[Literal["limit_offset"]]
     pagination_size: NotRequired[int]
-    search: NotRequired[Union[str, set[str], list[str]]]
+    search: NotRequired[str | set[str] | list[str]]
     search_ignore_case: NotRequired[bool]
     created_at: NotRequired[bool]
     updated_at: NotRequired[bool]
-    not_in_fields: NotRequired[Union[FieldNameType, set[FieldNameType], list[Union[str, FieldNameType]]]]
-    in_fields: NotRequired[Union[FieldNameType, set[FieldNameType], list[Union[str, FieldNameType]]]]
+    not_in_fields: NotRequired[FieldNameType | set[FieldNameType] | list[str | FieldNameType]]
+    in_fields: NotRequired[FieldNameType | set[FieldNameType] | list[str | FieldNameType]]
 
 
 class DependencyCache(metaclass=SingletonMeta):
     """Dependency cache for memoizing dynamically generated dependencies."""
 
     def __init__(self) -> None:
-        self.dependencies: dict[Union[int, str], dict[str, Provide]] = {}
+        self.dependencies: dict[int | str, dict[str, Provide]] = {}
 
-    def add_dependencies(self, key: Union[int, str], dependencies: dict[str, Provide]) -> None:
+    def add_dependencies(self, key: int | str, dependencies: dict[str, Provide]) -> None:
         self.dependencies[key] = dependencies
 
-    def get_dependencies(self, key: Union[int, str]) -> Optional[dict[str, Provide]]:
+    def get_dependencies(self, key: int | str) -> dict[str, Provide] | None:
         return self.dependencies.get(key)
 
 
@@ -169,7 +169,7 @@ def _create_statement_filters(
     if config.get("id_filter", False):
 
         def provide_id_filter(  # pyright: ignore[reportUnknownParameterType]
-            ids: Optional[list[str]] = Parameter(query="ids", default=None, required=False),
+            ids: list[str] | None = Parameter(query="ids", default=None, required=False),
         ) -> InCollectionFilter:  # pyright: ignore[reportMissingTypeArgument]
             return InCollectionFilter(field_name=config.get("id_field", "id"), values=ids)
 
@@ -257,12 +257,12 @@ def _create_statement_filters(
 
             def create_not_in_filter_provider(  # pyright: ignore
                 field_name: FieldNameType,
-            ) -> Callable[..., Optional[NotInCollectionFilter[field_def.type_hint]]]:  # type: ignore
+            ) -> Callable[..., NotInCollectionFilter[field_def.type_hint] | None]:  # type: ignore
                 def provide_not_in_filter(  # pyright: ignore
-                    values: Optional[list[field_name.type_hint]] = Parameter(  # type: ignore
+                    values: list[field_name.type_hint] | None = Parameter(  # type: ignore
                         query=camelize(f"{field_name.name}_not_in"), default=None, required=False
                     ),
-                ) -> Optional[NotInCollectionFilter[field_name.type_hint]]:  # type: ignore
+                ) -> NotInCollectionFilter[field_name.type_hint] | None:  # type: ignore
                     return (
                         NotInCollectionFilter[field_name.type_hint](field_name=field_name.name, values=values)  # type: ignore
                         if values
@@ -282,12 +282,12 @@ def _create_statement_filters(
 
             def create_in_filter_provider(  # pyright: ignore
                 field_name: FieldNameType,
-            ) -> Callable[..., Optional[InCollectionFilter[field_def.type_hint]]]:  # type: ignore # pyright: ignore
+            ) -> Callable[..., InCollectionFilter[field_def.type_hint] | None]:  # type: ignore # pyright: ignore
                 def provide_in_filter(  # pyright: ignore
-                    values: Optional[list[field_name.type_hint]] = Parameter(  # type: ignore # pyright: ignore
+                    values: list[field_name.type_hint] | None = Parameter(  # type: ignore # pyright: ignore
                         query=camelize(f"{field_name.name}_in"), default=None, required=False
                     ),
-                ) -> Optional[InCollectionFilter[field_name.type_hint]]:  # type: ignore # pyright: ignore
+                ) -> InCollectionFilter[field_name.type_hint] | None:  # type: ignore # pyright: ignore
                     return (
                         InCollectionFilter[field_name.type_hint](field_name=field_name.name, values=values)  # type: ignore  # pyright: ignore
                         if values
@@ -415,14 +415,14 @@ def _create_filter_aggregate_function(config: FilterConfig) -> Callable[..., lis
         if updated_filter := kwargs.get("updated_filter"):
             filters.append(updated_filter)
         if (
-            (search_filter := cast("Optional[SearchFilter]", kwargs.get("search_filter")))
+            (search_filter := cast("SearchFilter | None", kwargs.get("search_filter")))
             and search_filter is not None  # pyright: ignore[reportUnnecessaryComparison]
             and search_filter.field_name is not None  # pyright: ignore[reportUnnecessaryComparison]
             and search_filter.value is not None  # pyright: ignore[reportUnnecessaryComparison]
         ):
             filters.append(search_filter)
         if (
-            (order_by := cast("Optional[OrderByFilter]", kwargs.get("order_by_filter")))
+            (order_by := cast("OrderByFilter | None", kwargs.get("order_by_filter")))
             and order_by is not None  # pyright: ignore[reportUnnecessaryComparison]
             and order_by.field_name is not None  # pyright: ignore[reportUnnecessaryComparison]
         ):

sqlspec/extensions/litestar/store.py

@@ -0,0 +1,265 @@
+"""Base session store classes for Litestar integration."""
+
+import re
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any, Final, Generic, TypeVar, cast
+
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+
+ConfigT = TypeVar("ConfigT")
+
+
+logger = get_logger("extensions.litestar.store")
+
+__all__ = ("BaseSQLSpecStore",)
+
+VALID_TABLE_NAME_PATTERN: Final = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+MAX_TABLE_NAME_LENGTH: Final = 63
+
+
+class BaseSQLSpecStore(ABC, Generic[ConfigT]):
+    """Base class for SQLSpec-backed Litestar session stores.
+
+    Implements the litestar.stores.base.Store protocol for server-side session
+    storage using SQLSpec database adapters.
+
+    This abstract base class provides common functionality for all database-specific
+    store implementations including:
+    - Connection management via SQLSpec configs
+    - Session expiration calculation
+    - Table creation utilities
+
+    Subclasses must implement dialect-specific SQL queries.
+
+    Args:
+        config: SQLSpec database configuration with extension_config["litestar"] settings.
+
+    Example:
+        from sqlspec.adapters.asyncpg import AsyncpgConfig
+        from sqlspec.adapters.asyncpg.litestar.store import AsyncpgStore
+
+        config = AsyncpgConfig(
+            pool_config={"dsn": "postgresql://..."},
+            extension_config={"litestar": {"session_table": "my_sessions"}}
+        )
+        store = AsyncpgStore(config)
+        await store.create_table()
+
+    Notes:
+        Configuration is read from config.extension_config["litestar"]:
+        - session_table: Table name (default: "litestar_session")
+    """
+
+    __slots__ = ("_config", "_table_name")
+
+    def __init__(self, config: ConfigT) -> None:
+        """Initialize the session store.
+
+        Args:
+            config: SQLSpec database configuration.
+
+        Notes:
+            Reads table_name from config.extension_config["litestar"]["session_table"].
+            Defaults to "litestar_session" if not specified.
+        """
+        self._config = config
+        self._table_name = self._get_table_name_from_config()
+        self._validate_table_name(self._table_name)
+
+    def _get_table_name_from_config(self) -> str:
+        """Extract table name from config.extension_config.
+
+        Returns:
+            Table name for the session store.
+        """
+        if hasattr(self._config, "extension_config"):
+            extension_config = cast("dict[str, dict[str, Any]]", self._config.extension_config)  # pyright: ignore
+            litestar_config: dict[str, Any] = extension_config.get("litestar", {})
+            return str(litestar_config.get("session_table", "litestar_session"))
+        return "litestar_session"
+
+    @property
+    def config(self) -> ConfigT:
+        """Return the database configuration."""
+        return self._config
+
+    @property
+    def table_name(self) -> str:
+        """Return the session table name."""
+        return self._table_name
+
+    @abstractmethod
+    async def get(self, key: str, renew_for: "int | timedelta | None" = None) -> "bytes | None":
+        """Get a session value by key.
+
+        Args:
+            key: Session ID to retrieve.
+            renew_for: If given and the value had an initial expiry time set, renew the
+                expiry time for ``renew_for`` seconds. If the value has not been set
+                with an expiry time this is a no-op.
+
+        Returns:
+            Session data as bytes if found and not expired, None otherwise.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def set(self, key: str, value: "str | bytes", expires_in: "int | timedelta | None" = None) -> None:
+        """Store a session value.
+
+        Args:
+            key: Session ID.
+            value: Session data (will be converted to bytes if string).
+            expires_in: Time in seconds or timedelta before expiration.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        """Delete a session by key.
+
+        Args:
+            key: Session ID to delete.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_all(self) -> None:
+        """Delete all sessions from the store."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def exists(self, key: str) -> bool:
+        """Check if a session key exists and is not expired.
+
+        Args:
+            key: Session ID to check.
+
+        Returns:
+            True if the session exists and is not expired.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def expires_in(self, key: str) -> "int | None":
+        """Get the time in seconds until the session expires.
+
+        Args:
+            key: Session ID to check.
+
+        Returns:
+            Seconds until expiration, or None if no expiry or key doesn't exist.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_expired(self) -> int:
+        """Delete all expired sessions.
+
+        Returns:
+            Number of sessions deleted.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def create_table(self) -> None:
+        """Create the session table if it doesn't exist."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def _get_create_table_sql(self) -> str:
+        """Get the CREATE TABLE SQL for this database dialect.
+
+        Returns:
+            SQL statement to create the sessions table.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def _get_drop_table_sql(self) -> "list[str]":
+        """Get the DROP TABLE SQL statements for this database dialect.
+
+        Returns:
+            List of SQL statements to drop the table and all indexes.
+            Order matters: drop indexes before table.
+
+        Notes:
+            Should use IF EXISTS or dialect-specific error handling
+            to allow idempotent migrations.
+        """
+        raise NotImplementedError
+
+    async def __aenter__(self) -> "BaseSQLSpecStore":
+        """Enter context manager."""
+        return self
+
+    async def __aexit__(
+        self, exc_type: "type[BaseException] | None", exc_val: "BaseException | None", exc_tb: "TracebackType | None"
+    ) -> None:
+        """Exit context manager."""
+        return
+
+    def _calculate_expires_at(self, expires_in: "int | timedelta | None") -> "datetime | None":
+        """Calculate expiration timestamp from expires_in.
+
+        Args:
+            expires_in: Seconds or timedelta until expiration.
+
+        Returns:
+            UTC datetime of expiration, or None if no expiration.
+        """
+        if expires_in is None:
+            return None
+
+        expires_in_seconds = int(expires_in.total_seconds()) if isinstance(expires_in, timedelta) else expires_in
+
+        if expires_in_seconds <= 0:
+            return None
+
+        return datetime.now(timezone.utc) + timedelta(seconds=expires_in_seconds)
+
+    def _value_to_bytes(self, value: "str | bytes") -> bytes:
+        """Convert value to bytes if needed.
+
+        Args:
+            value: String or bytes value.
+
+        Returns:
+            Value as bytes.
+        """
+        if isinstance(value, str):
+            return value.encode("utf-8")
+        return value
+
+    @staticmethod
+    def _validate_table_name(table_name: str) -> None:
+        """Validate table name for SQL safety.
+
+        Args:
+            table_name: Table name to validate.
+
+        Raises:
+            ValueError: If table name is invalid.
+
+        Notes:
+            - Must start with letter or underscore
+            - Can only contain letters, numbers, and underscores
+            - Maximum length is 63 characters (PostgreSQL limit)
+            - Prevents SQL injection in table names
+        """
+        if not table_name:
+            msg = "Table name cannot be empty"
+            raise ValueError(msg)
+
+        if len(table_name) > MAX_TABLE_NAME_LENGTH:
+            msg = f"Table name too long: {len(table_name)} chars (max {MAX_TABLE_NAME_LENGTH})"
+            raise ValueError(msg)
+
+        if not VALID_TABLE_NAME_PATTERN.match(table_name):
+            msg = f"Invalid table name: {table_name!r}. Must start with letter/underscore and contain only alphanumeric characters and underscores"
+            raise ValueError(msg)

sqlspec/loader.py

@@ -9,7 +9,7 @@ import re
 import time
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Final, Optional, Union
+from typing import TYPE_CHECKING, Any, Final
 from urllib.parse import unquote, urlparse
 
 from sqlspec.core.cache import get_cache, get_cache_config
@@ -95,7 +95,7 @@ class NamedStatement:
 
     __slots__ = ("dialect", "name", "sql", "start_line")
 
-    def __init__(self, name: str, sql: str, dialect: "Optional[str]" = None, start_line: int = 0) -> None:
+    def __init__(self, name: str, sql: str, dialect: "str | None" = None, start_line: int = 0) -> None:
         self.name = name
         self.sql = sql
         self.dialect = dialect
@@ -112,11 +112,7 @@ class SQLFile:
     __slots__ = ("checksum", "content", "loaded_at", "metadata", "path")
 
     def __init__(
-        self,
-        content: str,
-        path: str,
-        metadata: "Optional[dict[str, Any]]" = None,
-        loaded_at: "Optional[datetime]" = None,
+        self, content: str, path: str, metadata: "dict[str, Any] | None" = None, loaded_at: "datetime | None" = None
     ) -> None:
         """Initialize SQLFile.
 
@@ -163,7 +159,7 @@ class SQLFileLoader:
 
     __slots__ = ("_files", "_queries", "_query_to_file", "encoding", "storage_registry")
 
-    def __init__(self, *, encoding: str = "utf-8", storage_registry: "Optional[StorageRegistry]" = None) -> None:
+    def __init__(self, *, encoding: str = "utf-8", storage_registry: "StorageRegistry | None" = None) -> None:
         """Initialize the SQL file loader.
 
         Args:
@@ -188,7 +184,7 @@ class SQLFileLoader:
         """
         raise SQLFileNotFoundError(path)
 
-    def _generate_file_cache_key(self, path: Union[str, Path]) -> str:
+    def _generate_file_cache_key(self, path: str | Path) -> str:
         """Generate cache key for a file path.
 
         Args:
@@ -201,7 +197,7 @@ class SQLFileLoader:
         path_hash = hashlib.md5(path_str.encode(), usedforsecurity=False).hexdigest()
         return f"file:{path_hash[:16]}"
 
-    def _calculate_file_checksum(self, path: Union[str, Path]) -> str:
+    def _calculate_file_checksum(self, path: str | Path) -> str:
         """Calculate checksum for file content validation.
 
         Args:
@@ -218,7 +214,7 @@ class SQLFileLoader:
         except Exception as e:
             raise SQLFileParseError(str(path), str(path), e) from e
 
-    def _is_file_unchanged(self, path: Union[str, Path], cached_file: CachedSQLFile) -> bool:
+    def _is_file_unchanged(self, path: str | Path, cached_file: CachedSQLFile) -> bool:
         """Check if file has changed since caching.
 
         Args:
@@ -235,7 +231,7 @@ class SQLFileLoader:
         else:
             return current_checksum == cached_file.sql_file.checksum
 
-    def _read_file_content(self, path: Union[str, Path]) -> str:
+    def _read_file_content(self, path: str | Path) -> str:
         """Read file content using storage backend.
 
         Args:
@@ -349,7 +345,7 @@ class SQLFileLoader:
 
         return statements
 
-    def load_sql(self, *paths: Union[str, Path]) -> None:
+    def load_sql(self, *paths: str | Path) -> None:
         """Load SQL files and parse named queries.
 
         Args:
@@ -358,43 +354,20 @@ class SQLFileLoader:
         correlation_id = CorrelationContext.get()
         start_time = time.perf_counter()
 
-        logger.info("Loading SQL files", extra={"file_count": len(paths), "correlation_id": correlation_id})
-
-        loaded_count = 0
-        query_count_before = len(self._queries)
-
         try:
             for path in paths:
                 path_str = str(path)
                 if "://" in path_str:
                     self._load_single_file(path, None)
-                    loaded_count += 1
                 else:
                     path_obj = Path(path)
                     if path_obj.is_dir():
-                        loaded_count += self._load_directory(path_obj)
+                        self._load_directory(path_obj)
                     elif path_obj.exists():
                         self._load_single_file(path_obj, None)
-                        loaded_count += 1
                     elif path_obj.suffix:
                         self._raise_file_not_found(str(path))
 
-            duration = time.perf_counter() - start_time
-            new_queries = len(self._queries) - query_count_before
-
-            logger.info(
-                "Loaded %d SQL files with %d new queries in %.3fms",
-                loaded_count,
-                new_queries,
-                duration * 1000,
-                extra={
-                    "files_loaded": loaded_count,
-                    "new_queries": new_queries,
-                    "duration_ms": duration * 1000,
-                    "correlation_id": correlation_id,
-                },
-            )
-
         except Exception as e:
             duration = time.perf_counter() - start_time
             logger.exception(
@@ -408,34 +381,40 @@ class SQLFileLoader:
             )
             raise
 
-    def _load_directory(self, dir_path: Path) -> int:
-        """Load all SQL files from a directory."""
+    def _load_directory(self, dir_path: Path) -> None:
+        """Load all SQL files from a directory.
+
+        Args:
+            dir_path: Directory path to load SQL files from.
+        """
         sql_files = list(dir_path.rglob("*.sql"))
         if not sql_files:
-            return 0
+            return
 
         for file_path in sql_files:
             relative_path = file_path.relative_to(dir_path)
             namespace_parts = relative_path.parent.parts
             self._load_single_file(file_path, ".".join(namespace_parts) if namespace_parts else None)
-        return len(sql_files)
 
-    def _load_single_file(self, file_path: Union[str, Path], namespace: Optional[str]) -> None:
+    def _load_single_file(self, file_path: str | Path, namespace: str | None) -> bool:
         """Load a single SQL file with optional namespace.
 
         Args:
             file_path: Path to the SQL file.
             namespace: Optional namespace prefix for queries.
+
+        Returns:
+            True if file was newly loaded, False if already cached.
         """
         path_str = str(file_path)
 
         if path_str in self._files:
-            return
+            return False
 
         cache_config = get_cache_config()
         if not cache_config.compiled_cache_enabled:
             self._load_file_without_cache(file_path, namespace)
-            return
+            return True
 
         cache_key_str = self._generate_file_cache_key(file_path)
         cache = get_cache()
@@ -459,7 +438,7 @@ class SQLFileLoader:
                         )
                 self._queries[namespaced_name] = statement
                 self._query_to_file[namespaced_name] = path_str
-            return
+            return True
 
         self._load_file_without_cache(file_path, namespace)
 
@@ -476,7 +455,9 @@ class SQLFileLoader:
             cached_file_data = CachedSQLFile(sql_file=sql_file, parsed_statements=file_statements)
             cache.put("file", cache_key_str, cached_file_data)
 
-    def _load_file_without_cache(self, file_path: Union[str, Path], namespace: Optional[str]) -> None:
+        return True
+
+    def _load_file_without_cache(self, file_path: str | Path, namespace: str | None) -> None:
         """Load a single SQL file without using cache.
 
         Args:
@@ -503,7 +484,7 @@ class SQLFileLoader:
             self._queries[namespaced_name] = statement
             self._query_to_file[namespaced_name] = path_str
 
-    def add_named_sql(self, name: str, sql: str, dialect: "Optional[str]" = None) -> None:
+    def add_named_sql(self, name: str, sql: str, dialect: "str | None" = None) -> None:
         """Add a named SQL query directly without loading from a file.
 
         Args:
@@ -529,7 +510,7 @@ class SQLFileLoader:
         self._queries[normalized_name] = statement
         self._query_to_file[normalized_name] = "<directly added>"
 
-    def get_file(self, path: Union[str, Path]) -> "Optional[SQLFile]":
+    def get_file(self, path: str | Path) -> "SQLFile | None":
         """Get a loaded SQLFile object by path.
 
         Args:
@@ -540,7 +521,7 @@ class SQLFileLoader:
         """
         return self._files.get(str(path))
 
-    def get_file_for_query(self, name: str) -> "Optional[SQLFile]":
+    def get_file_for_query(self, name: str) -> "SQLFile | None":
         """Get the SQLFile object containing a query.
 
         Args: