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

sqlspec/driver/_common.py

@@ -13,6 +13,7 @@ from sqlspec.core.cache import CachedStatement, get_cache, get_cache_config
 from sqlspec.core.splitter import split_sql_script
 from sqlspec.exceptions import ImproperConfigurationError, NotFoundError
 from sqlspec.utils.logging import get_logger
+from sqlspec.utils.type_guards import is_statement_filter
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -414,48 +415,82 @@ class CommonDriverAttributesMixin:
         """
         kwargs = kwargs or {}
 
+        filters: list[StatementFilter] = []
+        data_parameters: list[StatementParameters] = []
+
+        for param in parameters:
+            if is_statement_filter(param):
+                filters.append(param)
+            else:
+                data_parameters.append(param)
+
         if isinstance(statement, QueryBuilder):
             sql_statement = statement.to_statement(statement_config)
-            if parameters or kwargs:
+            if data_parameters or kwargs:
                 merged_parameters = (
-                    (*sql_statement.positional_parameters, *parameters)
-                    if parameters
+                    (*sql_statement.positional_parameters, *tuple(data_parameters))
+                    if data_parameters
                     else sql_statement.positional_parameters
                 )
-                return SQL(sql_statement.sql, *merged_parameters, statement_config=statement_config, **kwargs)
+                sql_statement = SQL(sql_statement.sql, *merged_parameters, statement_config=statement_config, **kwargs)
+
+            for filter_obj in filters:
+                sql_statement = filter_obj.append_to_statement(sql_statement)
+
             return sql_statement
+
         if isinstance(statement, SQL):
-            if parameters or kwargs:
+            sql_statement = statement
+
+            if data_parameters or kwargs:
                 merged_parameters = (
-                    (*statement.positional_parameters, *parameters) if parameters else statement.positional_parameters
+                    (*sql_statement.positional_parameters, *tuple(data_parameters))
+                    if data_parameters
+                    else sql_statement.positional_parameters
                 )
-                return SQL(statement.sql, *merged_parameters, statement_config=statement_config, **kwargs)
-            needs_rebuild = False
-
-            if statement_config.dialect and (
-                not statement.statement_config.dialect or statement.statement_config.dialect != statement_config.dialect
-            ):
-                needs_rebuild = True
+                sql_statement = SQL(sql_statement.sql, *merged_parameters, statement_config=statement_config, **kwargs)
+            else:
+                needs_rebuild = False
+
+                if statement_config.dialect and (
+                    not sql_statement.statement_config.dialect
+                    or sql_statement.statement_config.dialect != statement_config.dialect
+                ):
+                    needs_rebuild = True
+
+                if (
+                    sql_statement.statement_config.parameter_config.default_execution_parameter_style
+                    != statement_config.parameter_config.default_execution_parameter_style
+                ):
+                    needs_rebuild = True
+
+                if needs_rebuild:
+                    sql_text = sql_statement.raw_sql or sql_statement.sql
+
+                    if sql_statement.is_many and sql_statement.parameters:
+                        sql_statement = SQL(
+                            sql_text, sql_statement.parameters, statement_config=statement_config, is_many=True
+                        )
+                    elif sql_statement.named_parameters:
+                        sql_statement = SQL(
+                            sql_text, statement_config=statement_config, **sql_statement.named_parameters
+                        )
+                    else:
+                        sql_statement = SQL(
+                            sql_text, *sql_statement.positional_parameters, statement_config=statement_config
+                        )
+
+            for filter_obj in filters:
+                sql_statement = filter_obj.append_to_statement(sql_statement)
 
-            if (
-                statement.statement_config.parameter_config.default_execution_parameter_style
-                != statement_config.parameter_config.default_execution_parameter_style
-            ):
-                needs_rebuild = True
+            return sql_statement
 
-            if needs_rebuild:
-                sql_text = statement.raw_sql or statement.sql
+        sql_statement = SQL(statement, *tuple(data_parameters), statement_config=statement_config, **kwargs)
 
-                if statement.is_many and statement.parameters:
-                    new_sql = SQL(sql_text, statement.parameters, statement_config=statement_config, is_many=True)
-                elif statement.named_parameters:
-                    new_sql = SQL(sql_text, statement_config=statement_config, **statement.named_parameters)
-                else:
-                    new_sql = SQL(sql_text, *statement.positional_parameters, statement_config=statement_config)
+        for filter_obj in filters:
+            sql_statement = filter_obj.append_to_statement(sql_statement)
 
-                return new_sql
-            return statement
-        return SQL(statement, *parameters, statement_config=statement_config, **kwargs)
+        return sql_statement
 
     def split_script_statements(
         self, script: str, statement_config: "StatementConfig", strip_trailing_semicolon: bool = False

sqlspec/driver/_sync.py

@@ -4,6 +4,7 @@ from abc import abstractmethod
 from typing import TYPE_CHECKING, Any, Final, TypeVar, overload
 
 from sqlspec.core import SQL
+from sqlspec.core.result import create_arrow_result
 from sqlspec.driver._common import (
     CommonDriverAttributesMixin,
     DataDictionaryMixin,
@@ -12,7 +13,10 @@ from sqlspec.driver._common import (
     handle_single_row_error,
 )
 from sqlspec.driver.mixins import SQLTranslatorMixin
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.utils.arrow_helpers import convert_dict_to_arrow
 from sqlspec.utils.logging import get_logger
+from sqlspec.utils.module_loader import ensure_pyarrow
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -341,6 +345,97 @@ class SyncDriverAdapterBase(CommonDriverAttributesMixin, SQLTranslatorMixin):
         result = self.execute(statement, *parameters, statement_config=statement_config, **kwargs)
         return result.get_data(schema_type=schema_type)
 
+    def select_to_arrow(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        statement_config: "StatementConfig | None" = None,
+        return_format: str = "table",
+        native_only: bool = False,
+        batch_size: int | None = None,
+        arrow_schema: Any = None,
+        **kwargs: Any,
+    ) -> "Any":
+        """Execute query and return results as Apache Arrow format.
+
+        This base implementation uses the conversion path: execute() → dict → Arrow.
+        Adapters with native Arrow support (ADBC, DuckDB, BigQuery) override this
+        method to use zero-copy native paths for 5-10x performance improvement.
+
+        Args:
+            statement: SQL query string, Statement, or QueryBuilder
+            *parameters: Query parameters (same format as execute()/select())
+            statement_config: Optional statement configuration override
+            return_format: "table" for pyarrow.Table (default), "reader" for RecordBatchReader,
+                         "batches" for iterator of RecordBatches
+            native_only: If True, raise error if native Arrow unavailable (default: False)
+            batch_size: Rows per batch for "batches" format (default: None = all rows)
+            arrow_schema: Optional pyarrow.Schema for type casting
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            ArrowResult containing pyarrow.Table, RecordBatchReader, or RecordBatches
+
+        Raises:
+            MissingDependencyError: If pyarrow not installed
+            ImproperConfigurationError: If native_only=True and adapter doesn't support native Arrow
+            SQLExecutionError: If query execution fails
+
+        Examples:
+            >>> result = driver.select_to_arrow(
+            ...     "SELECT * FROM users WHERE age > ?", 18
+            ... )
+            >>> df = result.to_pandas()
+            >>> print(df.head())
+
+            >>> # Force native Arrow path (raises error if unavailable)
+            >>> result = driver.select_to_arrow(
+            ...     "SELECT * FROM users", native_only=True
+            ... )
+        """
+        # Check pyarrow is available
+        ensure_pyarrow()
+
+        # Check if native_only requested but not supported
+        if native_only:
+            msg = (
+                f"Adapter '{self.__class__.__name__}' does not support native Arrow results. "
+                f"Use native_only=False to allow conversion path, or switch to an adapter "
+                f"with native Arrow support (ADBC, DuckDB, BigQuery)."
+            )
+            raise ImproperConfigurationError(msg)
+
+        # Execute query using standard path
+        result = self.execute(statement, *parameters, statement_config=statement_config, **kwargs)
+
+        # Convert dict results to Arrow
+        arrow_data = convert_dict_to_arrow(
+            result.data,
+            return_format=return_format,  # type: ignore[arg-type]
+            batch_size=batch_size,
+        )
+
+        # Apply schema casting if requested
+        if arrow_schema is not None:
+            import pyarrow as pa
+
+            if not isinstance(arrow_schema, pa.Schema):
+                msg = f"arrow_schema must be a pyarrow.Schema, got {type(arrow_schema).__name__}"
+                raise TypeError(msg)
+
+            arrow_data = arrow_data.cast(arrow_schema)
+
+        # Create ArrowResult
+        return create_arrow_result(
+            statement=result.statement,
+            data=arrow_data,
+            rows_affected=result.rows_affected,
+            last_inserted_id=result.last_inserted_id,
+            execution_time=result.execution_time,
+            metadata=result.metadata,
+        )
+
     def select_value(
         self,
         statement: "Statement | QueryBuilder",

sqlspec/extensions/adk/migrations/0001_create_adk_tables.py

@@ -114,8 +114,8 @@ async def up(context: "MigrationContext | None" = None) -> "list[str]":
     store_instance = store_class(config=context.config)
 
     return [
-        store_instance._get_create_sessions_table_sql(),  # pyright: ignore[reportPrivateUsage]
-        store_instance._get_create_events_table_sql(),  # pyright: ignore[reportPrivateUsage]
+        await store_instance._get_create_sessions_table_sql(),  # pyright: ignore[reportPrivateUsage]
+        await store_instance._get_create_events_table_sql(),  # pyright: ignore[reportPrivateUsage]
     ]
 
 

sqlspec/extensions/adk/service.py

@@ -119,12 +119,12 @@ class SQLSpecSessionService(BaseSessionService):
 
         return record_to_session(record, events)
 
-    async def list_sessions(self, *, app_name: str, user_id: str) -> "ListSessionsResponse":
-        """List all sessions for an app and user.
+    async def list_sessions(self, *, app_name: str, user_id: str | None = None) -> "ListSessionsResponse":
+        """List all sessions for an app, optionally filtered by user.
 
         Args:
             app_name: Name of the application.
-            user_id: ID of the user.
+            user_id: ID of the user. If None, all sessions for the app are listed.
 
         Returns:
             Response containing list of sessions (without events).

sqlspec/extensions/adk/store.py

@@ -219,12 +219,12 @@ class BaseAsyncADKStore(ABC, Generic[ConfigT]):
         raise NotImplementedError
 
     @abstractmethod
-    async def list_sessions(self, app_name: str, user_id: str) -> "list[SessionRecord]":
-        """List all sessions for an app and user.
+    async def list_sessions(self, app_name: str, user_id: "str | None" = None) -> "list[SessionRecord]":
+        """List all sessions for an app, optionally filtered by user.
 
         Args:
             app_name: Name of the application.
-            user_id: ID of the user.
+            user_id: ID of the user. If None, returns all sessions for the app.
 
         Returns:
             List of session records.
@@ -271,7 +271,7 @@ class BaseAsyncADKStore(ABC, Generic[ConfigT]):
         raise NotImplementedError
 
     @abstractmethod
-    def _get_create_sessions_table_sql(self) -> str:
+    async def _get_create_sessions_table_sql(self) -> str:
         """Get the CREATE TABLE SQL for the sessions table.
 
         Returns:
@@ -280,7 +280,7 @@ class BaseAsyncADKStore(ABC, Generic[ConfigT]):
         raise NotImplementedError
 
     @abstractmethod
-    def _get_create_events_table_sql(self) -> str:
+    async def _get_create_events_table_sql(self) -> str:
         """Get the CREATE TABLE SQL for the events table.
 
         Returns:
@@ -440,12 +440,12 @@ class BaseSyncADKStore(ABC, Generic[ConfigT]):
         raise NotImplementedError
 
     @abstractmethod
-    def list_sessions(self, app_name: str, user_id: str) -> "list[SessionRecord]":
-        """List all sessions for an app and user.
+    def list_sessions(self, app_name: str, user_id: "str | None" = None) -> "list[SessionRecord]":
+        """List all sessions for an app, optionally filtered by user.
 
         Args:
             app_name: Name of the application.
-            user_id: ID of the user.
+            user_id: ID of the user. If None, returns all sessions for the app.
 
         Returns:
             List of session records.

sqlspec/extensions/aiosql/adapter.py

@@ -13,14 +13,8 @@ from typing import Any, ClassVar, Generic, TypeVar
 from sqlspec.core.result import SQLResult
 from sqlspec.core.statement import SQL, StatementConfig
 from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
-from sqlspec.exceptions import MissingDependencyError
-from sqlspec.typing import (
-    AIOSQL_INSTALLED,
-    AiosqlAsyncProtocol,
-    AiosqlParamType,
-    AiosqlSQLOperationType,
-    AiosqlSyncProtocol,
-)
+from sqlspec.typing import AiosqlAsyncProtocol, AiosqlParamType, AiosqlSQLOperationType, AiosqlSyncProtocol
+from sqlspec.utils.module_loader import ensure_aiosql
 
 logger = logging.getLogger("sqlspec.extensions.aiosql")
 
@@ -58,12 +52,6 @@ class CursorLike:
         return rows[0] if rows else None
 
 
-def _check_aiosql_available() -> None:
-    if not AIOSQL_INSTALLED:
-        msg = "aiosql"
-        raise MissingDependencyError(msg, "aiosql")
-
-
 def _normalize_dialect(dialect: "str | Any | None") -> str:
     """Normalize dialect name for SQLGlot compatibility.
 
@@ -105,7 +93,7 @@ class _AiosqlAdapterBase(Generic[DriverT]):
         Args:
             driver: SQLSpec driver to use for execution.
         """
-        _check_aiosql_available()
+        ensure_aiosql()
         self.driver: DriverT = driver
 
     def process_sql(self, query_name: str, op_type: "AiosqlSQLOperationType", sql: str) -> str:

sqlspec/extensions/fastapi/__init__.py

@@ -0,0 +1,21 @@
+"""FastAPI extension for SQLSpec.
+
+Extends Starlette integration with dependency injection helpers for FastAPI's
+Depends() system, including filter dependency builders.
+"""
+
+from sqlspec.config import StarletteConfig
+from sqlspec.extensions.fastapi.extension import SQLSpecPlugin
+from sqlspec.extensions.fastapi.providers import DependencyDefaults, FieldNameType, FilterConfig, provide_filters
+from sqlspec.extensions.starlette.middleware import SQLSpecAutocommitMiddleware, SQLSpecManualMiddleware
+
+__all__ = (
+    "DependencyDefaults",
+    "FieldNameType",
+    "FilterConfig",
+    "SQLSpecAutocommitMiddleware",
+    "SQLSpecManualMiddleware",
+    "SQLSpecPlugin",
+    "StarletteConfig",
+    "provide_filters",
+)