sqlspec 0.48.2__py3-none-any.whl → 0.49.0__py3-none-any.whl

sqlspec/__init__.py

@@ -89,8 +89,6 @@ from sqlspec.observability import (
 from sqlspec.typing import ConnectionT, PoolT, SchemaT, StatementParameters, SupportedSchemaModel
 from sqlspec.utils.logging import suppress_erroneous_sqlglot_log_messages
 
-suppress_erroneous_sqlglot_log_messages()
-
 __all__ = (
     "SQL",
     "ArrowResult",
@@ -165,3 +163,5 @@ __all__ = (
     "typing",
     "utils",
 )
+
+suppress_erroneous_sqlglot_log_messages()

sqlspec/_typing.py

@@ -3,7 +3,7 @@
 
 Public consumers should import from :mod:`sqlspec.typing`. This module is kept
 private because it centralizes optional dependency fallbacks, compatibility
-aliases, and mypyc-excluded type boundaries used by the package internals.
+aliases, and mypyc-excluded type boundaries for package internals.
 """
 
 import enum
@@ -14,7 +14,92 @@ from typing import Any, ClassVar, Final, Literal, Protocol, cast, runtime_checka
 
 from typing_extensions import Self, TypeVar, dataclass_transform
 
-from sqlspec.utils.module_loader import dependency_flag, module_available
+from sqlspec.utils.module_loader import dependency_flag, import_optional, import_optional_attr, module_available
+
+__all__ = (
+    "ALLOYDB_CONNECTOR_INSTALLED",
+    "ATTRS_INSTALLED",
+    "CATTRS_INSTALLED",
+    "CLOUD_SQL_CONNECTOR_INSTALLED",
+    "FSSPEC_INSTALLED",
+    "LITESTAR_INSTALLED",
+    "MSGSPEC_INSTALLED",
+    "NANOID_INSTALLED",
+    "NUMPY_INSTALLED",
+    "OBSTORE_INSTALLED",
+    "OPENTELEMETRY_INSTALLED",
+    "ORJSON_INSTALLED",
+    "PANDAS_INSTALLED",
+    "PGVECTOR_INSTALLED",
+    "POLARS_INSTALLED",
+    "PROMETHEUS_INSTALLED",
+    "PYARROW_INSTALLED",
+    "PYDANTIC_INSTALLED",
+    "UNSET",
+    "UNSET_STUB",
+    "UUID_UTILS_INSTALLED",
+    "ArrowRecordBatch",
+    "ArrowRecordBatchReader",
+    "ArrowRecordBatchReaderProtocol",
+    "ArrowRecordBatchResult",
+    "ArrowSchema",
+    "ArrowSchemaProtocol",
+    "ArrowTable",
+    "ArrowTableResult",
+    "AttrsInstance",
+    "AttrsInstanceStub",
+    "BaseModel",
+    "BaseModelStub",
+    "Counter",
+    "DTOData",
+    "DTODataStub",
+    "DataclassProtocol",
+    "Empty",
+    "EmptyEnum",
+    "EmptyType",
+    "FailFast",
+    "FailFastStub",
+    "Gauge",
+    "Histogram",
+    "NumpyArray",
+    "NumpyArrayStub",
+    "PandasDataFrame",
+    "PandasDataFrameProtocol",
+    "PolarsDataFrame",
+    "PolarsDataFrameProtocol",
+    "Span",
+    "Status",
+    "StatusCode",
+    "Struct",
+    "StructStub",
+    "T",
+    "T_co",
+    "Tracer",
+    "TypeAdapter",
+    "TypeAdapterStub",
+    "UnsetType",
+    "UnsetTypeStub",
+    "attrs_asdict",
+    "attrs_asdict_stub",
+    "attrs_define",
+    "attrs_define_stub",
+    "attrs_field",
+    "attrs_field_stub",
+    "attrs_fields",
+    "attrs_fields_stub",
+    "attrs_has",
+    "attrs_has_stub",
+    "cattrs_structure",
+    "cattrs_unstructure",
+    "convert",
+    "convert_stub",
+    "import_optional",
+    "import_optional_attr",
+    "module_available",
+    "msgspec_fields",
+    "msgspec_fields_stub",
+    "trace",
+)
 
 
 @runtime_checkable
@@ -630,85 +715,3 @@ PYDANTIC_INSTALLED = dependency_flag("pydantic")
 ALLOYDB_CONNECTOR_INSTALLED = dependency_flag("google.cloud.alloydb.connector")
 NANOID_INSTALLED = dependency_flag("fastnanoid")
 UUID_UTILS_INSTALLED = dependency_flag("uuid_utils")
-__all__ = (
-    "ALLOYDB_CONNECTOR_INSTALLED",
-    "ATTRS_INSTALLED",
-    "CATTRS_INSTALLED",
-    "CLOUD_SQL_CONNECTOR_INSTALLED",
-    "FSSPEC_INSTALLED",
-    "LITESTAR_INSTALLED",
-    "MSGSPEC_INSTALLED",
-    "NANOID_INSTALLED",
-    "NUMPY_INSTALLED",
-    "OBSTORE_INSTALLED",
-    "OPENTELEMETRY_INSTALLED",
-    "ORJSON_INSTALLED",
-    "PANDAS_INSTALLED",
-    "PGVECTOR_INSTALLED",
-    "POLARS_INSTALLED",
-    "PROMETHEUS_INSTALLED",
-    "PYARROW_INSTALLED",
-    "PYDANTIC_INSTALLED",
-    "UNSET",
-    "UNSET_STUB",
-    "UUID_UTILS_INSTALLED",
-    "ArrowRecordBatch",
-    "ArrowRecordBatchReader",
-    "ArrowRecordBatchReaderProtocol",
-    "ArrowRecordBatchResult",
-    "ArrowSchema",
-    "ArrowSchemaProtocol",
-    "ArrowTable",
-    "ArrowTableResult",
-    "AttrsInstance",
-    "AttrsInstanceStub",
-    "BaseModel",
-    "BaseModelStub",
-    "Counter",
-    "DTOData",
-    "DTODataStub",
-    "DataclassProtocol",
-    "Empty",
-    "EmptyEnum",
-    "EmptyType",
-    "FailFast",
-    "FailFastStub",
-    "Gauge",
-    "Histogram",
-    "NumpyArray",
-    "NumpyArrayStub",
-    "PandasDataFrame",
-    "PandasDataFrameProtocol",
-    "PolarsDataFrame",
-    "PolarsDataFrameProtocol",
-    "Span",
-    "Status",
-    "StatusCode",
-    "Struct",
-    "StructStub",
-    "T",
-    "T_co",
-    "Tracer",
-    "TypeAdapter",
-    "TypeAdapterStub",
-    "UnsetType",
-    "UnsetTypeStub",
-    "attrs_asdict",
-    "attrs_asdict_stub",
-    "attrs_define",
-    "attrs_define_stub",
-    "attrs_field",
-    "attrs_field_stub",
-    "attrs_fields",
-    "attrs_fields_stub",
-    "attrs_has",
-    "attrs_has_stub",
-    "cattrs_structure",
-    "cattrs_unstructure",
-    "convert",
-    "convert_stub",
-    "module_available",
-    "msgspec_fields",
-    "msgspec_fields_stub",
-    "trace",
-)

sqlspec/adapters/adbc/_typing.py

@@ -28,6 +28,8 @@ if not TYPE_CHECKING:
     AdbcConnection = _AdbcConnection
     AdbcRawCursor = _AdbcRawCursor
 
+__all__ = ("AdbcConnection", "AdbcCursor", "AdbcRawCursor", "AdbcSessionContext")
+
 
 class AdbcCursor:
     """Context manager for cursor management."""
@@ -106,6 +108,3 @@ class AdbcSessionContext:
             self._release_connection(self._connection)
             self._connection = None
         return None
-
-
-__all__ = ("AdbcConnection", "AdbcCursor", "AdbcRawCursor", "AdbcSessionContext")

sqlspec/adapters/adbc/adk/store.py

@@ -14,9 +14,10 @@ if TYPE_CHECKING:
     from sqlspec.adapters.adbc.config import AdbcConfig
     from sqlspec.extensions.adk import MemoryRecord
 
+__all__ = ("AdbcADKMemoryStore", "AdbcADKStore")
+
 logger = get_logger("sqlspec.adapters.adbc.adk.store")
 
-__all__ = ("AdbcADKMemoryStore", "AdbcADKStore")
 
 DIALECT_POSTGRESQL: Final = "postgresql"
 DIALECT_SQLITE: Final = "sqlite"
@@ -35,46 +36,21 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
     transfer across multiple databases (PostgreSQL, SQLite, DuckDB, etc.).
 
     Events use the new 5-column contract: session_id, invocation_id, author,
-    timestamp, and event_json.  The full ADK Event payload is stored as a
+    timestamp, and event_json. The full ADK Event payload is stored as a
     single JSON blob in event_json using a dialect-appropriate column type
     (JSONB for PostgreSQL, JSON for DuckDB, VARIANT for Snowflake, TEXT for
     SQLite and generic fallback).
 
     Provides:
-    - Session state management with JSON serialization
-    - Event history tracking via single event_json blob
-    - Atomic event insert + session state update
-    - Timezone-aware timestamps
-    - Foreign key constraints with cascade delete
-    - Database-agnostic SQL (supports multiple backends)
+        - Session state management with JSON serialization
+        - Event history tracking via single event_json blob
+        - Atomic event insert + session state update
+        - Timezone-aware timestamps
+        - Foreign key constraints with cascade delete
+        - Database-agnostic SQL (supports multiple backends)
 
     Args:
         config: AdbcConfig with extension_config["adk"] settings.
-
-    Example:
-        from sqlspec.adapters.adbc import AdbcConfig
-        from sqlspec.adapters.adbc.adk import AdbcADKStore
-
-        config = AdbcConfig(
-            connection_config={"driver_name": "sqlite", "uri": ":memory:"},
-            extension_config={
-                "adk": {
-                    "session_table": "my_sessions",
-                    "events_table": "my_events",
-                    "owner_id_column": "tenant_id INTEGER REFERENCES tenants(id)"
-                }
-            }
-        )
-        store = AdbcADKStore(config)
-        store.ensure_tables()
-
-    Notes:
-        - Dialect-appropriate JSON type for event_json storage
-        - TIMESTAMP for timezone-aware timestamps (driver-dependent precision)
-        - Parameter style: ``?`` universally across ADBC backends
-        - State and JSON fields use to_json/from_json for serialization
-        - ADBC drivers handle parameter binding automatically
-        - Configuration is read from config.extension_config["adk"]
     """
 
     __slots__ = ("_dialect",)
@@ -84,12 +60,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Args:
             config: AdbcConfig instance (any ADBC driver).
-
-        Notes:
-            Configuration is read from config.extension_config["adk"]:
-            - session_table: Sessions table name (default: "adk_sessions")
-            - events_table: Events table name (default: "adk_events")
-            - owner_id_column: Optional owner FK column DDL (default: None)
         """
         super().__init__(config)
         self._dialect = self._detect_dialect()
@@ -104,10 +74,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Returns:
             Dialect identifier for DDL generation.
-
-        Notes:
-            Reads from config.connection_config driver_name.
-            Falls back to generic for unknown drivers.
         """
         driver_name = self._config.connection_config.get("driver_name", "").lower()
 
@@ -304,9 +270,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Returns:
             SQL to create events table optimized for PostgreSQL.
-
-        Notes:
-            Uses JSONB for event_json to enable indexing and query support.
         """
         return f"""
         CREATE TABLE IF NOT EXISTS {self._events_table} (
@@ -324,9 +287,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Returns:
             SQL to create events table optimized for SQLite.
-
-        Notes:
-            Uses TEXT for event_json (SQLite has no native JSON column type).
         """
         return f"""
         CREATE TABLE IF NOT EXISTS {self._events_table} (
@@ -344,9 +304,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Returns:
             SQL to create events table optimized for DuckDB.
-
-        Notes:
-            Uses JSON for event_json (DuckDB native JSON type).
         """
         return f"""
         CREATE TABLE IF NOT EXISTS {self._events_table} (
@@ -364,9 +321,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Returns:
             SQL to create events table optimized for Snowflake.
-
-        Notes:
-            Uses VARIANT for event_json (Snowflake semi-structured type).
         """
         return f"""
         CREATE TABLE IF NOT EXISTS {self._events_table} (
@@ -384,9 +338,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Returns:
             SQL to create events table using generic types.
-
-        Notes:
-            Uses TEXT for event_json (maximum portability).
         """
         return f"""
         CREATE TABLE IF NOT EXISTS {self._events_table} (
@@ -404,10 +355,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Returns:
             List of SQL statements to drop tables and indexes.
-
-        Notes:
-            Order matters: drop events table (child) before sessions (parent).
-            Most databases automatically drop indexes when dropping tables.
         """
         return [f"DROP TABLE IF EXISTS {self._events_table}", f"DROP TABLE IF EXISTS {self._session_table}"]
 
@@ -457,10 +404,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
         Args:
             cursor: Database cursor.
             conn: Database connection.
-
-        Notes:
-            SQLite requires PRAGMA foreign_keys = ON to be set per connection.
-            This is a no-op for other databases.
         """
         try:
             cursor.execute("PRAGMA foreign_keys = ON")
@@ -528,9 +471,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Returns:
             Session record or None if not found.
-
-        Notes:
-            State is deserialized from JSON string.
         """
         sql = f"""
         SELECT id, app_name, user_id, state, create_time, update_time
@@ -574,10 +514,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
         Args:
             session_id: Session identifier.
             state: New state dictionary (replaces existing state).
-
-        Notes:
-            This replaces the entire state dictionary.
-            Updates update_time to current timestamp.
         """
         state_json = self._serialize_state(state)
         sql = f"""
@@ -603,9 +539,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Args:
             session_id: Session identifier.
-
-        Notes:
-            Foreign key constraint ensures events are cascade-deleted.
         """
         sql = f"DELETE FROM {self._session_table} WHERE id = ?"
 
@@ -631,9 +564,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Returns:
             List of session records ordered by update_time DESC.
-
-        Notes:
-            Uses composite index on (app_name, user_id) when user_id is provided.
         """
         if user_id is None:
             sql = f"""
@@ -718,7 +648,7 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
         """Atomically insert an event and update the session's durable state.
 
         The event insert, state update, and refresh-SELECT are executed within
-        a single connection and committed together.  ADBC drivers wrap a
+        a single connection and committed together. ADBC drivers wrap a
         variety of backends (Postgres, SQLite, DuckDB, ...) so we use a
         SELECT-after-UPDATE rather than relying on RETURNING which not every
         backend supports.
@@ -802,11 +732,6 @@ class AdbcADKStore(BaseAsyncADKStore["AdbcConfig"]):
 
         Returns:
             List of event records ordered by timestamp ASC.
-
-        Notes:
-            Uses index on (session_id, timestamp ASC).
-            Returns the 5-column EventRecord (session_id, invocation_id,
-            author, timestamp, event_json).
         """
         where_clauses = ["session_id = ?"]
         params: list[Any] = [session_id]

sqlspec/adapters/adbc/config.py

@@ -4,7 +4,7 @@ from typing import TYPE_CHECKING, Any, ClassVar, TypedDict, cast
 
 from typing_extensions import NotRequired
 
-from sqlspec.adapters.adbc._typing import AdbcConnection
+from sqlspec.adapters.adbc._typing import AdbcConnection, AdbcCursor, AdbcSessionContext
 from sqlspec.adapters.adbc.core import (
     apply_driver_features,
     build_connection_config,
@@ -17,7 +17,7 @@ from sqlspec.adapters.adbc.core import (
     resolve_postgres_extension_state,
     resolve_runtime_statement_config,
 )
-from sqlspec.adapters.adbc.driver import AdbcCursor, AdbcDriver, AdbcExceptionHandler, AdbcSessionContext
+from sqlspec.adapters.adbc.driver import AdbcDriver, AdbcExceptionHandler
 from sqlspec.config import ExtensionConfigs, NoPoolSyncConfig
 from sqlspec.core import StatementConfig
 from sqlspec.driver._sync import SyncPoolConnectionContext, SyncPoolSessionFactory
@@ -78,20 +78,20 @@ class AdbcDriverFeatures(TypedDict):
     Attributes:
         json_serializer: JSON serialization function to use.
             Callable that takes Any and returns str (JSON string).
-            Default: sqlspec.utils.serializers.to_json
+        Default: sqlspec.utils.serializers.to_json
         enable_cast_detection: Enable cast-aware parameter processing.
-            When True, detects SQL casts (e.g., ::JSONB) and applies appropriate
+            When True, detects SQL casts and applies appropriate
             serialization. Currently used for PostgreSQL JSONB handling.
-            Default: True
+        Default: True
         enable_strict_type_coercion: Enforce strict type coercion rules.
             When True, raises errors for unsupported type conversions.
             When False, attempts best-effort conversion.
-            Default: False
+        Default: False
         strict_type_coercion: Alias for enable_strict_type_coercion.
         enable_arrow_extension_types: Enable PyArrow extension type support.
             When True, preserves Arrow extension type metadata when reading data.
             When False, falls back to storage types.
-            Default: True
+        Default: True
         arrow_extension_types: Alias for enable_arrow_extension_types.
         enable_pgvector: Enable automatic pgvector extension detection.
             When True and the resolved dialect is PostgreSQL, queries ``pg_extension``
@@ -106,7 +106,7 @@ class AdbcDriverFeatures(TypedDict):
             Provides pub/sub capabilities via table-backed queue (ADBC has no native pub/sub).
             Requires extension_config["events"] for migration setup.
         events_backend: Event channel backend selection.
-            Only option: "table_queue" (durable table-backed queue with retries and exactly-once delivery).
+        Only option: "table_queue" (durable table-backed queue with retries and exactly-once delivery).
             ADBC does not have native pub/sub, so table_queue is the only backend.
             Defaults to "table_queue".
     """
@@ -171,14 +171,6 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
 
     Supports multiple database backends including PostgreSQL, SQLite, DuckDB,
     BigQuery, and Snowflake with automatic driver detection and loading.
-
-    Example::
-
-        config = AdbcConfig(
-            connection_config=AdbcConnectionParams(
-                uri="postgresql://user:pass@localhost/db"
-            )
-        )
     """
 
     driver_type: ClassVar[type[AdbcDriver]] = AdbcDriver
@@ -193,6 +185,7 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
     _session_factory_class: "ClassVar[type[_AdbcSessionConnectionHandler]]" = _AdbcSessionConnectionHandler
     _session_context_class: "ClassVar[type[AdbcSessionContext]]" = AdbcSessionContext
     _default_statement_config = StatementConfig()
+    __slots__ = ("_default_session_config", "_paradedb_available", "_pgvector_available", "_resolved_dialect")
 
     def __init__(
         self,
@@ -216,7 +209,7 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
             statement_config: Default SQL statement configuration
             driver_features: Driver feature configuration (AdbcDriverFeatures)
             bind_key: Optional unique identifier for this configuration
-            extension_config: Extension-specific configuration (e.g., Litestar plugin settings)
+            extension_config: Extension-specific configuration
             observability_config: Adapter-level observability overrides for lifecycle hooks and observers
             **kwargs: Additional keyword arguments passed to the base configuration.
         """
@@ -224,12 +217,13 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
         self._pgvector_available: bool | None = None
         self._paradedb_available: bool | None = None
 
-        dialect = resolve_dialect_from_config(self.connection_config)
+        self._resolved_dialect = resolve_dialect_from_config(self.connection_config)
 
         if statement_config is None:
-            statement_config = get_statement_config(dialect)
+            statement_config = get_statement_config(self._resolved_dialect)
 
         statement_config, driver_features = apply_driver_features(statement_config, driver_features)
+        self._default_session_config = get_statement_config(self._resolved_dialect)
 
         super().__init__(
             connection_config=self.connection_config,
@@ -246,7 +240,7 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
     @property
     def supports_migration_schemas(self) -> bool:  # type: ignore[override]
         """Migration schema support is only available for PostgreSQL-backed ADBC drivers."""
-        return is_postgres_dialect(resolve_dialect_from_config(self.connection_config))
+        return is_postgres_dialect(self._resolved_dialect)
 
     def create_connection(self) -> AdbcConnection:
         """Create and return a new connection using the specified driver.
@@ -346,9 +340,7 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
         """
         self._detect_extensions_if_needed()
         statement_config = resolve_runtime_statement_config(
-            statement_config,
-            self.statement_config,
-            get_statement_config(resolve_dialect_from_config(self.connection_config)),
+            statement_config, self.statement_config, self._default_session_config
         )
         handler = _AdbcSessionConnectionHandler(self)