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

sqlspec/adapters/aiosqlite/config.py

@@ -2,7 +2,7 @@
 
 import logging
 from contextlib import asynccontextmanager
-from typing import TYPE_CHECKING, Any, ClassVar, Optional, TypedDict, Union
+from typing import TYPE_CHECKING, Any, ClassVar, TypedDict
 
 from typing_extensions import NotRequired
 
@@ -15,30 +15,31 @@ from sqlspec.adapters.aiosqlite.pool import (
     AiosqlitePoolConnection,
 )
 from sqlspec.config import AsyncDatabaseConfig
+from sqlspec.utils.serializers import from_json, to_json
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncGenerator
+    from collections.abc import AsyncGenerator, Callable
 
     from sqlspec.core.statement import StatementConfig
 
-__all__ = ("AiosqliteConfig", "AiosqliteConnectionParams", "AiosqlitePoolParams")
+__all__ = ("AiosqliteConfig", "AiosqliteConnectionParams", "AiosqliteDriverFeatures", "AiosqlitePoolParams")
 
 logger = logging.getLogger(__name__)
 
 
-class AiosqliteConnectionParams(TypedDict, total=False):
+class AiosqliteConnectionParams(TypedDict):
     """TypedDict for aiosqlite connection parameters."""
 
     database: NotRequired[str]
     timeout: NotRequired[float]
     detect_types: NotRequired[int]
-    isolation_level: NotRequired[Optional[str]]
+    isolation_level: NotRequired[str | None]
     check_same_thread: NotRequired[bool]
     cached_statements: NotRequired[int]
     uri: NotRequired[bool]
 
 
-class AiosqlitePoolParams(AiosqliteConnectionParams, total=False):
+class AiosqlitePoolParams(AiosqliteConnectionParams):
     """TypedDict for aiosqlite pool parameters, inheriting connection parameters."""
 
     pool_size: NotRequired[int]
@@ -48,21 +49,42 @@ class AiosqlitePoolParams(AiosqliteConnectionParams, total=False):
     extra: NotRequired[dict[str, Any]]
 
 
+class AiosqliteDriverFeatures(TypedDict):
+    """Aiosqlite driver feature configuration.
+
+    Controls optional type handling and serialization features for SQLite connections.
+
+    enable_custom_adapters: Enable custom type adapters for JSON/UUID/datetime conversion.
+        Defaults to True for enhanced Python type support.
+        Set to False only if you need pure SQLite behavior without type conversions.
+    json_serializer: Custom JSON serializer function.
+        Defaults to sqlspec.utils.serializers.to_json.
+    json_deserializer: Custom JSON deserializer function.
+        Defaults to sqlspec.utils.serializers.from_json.
+    """
+
+    enable_custom_adapters: NotRequired[bool]
+    json_serializer: "NotRequired[Callable[[Any], str]]"
+    json_deserializer: "NotRequired[Callable[[str], Any]]"
+
+
 class AiosqliteConfig(AsyncDatabaseConfig["AiosqliteConnection", AiosqliteConnectionPool, AiosqliteDriver]):
     """Database configuration for AioSQLite engine."""
 
     driver_type: "ClassVar[type[AiosqliteDriver]]" = AiosqliteDriver
     connection_type: "ClassVar[type[AiosqliteConnection]]" = AiosqliteConnection
+    supports_transactional_ddl: "ClassVar[bool]" = True
 
     def __init__(
         self,
         *,
-        pool_config: "Optional[Union[AiosqlitePoolParams, dict[str, Any]]]" = None,
-        pool_instance: "Optional[AiosqliteConnectionPool]" = None,
-        migration_config: "Optional[dict[str, Any]]" = None,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
-        bind_key: "Optional[str]" = None,
+        pool_config: "AiosqlitePoolParams | dict[str, Any] | None" = None,
+        pool_instance: "AiosqliteConnectionPool | None" = None,
+        migration_config: "dict[str, Any] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "AiosqliteDriverFeatures | dict[str, Any] | None" = None,
+        bind_key: "str | None" = None,
+        extension_config: "dict[str, dict[str, Any]] | None" = None,
     ) -> None:
         """Initialize AioSQLite configuration.
 
@@ -73,20 +95,42 @@ class AiosqliteConfig(AsyncDatabaseConfig["AiosqliteConnection", AiosqliteConnec
             statement_config: Optional statement configuration.
             driver_features: Optional driver feature configuration.
             bind_key: Optional unique identifier for this configuration.
+            extension_config: Extension-specific configuration (e.g., Litestar plugin settings)
         """
         config_dict = dict(pool_config) if pool_config else {}
 
         if "database" not in config_dict or config_dict["database"] == ":memory:":
             config_dict["database"] = "file::memory:?cache=shared"
             config_dict["uri"] = True
+        elif "database" in config_dict:
+            database_path = str(config_dict["database"])
+            if database_path.startswith("file:") and not config_dict.get("uri"):
+                logger.debug(
+                    "Database URI detected (%s) but uri=True not set. "
+                    "Auto-enabling URI mode to prevent physical file creation.",
+                    database_path,
+                )
+                config_dict["uri"] = True
+
+        processed_driver_features: dict[str, Any] = dict(driver_features) if driver_features else {}
+
+        if "enable_custom_adapters" not in processed_driver_features:
+            processed_driver_features["enable_custom_adapters"] = True
+
+        if "json_serializer" not in processed_driver_features:
+            processed_driver_features["json_serializer"] = to_json
+
+        if "json_deserializer" not in processed_driver_features:
+            processed_driver_features["json_deserializer"] = from_json
 
         super().__init__(
             pool_config=config_dict,
             pool_instance=pool_instance,
             migration_config=migration_config,
             statement_config=statement_config or aiosqlite_statement_config,
-            driver_features=driver_features or {},
+            driver_features=processed_driver_features,
             bind_key=bind_key,
+            extension_config=extension_config,
         )
 
     def _get_pool_config_dict(self) -> "dict[str, Any]":
@@ -138,7 +182,7 @@ class AiosqliteConfig(AsyncDatabaseConfig["AiosqliteConnection", AiosqliteConnec
 
     @asynccontextmanager
     async def provide_session(
-        self, *_args: Any, statement_config: "Optional[StatementConfig]" = None, **_kwargs: Any
+        self, *_args: Any, statement_config: "StatementConfig | None" = None, **_kwargs: Any
     ) -> "AsyncGenerator[AiosqliteDriver, None]":
         """Provide an async driver session context manager.
 
@@ -151,7 +195,11 @@ class AiosqliteConfig(AsyncDatabaseConfig["AiosqliteConnection", AiosqliteConnec
             An AiosqliteDriver instance.
         """
         async with self.provide_connection(*_args, **_kwargs) as connection:
-            yield self.driver_type(connection=connection, statement_config=statement_config or self.statement_config)
+            yield self.driver_type(
+                connection=connection,
+                statement_config=statement_config or self.statement_config,
+                driver_features=self.driver_features,
+            )
 
     async def _create_pool(self) -> AiosqliteConnectionPool:
         """Create the connection pool instance.
@@ -165,7 +213,7 @@ class AiosqliteConfig(AsyncDatabaseConfig["AiosqliteConnection", AiosqliteConnec
         idle_timeout = config.pop("idle_timeout", 24 * 60 * 60)
         operation_timeout = config.pop("operation_timeout", 10.0)
 
-        return AiosqliteConnectionPool(
+        pool = AiosqliteConnectionPool(
             connection_parameters=self._get_connection_config_dict(),
             pool_size=pool_size,
             connect_timeout=connect_timeout,
@@ -173,6 +221,28 @@ class AiosqliteConfig(AsyncDatabaseConfig["AiosqliteConnection", AiosqliteConnec
             operation_timeout=operation_timeout,
         )
 
+        if self.driver_features.get("enable_custom_adapters", False):
+            self._register_type_adapters()
+
+        return pool
+
+    def _register_type_adapters(self) -> None:
+        """Register custom type adapters and converters for SQLite.
+
+        Called once during pool creation if enable_custom_adapters is True.
+        Registers JSON serialization handlers if configured.
+
+        Note: aiosqlite uses the same sqlite3 module type registration as the
+        sync adapter, so this shares the implementation.
+        """
+        if self.driver_features.get("enable_custom_adapters", False):
+            from sqlspec.adapters.sqlite._type_handlers import register_type_handlers
+
+            register_type_handlers(
+                json_serializer=self.driver_features.get("json_serializer"),
+                json_deserializer=self.driver_features.get("json_deserializer"),
+            )
+
     async def close_pool(self) -> None:
         """Close the connection pool."""
         if self.pool_instance and not self.pool_instance.is_closed:

sqlspec/adapters/aiosqlite/data_dictionary.py

@@ -1,12 +1,14 @@
 """SQLite-specific data dictionary for metadata queries via aiosqlite."""
 
 import re
-from typing import TYPE_CHECKING, Callable, Optional, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from sqlspec.driver import AsyncDataDictionaryBase, AsyncDriverAdapterBase, VersionInfo
 from sqlspec.utils.logging import get_logger
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from sqlspec.adapters.aiosqlite.driver import AiosqliteDriver
 
 logger = get_logger("adapters.aiosqlite.data_dictionary")
@@ -20,7 +22,7 @@ __all__ = ("AiosqliteAsyncDataDictionary",)
 class AiosqliteAsyncDataDictionary(AsyncDataDictionaryBase):
     """SQLite-specific async data dictionary via aiosqlite."""
 
-    async def get_version(self, driver: AsyncDriverAdapterBase) -> "Optional[VersionInfo]":
+    async def get_version(self, driver: AsyncDriverAdapterBase) -> "VersionInfo | None":
         """Get SQLite database version information.
 
         Args:
@@ -97,6 +99,36 @@ class AiosqliteAsyncDataDictionary(AsyncDataDictionaryBase):
         type_map = {"uuid": "TEXT", "boolean": "INTEGER", "timestamp": "TIMESTAMP", "text": "TEXT", "blob": "BLOB"}
         return type_map.get(type_category, "TEXT")
 
+    async def get_columns(
+        self, driver: AsyncDriverAdapterBase, table: str, schema: "str | None" = None
+    ) -> "list[dict[str, Any]]":
+        """Get column information for a table using SQLite PRAGMA.
+
+        Args:
+            driver: AioSQLite driver instance
+            table: Table name to query columns for
+            schema: Schema name (unused in SQLite)
+
+        Returns:
+            List of column metadata dictionaries with keys:
+                - column_name: Name of the column
+                - data_type: SQLite data type
+                - nullable: Whether column allows NULL
+                - default_value: Default value if any
+        """
+        aiosqlite_driver = cast("AiosqliteDriver", driver)
+        result = await aiosqlite_driver.execute(f"PRAGMA table_info({table})")
+
+        return [
+            {
+                "column_name": row["name"] if isinstance(row, dict) else row[1],
+                "data_type": row["type"] if isinstance(row, dict) else row[2],
+                "nullable": not (row["notnull"] if isinstance(row, dict) else row[3]),
+                "default_value": row["dflt_value"] if isinstance(row, dict) else row[4],
+            }
+            for row in result.data or []
+        ]
+
     def list_available_features(self) -> "list[str]":
         """List available SQLite feature flags.
 

sqlspec/adapters/aiosqlite/driver.py

@@ -4,7 +4,7 @@ import asyncio
 import contextlib
 import datetime
 from decimal import Decimal
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any
 
 import aiosqlite
 
@@ -12,7 +12,18 @@ from sqlspec.core.cache import get_cache_config
 from sqlspec.core.parameters import ParameterStyle, ParameterStyleConfig
 from sqlspec.core.statement import StatementConfig
 from sqlspec.driver import AsyncDriverAdapterBase
-from sqlspec.exceptions import SQLParsingError, SQLSpecError
+from sqlspec.exceptions import (
+    CheckViolationError,
+    DatabaseConnectionError,
+    DataError,
+    ForeignKeyViolationError,
+    IntegrityError,
+    NotNullViolationError,
+    OperationalError,
+    SQLParsingError,
+    SQLSpecError,
+    UniqueViolationError,
+)
 from sqlspec.utils.serializers import to_json
 
 if TYPE_CHECKING:
@@ -26,6 +37,15 @@ if TYPE_CHECKING:
 
 __all__ = ("AiosqliteCursor", "AiosqliteDriver", "AiosqliteExceptionHandler", "aiosqlite_statement_config")
 
+SQLITE_CONSTRAINT_UNIQUE_CODE = 2067
+SQLITE_CONSTRAINT_FOREIGNKEY_CODE = 787
+SQLITE_CONSTRAINT_NOTNULL_CODE = 1811
+SQLITE_CONSTRAINT_CHECK_CODE = 531
+SQLITE_CONSTRAINT_CODE = 19
+SQLITE_CANTOPEN_CODE = 14
+SQLITE_IOERR_CODE = 10
+SQLITE_MISMATCH_CODE = 20
+
 
 aiosqlite_statement_config = StatementConfig(
     dialect="sqlite",
@@ -61,7 +81,7 @@ class AiosqliteCursor:
 
     def __init__(self, connection: "AiosqliteConnection") -> None:
         self.connection = connection
-        self.cursor: Optional[aiosqlite.Cursor] = None
+        self.cursor: aiosqlite.Cursor | None = None
 
     async def __aenter__(self) -> "aiosqlite.Cursor":
         self.cursor = await self.connection.cursor()
@@ -74,7 +94,11 @@ class AiosqliteCursor:
 
 
 class AiosqliteExceptionHandler:
-    """Async context manager for AIOSQLite database exceptions."""
+    """Async context manager for handling aiosqlite database exceptions.
+
+    Maps SQLite extended result codes to specific SQLSpec exceptions
+    for better error handling in application code.
+    """
 
     __slots__ = ()
 
@@ -84,38 +108,103 @@ class AiosqliteExceptionHandler:
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         if exc_type is None:
             return
-        if issubclass(exc_type, aiosqlite.IntegrityError):
-            e = exc_val
-            msg = f"AIOSQLite integrity constraint violation: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, aiosqlite.OperationalError):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "locked" in error_msg:
-                msg = f"AIOSQLite database locked: {e}. Consider enabling WAL mode or reducing concurrency."
-                raise SQLSpecError(msg) from e
-            if "syntax" in error_msg or "malformed" in error_msg:
-                msg = f"AIOSQLite SQL syntax error: {e}"
-                raise SQLParsingError(msg) from e
-            msg = f"AIOSQLite operational error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, aiosqlite.DatabaseError):
-            e = exc_val
-            msg = f"AIOSQLite database error: {e}"
-            raise SQLSpecError(msg) from e
         if issubclass(exc_type, aiosqlite.Error):
-            e = exc_val
-            msg = f"AIOSQLite error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, Exception):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "parse" in error_msg or "syntax" in error_msg:
-                msg = f"SQL parsing failed: {e}"
-                raise SQLParsingError(msg) from e
-            msg = f"Unexpected async database operation error: {e}"
+            self._map_sqlite_exception(exc_val)
+
+    def _map_sqlite_exception(self, e: Any) -> None:
+        """Map SQLite exception to SQLSpec exception.
+
+        Args:
+            e: aiosqlite.Error instance
+
+        Raises:
+            Specific SQLSpec exception based on error code
+        """
+        error_code = getattr(e, "sqlite_errorcode", None)
+        error_name = getattr(e, "sqlite_errorname", None)
+        error_msg = str(e).lower()
+
+        if "locked" in error_msg:
+            msg = f"AIOSQLite database locked: {e}. Consider enabling WAL mode or reducing concurrency."
             raise SQLSpecError(msg) from e
 
+        if not error_code:
+            if "unique constraint" in error_msg:
+                self._raise_unique_violation(e, 0)
+            elif "foreign key constraint" in error_msg:
+                self._raise_foreign_key_violation(e, 0)
+            elif "not null constraint" in error_msg:
+                self._raise_not_null_violation(e, 0)
+            elif "check constraint" in error_msg:
+                self._raise_check_violation(e, 0)
+            elif "syntax" in error_msg:
+                self._raise_parsing_error(e, None)
+            else:
+                self._raise_generic_error(e)
+            return
+
+        if error_code == SQLITE_CONSTRAINT_UNIQUE_CODE or error_name == "SQLITE_CONSTRAINT_UNIQUE":
+            self._raise_unique_violation(e, error_code)
+        elif error_code == SQLITE_CONSTRAINT_FOREIGNKEY_CODE or error_name == "SQLITE_CONSTRAINT_FOREIGNKEY":
+            self._raise_foreign_key_violation(e, error_code)
+        elif error_code == SQLITE_CONSTRAINT_NOTNULL_CODE or error_name == "SQLITE_CONSTRAINT_NOTNULL":
+            self._raise_not_null_violation(e, error_code)
+        elif error_code == SQLITE_CONSTRAINT_CHECK_CODE or error_name == "SQLITE_CONSTRAINT_CHECK":
+            self._raise_check_violation(e, error_code)
+        elif error_code == SQLITE_CONSTRAINT_CODE or error_name == "SQLITE_CONSTRAINT":
+            self._raise_integrity_error(e, error_code)
+        elif error_code == SQLITE_CANTOPEN_CODE or error_name == "SQLITE_CANTOPEN":
+            self._raise_connection_error(e, error_code)
+        elif error_code == SQLITE_IOERR_CODE or error_name == "SQLITE_IOERR":
+            self._raise_operational_error(e, error_code)
+        elif error_code == SQLITE_MISMATCH_CODE or error_name == "SQLITE_MISMATCH":
+            self._raise_data_error(e, error_code)
+        elif error_code == 1 or "syntax" in error_msg:
+            self._raise_parsing_error(e, error_code)
+        else:
+            self._raise_generic_error(e)
+
+    def _raise_unique_violation(self, e: Any, code: int) -> None:
+        msg = f"SQLite unique constraint violation [code {code}]: {e}"
+        raise UniqueViolationError(msg) from e
+
+    def _raise_foreign_key_violation(self, e: Any, code: int) -> None:
+        msg = f"SQLite foreign key constraint violation [code {code}]: {e}"
+        raise ForeignKeyViolationError(msg) from e
+
+    def _raise_not_null_violation(self, e: Any, code: int) -> None:
+        msg = f"SQLite not-null constraint violation [code {code}]: {e}"
+        raise NotNullViolationError(msg) from e
+
+    def _raise_check_violation(self, e: Any, code: int) -> None:
+        msg = f"SQLite check constraint violation [code {code}]: {e}"
+        raise CheckViolationError(msg) from e
+
+    def _raise_integrity_error(self, e: Any, code: int) -> None:
+        msg = f"SQLite integrity constraint violation [code {code}]: {e}"
+        raise IntegrityError(msg) from e
+
+    def _raise_parsing_error(self, e: Any, code: "int | None") -> None:
+        code_str = f"[code {code}]" if code else ""
+        msg = f"SQLite SQL syntax error {code_str}: {e}"
+        raise SQLParsingError(msg) from e
+
+    def _raise_connection_error(self, e: Any, code: int) -> None:
+        msg = f"SQLite connection error [code {code}]: {e}"
+        raise DatabaseConnectionError(msg) from e
+
+    def _raise_operational_error(self, e: Any, code: int) -> None:
+        msg = f"SQLite operational error [code {code}]: {e}"
+        raise OperationalError(msg) from e
+
+    def _raise_data_error(self, e: Any, code: int) -> None:
+        msg = f"SQLite data error [code {code}]: {e}"
+        raise DataError(msg) from e
+
+    def _raise_generic_error(self, e: Any) -> None:
+        msg = f"SQLite database error: {e}"
+        raise SQLSpecError(msg) from e
+
 
 class AiosqliteDriver(AsyncDriverAdapterBase):
     """AIOSQLite driver for async SQLite database operations."""
@@ -126,15 +215,15 @@ class AiosqliteDriver(AsyncDriverAdapterBase):
     def __init__(
         self,
         connection: "AiosqliteConnection",
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "dict[str, Any] | None" = None,
     ) -> None:
         if statement_config is None:
             cache_config = get_cache_config()
             statement_config = aiosqlite_statement_config.replace(enable_caching=cache_config.compiled_cache_enabled)
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
-        self._data_dictionary: Optional[AsyncDataDictionaryBase] = None
+        self._data_dictionary: AsyncDataDictionaryBase | None = None
 
     def with_cursor(self, connection: "AiosqliteConnection") -> "AiosqliteCursor":
         """Create async context manager for AIOSQLite cursor."""
@@ -144,7 +233,7 @@ class AiosqliteDriver(AsyncDriverAdapterBase):
         """Handle AIOSQLite-specific exceptions."""
         return AiosqliteExceptionHandler()
 
-    async def _try_special_handling(self, cursor: "aiosqlite.Cursor", statement: "SQL") -> "Optional[SQLResult]":
+    async def _try_special_handling(self, cursor: "aiosqlite.Cursor", statement: "SQL") -> "SQLResult | None":
         """Hook for AIOSQLite-specific special operations.
 
         Args:
@@ -196,7 +285,7 @@ class AiosqliteDriver(AsyncDriverAdapterBase):
             fetched_data = await cursor.fetchall()
             column_names = [col[0] for col in cursor.description or []]
 
-            data = [dict(zip(column_names, row)) for row in fetched_data]
+            data = [dict(zip(column_names, row, strict=False)) for row in fetched_data]
 
             return self.create_execution_result(
                 cursor, selected_data=data, column_names=column_names, data_row_count=len(data), is_select_result=True

sqlspec/adapters/aiosqlite/litestar/__init__.py

@@ -0,0 +1,5 @@
+"""Litestar integration for AioSQLite adapter."""
+
+from sqlspec.adapters.aiosqlite.litestar.store import AiosqliteStore
+
+__all__ = ("AiosqliteStore",)