sqlspec 0.7.1__py3-none-any.whl → 0.8.0__py3-none-any.whl

sqlspec/__init__.py

@@ -0,0 +1,15 @@
+from sqlspec import adapters, base, exceptions, extensions, filters, typing, utils
+from sqlspec.__metadata__ import __version__
+from sqlspec.base import SQLSpec
+
+__all__ = (
+    "SQLSpec",
+    "__version__",
+    "adapters",
+    "base",
+    "exceptions",
+    "extensions",
+    "filters",
+    "typing",
+    "utils",
+)

sqlspec/_serialization.py

@@ -60,12 +60,26 @@ __all__ = (
 
 
 def convert_datetime_to_gmt_iso(dt: datetime.datetime) -> str:  # pragma: no cover
-    """Handle datetime serialization for nested timestamps."""
+    """Handle datetime serialization for nested timestamps.
+
+    Args:
+        dt: The datetime to convert.
+
+    Returns:
+        The ISO formatted datetime string.
+    """
     if not dt.tzinfo:
         dt = dt.replace(tzinfo=datetime.timezone.utc)
     return dt.isoformat().replace("+00:00", "Z")
 
 
 def convert_date_to_iso(dt: datetime.date) -> str:  # pragma: no cover
-    """Handle datetime serialization for nested timestamps."""
+    """Handle datetime serialization for nested timestamps.
+
+    Args:
+        dt: The date to convert.
+
+    Returns:
+        The ISO formatted date string.
+    """
     return dt.isoformat()

sqlspec/_typing.py

@@ -29,7 +29,7 @@ T_co = TypeVar("T_co", covariant=True)
 
 try:
     from pydantic import (
-        BaseModel,
+        BaseModel,  # pyright: ignore[reportAssignmentType]
         FailFast,  # pyright: ignore[reportGeneralTypeIssues,reportAssignmentType]
         TypeAdapter,
     )

sqlspec/adapters/adbc/__init__.py

@@ -0,0 +1,7 @@
+from sqlspec.adapters.adbc.config import Adbc
+from sqlspec.adapters.adbc.driver import AdbcDriver
+
+__all__ = (
+    "Adbc",
+    "AdbcDriver",
+)

sqlspec/adapters/adbc/config.py

@@ -1,21 +1,24 @@
 from contextlib import contextmanager
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Optional, Union
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Optional, Union, cast
 
+from adbc_driver_manager.dbapi import Connection
+
+from sqlspec.adapters.adbc.driver import AdbcDriver
 from sqlspec.base import NoPoolSyncConfig
+from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import Empty, EmptyType
+from sqlspec.utils.module_loader import import_string
 
 if TYPE_CHECKING:
     from collections.abc import Generator
-    from typing import Any
 
-    from adbc_driver_manager.dbapi import Connection
 
-__all__ = ("AdbcDatabaseConfig",)
+__all__ = ("Adbc",)
 
 
 @dataclass
-class AdbcDatabaseConfig(NoPoolSyncConfig["Connection"]):
+class Adbc(NoPoolSyncConfig["Connection", "AdbcDriver"]):
     """Configuration for ADBC connections.
 
     This class provides configuration options for ADBC database connections using the
@@ -25,23 +28,163 @@ class AdbcDatabaseConfig(NoPoolSyncConfig["Connection"]):
     uri: "Union[str, EmptyType]" = Empty
     """Database URI"""
     driver_name: "Union[str, EmptyType]" = Empty
-    """Name of the ADBC driver to use"""
+    """Full dotted path to the ADBC driver's connect function (e.g., 'adbc_driver_sqlite.dbapi.connect')"""
     db_kwargs: "Optional[dict[str, Any]]" = None
     """Additional database-specific connection parameters"""
+    conn_kwargs: "Optional[dict[str, Any]]" = None
+    """Additional database-specific connection parameters"""
+    connection_type: "type[Connection]" = field(init=False, default_factory=lambda: Connection)
+    """Type of the connection object"""
+    driver_type: "type[AdbcDriver]" = field(init=False, default_factory=lambda: AdbcDriver)  # type: ignore[type-abstract,unused-ignore]
+    """Type of the driver object"""
+    pool_instance: None = field(init=False, default=None)
+    """No connection pool is used for ADBC connections"""
+    _is_in_memory: bool = field(init=False, default=False)
+    """Flag indicating if the connection is for an in-memory database"""
+
+    def _set_adbc(self) -> str:  # noqa: PLR0912
+        """Identify the driver type based on the URI (if provided) or preset driver name.
+
+        Also sets the `_is_in_memory` flag for specific in-memory URIs.
+
+        Raises:
+            ImproperConfigurationError: If the driver name is not recognized or supported.
+
+        Returns:
+            str: The driver name to be used for the connection.
+        """
+
+        if isinstance(self.driver_name, str):
+            if self.driver_name != "adbc_driver_sqlite.dbapi.connect" and "sqlite" in self.driver_name:
+                self.driver_name = "adbc_driver_sqlite.dbapi.connect"
+            elif self.driver_name != "adbc_driver_duckdb.dbapi.connect" and "duckdb" in self.driver_name:
+                self.driver_name = "adbc_driver_duckdb.dbapi.connect"
+            elif self.driver_name != "adbc_driver_postgresql.dbapi.connect" and "postgres" in self.driver_name:
+                self.driver_name = "adbc_driver_postgresql.dbapi.connect"
+            elif self.driver_name != "adbc_driver_snowflake.dbapi.connect" and "snowflake" in self.driver_name:
+                self.driver_name = "adbc_driver_snowflake.dbapi.connect"
+            elif self.driver_name != "adbc_driver_bigquery.dbapi.connect" and "bigquery" in self.driver_name:
+                self.driver_name = "adbc_driver_bigquery.dbapi.connect"
+            elif self.driver_name != "adbc_driver_flightsql.dbapi.connect" and "flightsql" in self.driver_name:
+                self.driver_name = "adbc_driver_flightsql.dbapi.connect"
+            return self.driver_name
+
+        # If driver_name wasn't explicit, try to determine from URI
+        if isinstance(self.uri, str) and self.uri.startswith("postgresql://"):
+            self.driver_name = "adbc_driver_postgresql.dbapi.connect"
+        elif isinstance(self.uri, str) and self.uri.startswith("sqlite://"):
+            self.driver_name = "adbc_driver_sqlite.dbapi.connect"
+        elif isinstance(self.uri, str) and self.uri.startswith("grpc://"):
+            self.driver_name = "adbc_driver_flightsql.dbapi.connect"
+        elif isinstance(self.uri, str) and self.uri.startswith("snowflake://"):
+            self.driver_name = "adbc_driver_snowflake.dbapi.connect"
+        elif isinstance(self.uri, str) and self.uri.startswith("bigquery://"):
+            self.driver_name = "adbc_driver_bigquery.dbapi.connect"
+        elif isinstance(self.uri, str) and self.uri.startswith("duckdb://"):
+            self.driver_name = "adbc_driver_duckdb.dbapi.connect"
+
+        # Check if we successfully determined a driver name
+        if self.driver_name is Empty or not isinstance(self.driver_name, str):
+            msg = (
+                "Could not determine ADBC driver connect path. Please specify 'driver_name' "
+                "(e.g., 'adbc_driver_sqlite.dbapi.connect') or provide a supported 'uri'. "
+                f"URI: {self.uri}, Driver Name: {self.driver_name}"
+            )
+            raise ImproperConfigurationError(msg)
+        return self.driver_name
 
     @property
-    def connection_params(self) -> "dict[str, Any]":
-        """Return the connection parameters as a dict."""
-        return {
-            k: v
-            for k, v in {"uri": self.uri, "driver": self.driver_name, **(self.db_kwargs or {})}.items()
-            if v is not Empty
-        }
+    def connection_config_dict(self) -> "dict[str, Any]":
+        """Return the connection configuration as a dict.
+
+        Omits the 'uri' key for known in-memory database types.
+
+        Returns:
+            A string keyed dict of config kwargs for the adbc_driver_manager.dbapi.connect function.
+        """
+        config = {}
+        db_kwargs = self.db_kwargs or {}
+        conn_kwargs = self.conn_kwargs or {}
+        if isinstance(self.uri, str) and self.uri.startswith("sqlite://"):
+            db_kwargs["uri"] = self.uri.replace("sqlite://", "")
+        elif isinstance(self.uri, str) and self.uri.startswith("duckdb://"):
+            db_kwargs["path"] = self.uri.replace("duckdb://", "")
+        elif isinstance(self.uri, str):
+            db_kwargs["uri"] = self.uri
+        if isinstance(self.driver_name, str) and self.driver_name.startswith("adbc_driver_bigquery"):
+            config["db_kwargs"] = db_kwargs
+        else:
+            config = db_kwargs
+        if conn_kwargs:
+            config["conn_kwargs"] = conn_kwargs
+        return config
+
+    def _get_connect_func(self) -> "Callable[..., Connection]":
+        self._set_adbc()
+        driver_path = cast("str", self.driver_name)
+        try:
+            connect_func = import_string(driver_path)
+        except ImportError as e:
+            # Check if the error is likely due to missing suffix and try again
+            if ".dbapi.connect" not in driver_path:
+                try:
+                    driver_path += ".dbapi.connect"
+                    connect_func = import_string(driver_path)
+                except ImportError as e2:
+                    msg = f"Failed to import ADBC connect function from '{self.driver_name}' or '{driver_path}'. Is the driver installed and the path correct? Original error: {e} / {e2}"
+                    raise ImproperConfigurationError(msg) from e2
+            else:
+                # Original import failed, and suffix was already present or added
+                msg = f"Failed to import ADBC connect function from '{driver_path}'. Is the driver installed and the path correct? Original error: {e}"
+                raise ImproperConfigurationError(msg) from e
+        if not callable(connect_func):
+            msg = f"The path '{driver_path}' did not resolve to a callable function."
+            raise ImproperConfigurationError(msg)
+        return connect_func  # type: ignore[no-any-return]
+
+    def create_connection(self) -> "Connection":
+        """Create and return a new database connection using the specific driver.
+
+        Returns:
+            A new ADBC connection instance.
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established.
+        """
+        try:
+            connect_func = self._get_connect_func()
+            _config = self.connection_config_dict
+            return connect_func(**_config)
+        except Exception as e:
+            # Include driver name in error message for better context
+            driver_name = self.driver_name if isinstance(self.driver_name, str) else "Unknown/Derived"
+            # Use the potentially modified driver_path from _get_connect_func if available,
+            # otherwise fallback to self.driver_name for the error message.
+            # This requires _get_connect_func to potentially return the used path or store it.
+            # For simplicity now, we stick to self.driver_name in the message.
+            msg = f"Could not configure the ADBC connection using driver path '{driver_name}'. Error: {e!s}"
+            raise ImproperConfigurationError(msg) from e
 
     @contextmanager
     def provide_connection(self, *args: "Any", **kwargs: "Any") -> "Generator[Connection, None, None]":
-        """Create and provide a database connection."""
-        from adbc_driver_manager.dbapi import connect
+        """Create and provide a database connection using the specific driver.
 
-        with connect(**self.connection_params) as connection:
+        Yields:
+            Connection: A database connection instance.
+        """
+
+        connection = self.create_connection()
+        try:
             yield connection
+        finally:
+            connection.close()
+
+    @contextmanager
+    def provide_session(self, *args: Any, **kwargs: Any) -> "Generator[AdbcDriver, None, None]":
+        """Create and provide a database session.
+
+        Yields:
+            An ADBC driver instance with an active connection.
+        """
+        with self.provide_connection(*args, **kwargs) as connection:
+            yield self.driver_type(connection)

sqlspec/adapters/adbc/driver.py

@@ -0,0 +1,333 @@
+import contextlib
+import re
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
+
+from adbc_driver_manager.dbapi import Connection, Cursor
+
+from sqlspec.base import SyncDriverAdapterProtocol, T
+
+if TYPE_CHECKING:
+    from sqlspec.typing import ModelDTOT, StatementParameterType
+
+__all__ = ("AdbcDriver",)
+
+
+# Regex to find :param or %(param)s style placeholders, skipping those inside quotes
+PARAM_REGEX = re.compile(
+    r"""
+    (?P<dquote>"([^"]|\\")*") | # Double-quoted strings
+    (?P<squote>'([^']|\\')*') | # Single-quoted strings
+    : (?P<var_name_colon>[a-zA-Z_][a-zA-Z0-9_]*) | # :var_name
+    % \( (?P<var_name_perc>[a-zA-Z_][a-zA-Z0-9_]*) \) s # %(var_name)s
+    """,
+    re.VERBOSE,
+)
+
+
+class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
+    """ADBC Sync Driver Adapter."""
+
+    connection: Connection
+
+    def __init__(self, connection: "Connection") -> None:
+        """Initialize the ADBC driver adapter."""
+        self.connection = connection
+        # Potentially introspect connection.paramstyle here if needed in the future
+        # For now, assume 'qmark' based on typical ADBC DBAPI behavior
+
+    @staticmethod
+    def _cursor(connection: "Connection", *args: Any, **kwargs: Any) -> "Cursor":
+        return connection.cursor(*args, **kwargs)
+
+    @contextmanager
+    def _with_cursor(self, connection: "Connection") -> Generator["Cursor", None, None]:
+        cursor = self._cursor(connection)
+        try:
+            yield cursor
+        finally:
+            with contextlib.suppress(Exception):
+                cursor.close()  # type: ignore[no-untyped-call]
+
+    def _process_sql_params(
+        self, sql: str, parameters: "Optional[StatementParameterType]" = None
+    ) -> "tuple[str, Optional[Union[tuple[Any, ...], list[Any], dict[str, Any]]]]":
+        """Process SQL query and parameters for DB-API execution.
+
+        Converts named parameters (:name or %(name)s) to positional parameters specified by `self.param_style`
+        if the input parameters are a dictionary.
+
+        Args:
+            sql: The SQL query string.
+            parameters: The parameters for the query (dict, tuple, list, or None).
+
+        Returns:
+            A tuple containing the processed SQL string and the processed parameters
+            (always a tuple or None if the input was a dictionary, otherwise the original type).
+
+        Raises:
+            ValueError: If a named parameter in the SQL is not found in the dictionary
+                        or if a parameter in the dictionary is not used in the SQL.
+        """
+        if not isinstance(parameters, dict) or not parameters:
+            # If parameters are not a dict, or empty dict, assume positional/no params
+            # Let the underlying driver handle tuples/lists directly
+            return self._process_sql_statement(sql), parameters
+
+        processed_sql = ""
+        processed_params_list: list[Any] = []
+        last_end = 0
+        found_params: set[str] = set()
+
+        for match in PARAM_REGEX.finditer(sql):
+            if match.group("dquote") is not None or match.group("squote") is not None:
+                # Skip placeholders within quotes
+                continue
+
+            # Get name from whichever group matched
+            var_name = match.group("var_name_colon") or match.group("var_name_perc")
+
+            if var_name is None:  # Should not happen with the new regex structure
+                continue
+
+            if var_name not in parameters:
+                placeholder = match.group(0)  # Get the full matched placeholder
+                msg = f"Named parameter '{placeholder}' found in SQL but not provided in parameters dictionary."
+                raise ValueError(msg)
+
+            # Append segment before the placeholder
+            processed_sql += sql[last_end : match.start()]
+            # Append the driver's positional placeholder
+            processed_sql += self.param_style
+            processed_params_list.append(parameters[var_name])
+            found_params.add(var_name)
+            last_end = match.end()
+
+        # Append the rest of the SQL string
+        processed_sql += sql[last_end:]
+
+        # Check if all provided parameters were used
+        unused_params = set(parameters.keys()) - found_params
+        if unused_params:
+            msg = f"Parameters provided but not found in SQL: {unused_params}"
+            # Depending on desired strictness, this could be a warning or an error
+            # For now, let's raise an error for clarity
+            raise ValueError(msg)
+
+        return self._process_sql_statement(processed_sql), tuple(processed_params_list)
+
+    def select(
+        self,
+        sql: str,
+        parameters: Optional["StatementParameterType"] = None,
+        /,
+        connection: Optional["Connection"] = None,
+        schema_type: "Optional[type[ModelDTOT]]" = None,
+    ) -> "list[Union[ModelDTOT, dict[str, Any]]]":
+        """Fetch data from the database.
+
+        Returns:
+            List of row data as either model instances or dictionaries.
+        """
+        connection = self._connection(connection)
+        sql, parameters = self._process_sql_params(sql, parameters)
+        with self._with_cursor(connection) as cursor:
+            cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
+            results = cursor.fetchall()  # pyright: ignore
+            if not results:
+                return []
+
+            column_names = [col[0] for col in cursor.description or []]  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+
+            if schema_type is not None:
+                return [cast("ModelDTOT", schema_type(**dict(zip(column_names, row)))) for row in results]  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
+            return [dict(zip(column_names, row)) for row in results]  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
+
+    def select_one(
+        self,
+        sql: str,
+        parameters: Optional["StatementParameterType"] = None,
+        /,
+        connection: Optional["Connection"] = None,
+        schema_type: "Optional[type[ModelDTOT]]" = None,
+    ) -> "Union[ModelDTOT, dict[str, Any]]":
+        """Fetch one row from the database.
+
+        Returns:
+            The first row of the query results.
+        """
+        connection = self._connection(connection)
+        sql, parameters = self._process_sql_params(sql, parameters)
+        with self._with_cursor(connection) as cursor:
+            cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
+            result = cursor.fetchone()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            result = self.check_not_found(result)  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType,reportUnknownArgumentType]
+            column_names = [c[0] for c in cursor.description or []]  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            if schema_type is None:
+                return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType]
+            return schema_type(**dict(zip(column_names, result)))  # type: ignore[return-value]
+
+    def select_one_or_none(
+        self,
+        sql: str,
+        parameters: Optional["StatementParameterType"] = None,
+        /,
+        connection: Optional["Connection"] = None,
+        schema_type: "Optional[type[ModelDTOT]]" = None,
+    ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]":
+        """Fetch one row from the database.
+
+        Returns:
+            The first row of the query results.
+        """
+        connection = self._connection(connection)
+        sql, parameters = self._process_sql_params(sql, parameters)
+        with self._with_cursor(connection) as cursor:
+            cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
+            result = cursor.fetchone()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            if result is None:
+                return None
+            column_names = [c[0] for c in cursor.description or []]  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            if schema_type is None:
+                return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType]
+            return schema_type(**dict(zip(column_names, result)))  # type: ignore[return-value]
+
+    def select_value(
+        self,
+        sql: str,
+        parameters: Optional["StatementParameterType"] = None,
+        /,
+        connection: Optional["Connection"] = None,
+        schema_type: "Optional[type[T]]" = None,
+    ) -> "Union[T, Any]":
+        """Fetch a single value from the database.
+
+        Returns:
+            The first value from the first row of results, or None if no results.
+        """
+        connection = self._connection(connection)
+        sql, parameters = self._process_sql_params(sql, parameters)
+        with self._with_cursor(connection) as cursor:
+            cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
+            result = cursor.fetchone()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            result = self.check_not_found(result)  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType,reportUnknownArgumentType]
+            if schema_type is None:
+                return result[0]  # pyright: ignore[reportUnknownVariableType]
+            return schema_type(result[0])  # type: ignore[call-arg]
+
+    def select_value_or_none(
+        self,
+        sql: str,
+        parameters: Optional["StatementParameterType"] = None,
+        /,
+        connection: Optional["Connection"] = None,
+        schema_type: "Optional[type[T]]" = None,
+    ) -> "Optional[Union[T, Any]]":
+        """Fetch a single value from the database.
+
+        Returns:
+            The first value from the first row of results, or None if no results.
+        """
+        connection = self._connection(connection)
+        sql, parameters = self._process_sql_params(sql, parameters)
+        with self._with_cursor(connection) as cursor:
+            cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
+            result = cursor.fetchone()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            if result is None:
+                return None
+            if schema_type is None:
+                return result[0]  # pyright: ignore[reportUnknownVariableType]
+            return schema_type(result[0])  # type: ignore[call-arg]
+
+    def insert_update_delete(
+        self,
+        sql: str,
+        parameters: Optional["StatementParameterType"] = None,
+        /,
+        connection: Optional["Connection"] = None,
+    ) -> int:
+        """Insert, update, or delete data from the database.
+
+        Returns:
+            Row count affected by the operation.
+        """
+        connection = self._connection(connection)
+        sql, parameters = self._process_sql_params(sql, parameters)
+
+        with self._with_cursor(connection) as cursor:
+            cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
+            return cursor.rowcount if hasattr(cursor, "rowcount") else -1
+
+    def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: Optional["StatementParameterType"] = None,
+        /,
+        connection: Optional["Connection"] = None,
+        schema_type: "Optional[type[ModelDTOT]]" = None,
+    ) -> "Optional[Union[dict[str, Any], ModelDTOT]]":
+        """Insert, update, or delete data from the database and return result.
+
+        Returns:
+            The first row of results.
+        """
+        connection = self._connection(connection)
+        sql, parameters = self._process_sql_params(sql, parameters)
+        column_names: list[str] = []
+
+        with self._with_cursor(connection) as cursor:
+            cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
+            result = cursor.fetchall()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            if len(result) == 0:  # pyright: ignore[reportUnknownArgumentType]
+                return None
+            column_names = [c[0] for c in cursor.description or []]  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            if schema_type is not None:
+                return cast("ModelDTOT", schema_type(**dict(zip(column_names, result[0]))))  # pyright: ignore[reportUnknownArgumentType]
+            return dict(zip(column_names, result[0]))  # pyright: ignore[reportUnknownVariableType,reportUnknownArgumentType]
+
+    def execute_script(
+        self,
+        sql: str,
+        parameters: Optional["StatementParameterType"] = None,
+        /,
+        connection: Optional["Connection"] = None,
+    ) -> str:
+        """Execute a script.
+
+        Returns:
+            Status message for the operation.
+        """
+        connection = self._connection(connection)
+        sql, parameters = self._process_sql_params(sql, parameters)
+
+        with self._with_cursor(connection) as cursor:
+            cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
+            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,
+    ) -> "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)
+        column_names: list[str] = []
+
+        with self._with_cursor(connection) as cursor:
+            cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
+            result = cursor.fetchall()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            if len(result) == 0:  # pyright: ignore[reportUnknownArgumentType]
+                return None
+            column_names = [c[0] for c in cursor.description or []]  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+            if schema_type is not None:
+                return cast("ModelDTOT", schema_type(**dict(zip(column_names, result[0]))))  # pyright: ignore[reportUnknownArgumentType]
+            return dict(zip(column_names, result[0]))  # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType]

sqlspec/adapters/aiosqlite/__init__.py

@@ -1,3 +1,7 @@
-from sqlspec.adapters.aiosqlite.config import AiosqliteConfig
+from sqlspec.adapters.aiosqlite.config import Aiosqlite
+from sqlspec.adapters.aiosqlite.driver import AiosqliteDriver
 
-__all__ = ("AiosqliteConfig",)
+__all__ = (
+    "Aiosqlite",
+    "AiosqliteDriver",
+)