sqlspec 0.26.0__py3-none-any.whl → 0.28.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/extensions/starlette/__init__.py

@@ -0,0 +1,10 @@
+"""Starlette extension for SQLSpec.
+
+Provides middleware-based session management, automatic transaction handling,
+and connection pooling lifecycle management for Starlette applications.
+"""
+
+from sqlspec.extensions.starlette.extension import SQLSpecPlugin
+from sqlspec.extensions.starlette.middleware import SQLSpecAutocommitMiddleware, SQLSpecManualMiddleware
+
+__all__ = ("SQLSpecAutocommitMiddleware", "SQLSpecManualMiddleware", "SQLSpecPlugin")

sqlspec/extensions/starlette/_state.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from sqlspec.config import DatabaseConfigProtocol
+
+__all__ = ("CommitMode", "SQLSpecConfigState")
+
+CommitMode = Literal["manual", "autocommit", "autocommit_include_redirect"]
+
+
+@dataclass
+class SQLSpecConfigState:
+    """Internal state for each database configuration.
+
+    Tracks all configuration parameters needed for middleware and session management.
+    """
+
+    config: "DatabaseConfigProtocol[Any, Any, Any]"
+    connection_key: str
+    pool_key: str
+    session_key: str
+    commit_mode: CommitMode
+    extra_commit_statuses: "set[int] | None"
+    extra_rollback_statuses: "set[int] | None"

sqlspec/extensions/starlette/_utils.py

@@ -0,0 +1,52 @@
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+    from sqlspec.extensions.starlette._state import SQLSpecConfigState
+
+__all__ = ("get_connection_from_request", "get_or_create_session")
+
+
+def get_connection_from_request(request: "Request", config_state: "SQLSpecConfigState") -> Any:
+    """Get database connection from request state.
+
+    Args:
+        request: Starlette request instance.
+        config_state: Configuration state for the database.
+
+    Returns:
+        Database connection object.
+    """
+    return getattr(request.state, config_state.connection_key)
+
+
+def get_or_create_session(request: "Request", config_state: "SQLSpecConfigState") -> Any:
+    """Get or create database session for request.
+
+    Sessions are cached per request to ensure the same session instance
+    is returned for multiple calls within the same request.
+
+    Args:
+        request: Starlette request instance.
+        config_state: Configuration state for the database.
+
+    Returns:
+        Database session (driver instance).
+    """
+    session_instance_key = f"{config_state.session_key}_instance"
+
+    existing_session = getattr(request.state, session_instance_key, None)
+    if existing_session is not None:
+        return existing_session
+
+    connection = get_connection_from_request(request, config_state)
+
+    session = config_state.config.driver_type(
+        connection=connection,
+        statement_config=config_state.config.statement_config,
+        driver_features=config_state.config.driver_features,
+    )
+
+    setattr(request.state, session_instance_key, session)
+    return session