sqlspec 0.9.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

sqlspec/adapters/sqlite/config.py

@@ -1,9 +1,9 @@
+import sqlite3
 from contextlib import contextmanager
 from dataclasses import dataclass, field
-from sqlite3 import Connection
 from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 
-from sqlspec.adapters.sqlite.driver import SqliteDriver
+from sqlspec.adapters.sqlite.driver import SqliteConnection, SqliteDriver
 from sqlspec.base import NoPoolSyncConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import Empty, EmptyType, dataclass_to_dict
@@ -16,7 +16,7 @@ __all__ = ("SqliteConfig",)
 
 
 @dataclass
-class SqliteConfig(NoPoolSyncConfig["Connection", "SqliteDriver"]):
+class SqliteConfig(NoPoolSyncConfig["SqliteConnection", "SqliteDriver"]):
     """Configuration for SQLite database connections.
 
     This class provides configuration options for SQLite database connections, wrapping all parameters
@@ -40,7 +40,7 @@ class SqliteConfig(NoPoolSyncConfig["Connection", "SqliteDriver"]):
     check_same_thread: "Union[bool, EmptyType]" = Empty
     """If True (default), ProgrammingError is raised if the database connection is used by a thread other than the one that created it. If False, the connection may be shared across multiple threads."""
 
-    factory: "Union[type[Connection], EmptyType]" = Empty
+    factory: "Union[type[SqliteConnection], EmptyType]" = Empty
     """A custom Connection class factory. If given, must be a callable that returns a Connection instance."""
 
     cached_statements: "Union[int, EmptyType]" = Empty
@@ -50,7 +50,7 @@ class SqliteConfig(NoPoolSyncConfig["Connection", "SqliteDriver"]):
     """If set to True, database is interpreted as a URI with supported options."""
     driver_type: "type[SqliteDriver]" = field(init=False, default_factory=lambda: SqliteDriver)
     """Type of the driver object"""
-    connection_type: "type[Connection]" = field(init=False, default_factory=lambda: Connection)
+    connection_type: "type[SqliteConnection]" = field(init=False, default_factory=lambda: SqliteConnection)
     """Type of the connection object"""
 
     @property
@@ -61,10 +61,13 @@ class SqliteConfig(NoPoolSyncConfig["Connection", "SqliteDriver"]):
             A string keyed dict of config kwargs for the sqlite3.connect() function.
         """
         return dataclass_to_dict(
-            self, exclude_empty=True, convert_nested=False, exclude={"pool_instance", "driver_type", "connection_type"}
+            self,
+            exclude_empty=True,
+            convert_nested=False,
+            exclude={"pool_instance", "driver_type", "connection_type"},
         )
 
-    def create_connection(self) -> "Connection":
+    def create_connection(self) -> "SqliteConnection":
         """Create and return a new database connection.
 
         Returns:
@@ -73,8 +76,6 @@ class SqliteConfig(NoPoolSyncConfig["Connection", "SqliteDriver"]):
         Raises:
             ImproperConfigurationError: If the connection could not be established.
         """
-        import sqlite3
-
         try:
             return sqlite3.connect(**self.connection_config_dict)  # type: ignore[no-any-return,unused-ignore]
         except Exception as e:
@@ -82,7 +83,7 @@ class SqliteConfig(NoPoolSyncConfig["Connection", "SqliteDriver"]):
             raise ImproperConfigurationError(msg) from e
 
     @contextmanager
-    def provide_connection(self, *args: "Any", **kwargs: "Any") -> "Generator[Connection, None, None]":
+    def provide_connection(self, *args: "Any", **kwargs: "Any") -> "Generator[SqliteConnection, None, None]":
         """Create and provide a database connection.
 
         Yields:
@@ -100,7 +101,7 @@ class SqliteConfig(NoPoolSyncConfig["Connection", "SqliteDriver"]):
         """Create and provide a database connection.
 
         Yields:
-            A DuckDB driver instance.
+            A SQLite driver instance.
 
 
         """

sqlspec/adapters/sqlite/driver.py

@@ -1,48 +1,78 @@
+import sqlite3
 from contextlib import contextmanager
-from sqlite3 import Connection, Cursor
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
+from sqlite3 import Cursor
+from typing import TYPE_CHECKING, Any, Optional, Union, cast, overload
 
-from sqlspec.base import SyncDriverAdapterProtocol, T
+from sqlspec.base import SyncDriverAdapterProtocol
+from sqlspec.mixins import SQLTranslatorMixin
 
 if TYPE_CHECKING:
-    from collections.abc import Generator
+    from collections.abc import Generator, Sequence
 
-    from sqlspec.typing import ModelDTOT, StatementParameterType
+    from sqlspec.typing import ModelDTOT, StatementParameterType, T
 
-__all__ = ("SqliteDriver",)
+__all__ = ("SqliteConnection", "SqliteDriver")
 
+SqliteConnection = sqlite3.Connection
 
-class SqliteDriver(SyncDriverAdapterProtocol["Connection"]):
+
+class SqliteDriver(
+    SQLTranslatorMixin["SqliteConnection"],
+    SyncDriverAdapterProtocol["SqliteConnection"],
+):
     """SQLite Sync Driver Adapter."""
 
-    connection: "Connection"
+    connection: "SqliteConnection"
     dialect: str = "sqlite"
 
-    def __init__(self, connection: "Connection") -> None:
+    def __init__(self, connection: "SqliteConnection") -> None:
         self.connection = connection
 
     @staticmethod
-    def _cursor(connection: "Connection", *args: Any, **kwargs: Any) -> Cursor:
+    def _cursor(connection: "SqliteConnection", *args: Any, **kwargs: Any) -> Cursor:
         return connection.cursor(*args, **kwargs)  # type: ignore[no-any-return]
 
     @contextmanager
-    def _with_cursor(self, connection: "Connection") -> "Generator[Cursor, None, None]":
+    def _with_cursor(self, connection: "SqliteConnection") -> "Generator[Cursor, None, None]":
         cursor = self._cursor(connection)
         try:
             yield cursor
         finally:
             cursor.close()
 
+    # --- Public API Methods --- #
+    @overload
+    def select(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Sequence[dict[str, Any]]": ...
+    @overload
+    def select(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "Sequence[ModelDTOT]": ...
     def select(
         self,
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
         *,
-        connection: Optional["Connection"] = None,
+        connection: Optional["SqliteConnection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
-    ) -> "list[Union[ModelDTOT, dict[str, Any]]]":
+    ) -> "Sequence[Union[ModelDTOT, dict[str, Any]]]":
         """Fetch data from the database.
 
         Returns:
@@ -63,13 +93,35 @@ class SqliteDriver(SyncDriverAdapterProtocol["Connection"]):
                 return [cast("ModelDTOT", schema_type(**dict(zip(column_names, row)))) for row in results]  # pyright: ignore[reportUnknownArgumentType]
             return [dict(zip(column_names, row)) for row in results]  # pyright: ignore[reportUnknownArgumentType]
 
+    @overload
+    def select_one(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+    @overload
+    def select_one(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "ModelDTOT": ...
     def select_one(
         self,
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
         *,
-        connection: Optional["Connection"] = None,
+        connection: Optional["SqliteConnection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
     ) -> "Union[ModelDTOT, dict[str, Any]]":
@@ -92,13 +144,35 @@ class SqliteDriver(SyncDriverAdapterProtocol["Connection"]):
                 return dict(zip(column_names, result))
             return schema_type(**dict(zip(column_names, result)))  # type: ignore[return-value]
 
+    @overload
+    def select_one_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[dict[str, Any]]": ...
+    @overload
+    def select_one_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "Optional[ModelDTOT]": ...
     def select_one_or_none(
         self,
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
         *,
-        connection: Optional["Connection"] = None,
+        connection: Optional["SqliteConnection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]":
@@ -122,13 +196,35 @@ class SqliteDriver(SyncDriverAdapterProtocol["Connection"]):
                 return dict(zip(column_names, result))
             return schema_type(**dict(zip(column_names, result)))  # type: ignore[return-value]
 
+    @overload
+    def select_value(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Any": ...
+    @overload
     def select_value(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
         *,
-        connection: "Optional[Connection]" = None,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "T": ...
+    def select_value(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
     ) -> "Union[T, Any]":
@@ -150,13 +246,35 @@ class SqliteDriver(SyncDriverAdapterProtocol["Connection"]):
                 return result[0]
             return schema_type(result[0])  # type: ignore[call-arg]
 
+    @overload
+    def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[Any]": ...
+    @overload
+    def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "Optional[T]": ...
     def select_value_or_none(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
         *,
-        connection: "Optional[Connection]" = None,
+        connection: "Optional[SqliteConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[T, Any]]":
@@ -185,7 +303,7 @@ class SqliteDriver(SyncDriverAdapterProtocol["Connection"]):
         parameters: Optional["StatementParameterType"] = None,
         /,
         *,
-        connection: Optional["Connection"] = None,
+        connection: Optional["SqliteConnection"] = None,
         **kwargs: Any,
     ) -> int:
         """Insert, update, or delete data from the database.
@@ -203,13 +321,35 @@ class SqliteDriver(SyncDriverAdapterProtocol["Connection"]):
                 cursor.execute(sql, parameters)
             return cursor.rowcount if hasattr(cursor, "rowcount") else -1
 
+    @overload
+    def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+    @overload
+    def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[SqliteConnection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "ModelDTOT": ...
     def insert_update_delete_returning(
         self,
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
         *,
-        connection: Optional["Connection"] = None,
+        connection: Optional["SqliteConnection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[dict[str, Any], ModelDTOT]]":
@@ -253,7 +393,7 @@ class SqliteDriver(SyncDriverAdapterProtocol["Connection"]):
         parameters: Optional["StatementParameterType"] = None,
         /,
         *,
-        connection: Optional["Connection"] = None,
+        connection: Optional["SqliteConnection"] = None,
         **kwargs: Any,
     ) -> str:
         """Execute a script.
@@ -272,34 +412,3 @@ class SqliteDriver(SyncDriverAdapterProtocol["Connection"]):
                 cursor.execute(sql, parameters)
 
         return cast("str", cursor.statusmessage) if hasattr(cursor, "statusmessage") else "DONE"  # pyright: ignore[reportUnknownMemberType,reportAttributeAccessIssue]
-
-    def execute_script_returning(
-        self,
-        sql: str,
-        parameters: Optional["StatementParameterType"] = None,
-        /,
-        *,
-        connection: Optional["Connection"] = None,
-        schema_type: "Optional[type[ModelDTOT]]" = None,
-        **kwargs: Any,
-    ) -> "Optional[Union[dict[str, Any], ModelDTOT]]":
-        """Execute a script and return result.
-
-        Returns:
-            The first row of results.
-        """
-        connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
-
-        with self._with_cursor(connection) as cursor:
-            if not parameters:
-                cursor.execute(sql)  # pyright: ignore[reportUnknownMemberType]
-            else:
-                cursor.execute(sql, parameters)
-            result = cursor.fetchall()
-            if len(result) == 0:
-                return None
-            column_names = [c[0] for c in cursor.description or []]
-            if schema_type is not None:
-                return cast("ModelDTOT", schema_type(**dict(zip(column_names, result[0]))))
-            return dict(zip(column_names, result[0]))