refactor: tighten adapter typing and core cleanup

docs/conf.py

@@ -135,6 +135,7 @@
     "ParameterMapping": "sqlspec.core.parameters.ParameterMapping",
     "ParameterSequence": "sqlspec.core.parameters.ParameterSequence",
     "ParameterPayload": "sqlspec.core.parameters.ParameterPayload",
+    "DialectType": "sqlglot.dialects.dialect.DialectType",
     "Union": "typing.Union",
     "Callable": "typing.Callable",
     "Any": "typing.Any",

docs/reference/core/filters.rst

@@ -25,10 +25,12 @@ Date Filters
 
 .. autoclass:: BeforeAfterFilter
    :members:
+   :inherited-members:
    :show-inheritance:
 
 .. autoclass:: OnBeforeAfterFilter
    :members:
+   :inherited-members:
    :show-inheritance:
 
 Collection Filters
@@ -84,10 +86,12 @@ Search
 
 .. autoclass:: SearchFilter
    :members:
+   :inherited-members:
    :show-inheritance:
 
 .. autoclass:: NotInSearchFilter
    :members:
+   :inherited-members:
    :show-inheritance:
 
 Type Aliases

sqlspec/__init__.py

@@ -16,9 +16,6 @@
 from typing import TYPE_CHECKING, Any
 
 from sqlspec import adapters, base, builder, core, driver, exceptions, extensions, loader, migrations, typing, utils
-
-if TYPE_CHECKING:
-    from sqlspec import dialects
 from sqlspec.__metadata__ import __version__
 from sqlspec.base import SQLSpec
 from sqlspec.builder import (
@@ -86,6 +83,9 @@
 from sqlspec.typing import ConnectionT, PoolT, SchemaT, StatementParameters, SupportedSchemaModel
 from sqlspec.utils.logging import suppress_erroneous_sqlglot_log_messages
 
+if TYPE_CHECKING:
+    from sqlspec import dialects
+
 __all__ = (
     "SQL",
     "ArrowResult",

sqlspec/adapters/adbc/config.py

@@ -13,6 +13,7 @@
     get_statement_config,
     is_postgres_dialect,
     resolve_dialect_from_config,
+    resolve_dialect_name,
     resolve_driver_connect_func,
     resolve_postgres_extension_state,
     resolve_runtime_statement_config,
@@ -194,7 +195,7 @@ def __init__(
         self,
         *,
         connection_config: "AdbcConnectionParams | dict[str, Any] | None" = None,
-        connection_instance: "Any" = None,
+        connection_instance: "AdbcConnection | None" = None,
         migration_config: "dict[str, Any] | None" = None,
         statement_config: StatementConfig | None = None,
         driver_features: "AdbcDriverFeatures | dict[str, Any] | None" = None,
@@ -256,13 +257,15 @@ def create_connection(self) -> AdbcConnection:
         """
 
         try:
-            connection = resolve_driver_connect_func(
-                self.connection_config.get("driver_name"), self.connection_config.get("uri")
-            )(**build_connection_config(self.connection_config))
+            driver_name = cast("str | None", self.connection_config.get("driver_name"))
+            uri = cast("str | None", self.connection_config.get("uri"))
+            connection = resolve_driver_connect_func(driver_name, uri)(
+                **build_connection_config(self.connection_config)
+            )
             return cast("AdbcConnection", connection)
         except Exception as e:
-            driver_name = self.connection_config.get("driver_name", "Unknown")
-            msg = f"Could not configure connection using driver '{driver_name}'. Error: {e}"
+            err_driver_name = self.connection_config.get("driver_name", "Unknown")
+            msg = f"Could not configure connection using driver '{err_driver_name}'. Error: {e}"
             raise ImproperConfigurationError(msg) from e
 
     def _update_dialect_for_extensions(self) -> None:
@@ -271,7 +274,7 @@ def _update_dialect_for_extensions(self) -> None:
         Priority: paradedb > pgvector > postgres (default).
         Only switches when current dialect is ``postgres``.
         """
-        current_dialect = getattr(self.statement_config, "dialect", "postgres")
+        current_dialect = self.statement_config.dialect or "postgres"
         if current_dialect != "postgres":
             return
 
@@ -289,7 +292,7 @@ def _detect_extensions_if_needed(self) -> None:
         if self._pgvector_available is not None:
             return
 
-        dialect = getattr(self.statement_config, "dialect", "")
+        dialect = resolve_dialect_name(self.statement_config.dialect)
         if not is_postgres_dialect(dialect):
             self._pgvector_available = False
             self._paradedb_available = False

sqlspec/adapters/aiomysql/core.py

@@ -4,8 +4,6 @@
 from collections.abc import Callable, Sized
 from typing import TYPE_CHECKING, Any
 
-from aiomysql import SSCursor
-
 from sqlspec.core import DriverParameterProfile, ParameterStyle, StatementConfig, build_statement_config_from_profile
 from sqlspec.driver import rows_to_dicts
 from sqlspec.exceptions import (
@@ -24,6 +22,7 @@
     TransactionError,
     UniqueViolationError,
 )
+from sqlspec.protocols import HasSqlStateProtocol, HasTypeCodeProtocol
 from sqlspec.utils.serializers import from_json, to_json
 from sqlspec.utils.text import quote_backtick_identifier, split_qualified_identifier
 from sqlspec.utils.type_converters import build_uuid_coercions
@@ -189,6 +188,8 @@ def __init__(self, driver: Any, sql: str, parameters: Any, chunk_size: int) -> N
         self._column_names: list[str] | None = None
 
     async def start(self) -> None:
+        from aiomysql import SSCursor
+
         handler = self._driver.handle_database_exceptions()
         async with handler:
             cursor = await self._driver.connection.cursor(SSCursor)
@@ -324,13 +325,11 @@ def create_mapped_exception(error: Any, *, logger: Any | None = None) -> "SQLSpe
     Returns:
         True to suppress expected migration errors, or a SQLSpec exception
     """
-    error_args = getattr(error, "args", ())
+    error_args = error.args
     error_code = error_args[0] if error_args and isinstance(error_args[0], int) else None
-    sqlstate_attr = getattr(error, "sqlstate", None)
-    sqlstate = sqlstate_attr if isinstance(sqlstate_attr, str) else None
+    sqlstate = error.sqlstate if isinstance(error, HasSqlStateProtocol) else None
     sqlstate_prefix = sqlstate[:2] if isinstance(sqlstate, str) and sqlstate else None
 
-    # Migration-specific errors to suppress
     if error_code in _MYSQL_MIGRATION_ERROR_CODES:
         if logger is not None:
             logger.warning("aiomysql MySQL expected migration error (ignoring): %s", error)
@@ -402,7 +401,7 @@ def detect_json_columns_from_description(
         if isinstance(column, (tuple, list)):
             type_code = column[1] if len(column) > 1 else None
         else:
-            type_code = getattr(column, "type_code", None)
+            type_code = column.type_code if isinstance(column, HasTypeCodeProtocol) else None
         if type_code in json_type_codes:
             append(index)
     return json_indexes

sqlspec/adapters/arrow_odbc/config.py

@@ -11,6 +11,7 @@
 from sqlspec.driver._sync import SyncPoolConnectionContext, SyncPoolSessionFactory
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.extensions.events import EventRuntimeHints
+from sqlspec.protocols import SupportsCloseProtocol
 from sqlspec.utils.config_tools import normalize_connection_config
 
 if TYPE_CHECKING:
@@ -124,7 +125,7 @@ def __init__(
         self,
         *,
         connection_config: "ArrowOdbcConnectionParams | dict[str, Any] | None" = None,
-        connection_instance: "Any" = None,
+        connection_instance: "ArrowOdbcConnection | None" = None,
         migration_config: "dict[str, Any] | None" = None,
         statement_config: "StatementConfig | None" = None,
         driver_features: "ArrowOdbcDriverFeatures | dict[str, Any] | None" = None,
@@ -204,6 +205,5 @@ def get_event_runtime_hints(self) -> "EventRuntimeHints":
 
 def _close_arrow_odbc_connection(connection: "ArrowOdbcConnection") -> None:
     """Close connection objects from compatible wrappers when they expose close()."""
-    close = getattr(connection, "close", None)
-    if close is not None:
-        close()
+    if isinstance(connection, SupportsCloseProtocol):
+        connection.close()

sqlspec/adapters/asyncmy/core.py

@@ -4,8 +4,6 @@
 from collections.abc import Callable, Sized
 from typing import TYPE_CHECKING, Any
 
-from asyncmy.cursors import SSCursor
-
 from sqlspec.core import DriverParameterProfile, ParameterStyle, StatementConfig, build_statement_config_from_profile
 from sqlspec.driver import rows_to_dicts
 from sqlspec.exceptions import (
@@ -24,6 +22,7 @@
     TransactionError,
     UniqueViolationError,
 )
+from sqlspec.protocols import HasSqlStateProtocol, HasTypeCodeProtocol
 from sqlspec.utils.serializers import from_json, to_json
 from sqlspec.utils.text import quote_backtick_identifier, split_qualified_identifier
 from sqlspec.utils.type_converters import build_uuid_coercions
@@ -161,6 +160,8 @@ def __init__(self, driver: Any, sql: str, parameters: Any, chunk_size: int) -> N
         self._column_names: list[str] | None = None
 
     async def start(self) -> None:
+        from asyncmy.cursors import SSCursor
+
         handler = self._driver.handle_database_exceptions()
         async with handler:
             cursor = self._driver.connection.cursor(SSCursor)
@@ -296,13 +297,11 @@ def create_mapped_exception(error: Any, *, logger: Any | None = None) -> "SQLSpe
     Returns:
         True to suppress expected migration errors, or a SQLSpec exception
     """
-    error_args = getattr(error, "args", ())
+    error_args = error.args
     error_code = error_args[0] if error_args and isinstance(error_args[0], int) else None
-    sqlstate_attr = getattr(error, "sqlstate", None)
-    sqlstate = sqlstate_attr if isinstance(sqlstate_attr, str) else None
+    sqlstate = error.sqlstate if isinstance(error, HasSqlStateProtocol) else None
     sqlstate_prefix = sqlstate[:2] if isinstance(sqlstate, str) and sqlstate else None
 
-    # Migration-specific errors to suppress
     if error_code in _MYSQL_MIGRATION_ERROR_CODES:
         if logger is not None:
             logger.warning("AsyncMy MySQL expected migration error (ignoring): %s", error)
@@ -374,7 +373,7 @@ def detect_json_columns_from_description(
         if isinstance(column, (tuple, list)):
             type_code = column[1] if len(column) > 1 else None
         else:
-            type_code = getattr(column, "type_code", None)
+            type_code = column.type_code if isinstance(column, HasTypeCodeProtocol) else None
         if type_code in json_type_codes:
             append(index)
     return json_indexes

sqlspec/adapters/asyncpg/_typing.py

@@ -6,7 +6,7 @@
 
 from typing import TYPE_CHECKING, Any
 
-from asyncpg import Pool
+from asyncpg import Pool, PostgresError
 from asyncpg.pool import PoolConnectionProxy
 from asyncpg.prepared_stmt import PreparedStatement
 
@@ -22,14 +22,23 @@
 
     AsyncpgConnection: TypeAlias = Connection[Record] | PoolConnectionProxy[Record]
     AsyncpgPool: TypeAlias = Pool[Record]
+    AsyncpgPostgresError: TypeAlias = PostgresError
     AsyncpgPreparedStatement: TypeAlias = PreparedStatement[Record]
 
 if not TYPE_CHECKING:
     AsyncpgConnection = PoolConnectionProxy
     AsyncpgPool = Pool
+    AsyncpgPostgresError = PostgresError
     AsyncpgPreparedStatement = PreparedStatement
 
-__all__ = ("AsyncpgConnection", "AsyncpgCursor", "AsyncpgPool", "AsyncpgPreparedStatement", "AsyncpgSessionContext")
+__all__ = (
+    "AsyncpgConnection",
+    "AsyncpgCursor",
+    "AsyncpgPool",
+    "AsyncpgPostgresError",
+    "AsyncpgPreparedStatement",
+    "AsyncpgSessionContext",
+)
 
 
 class AsyncpgCursor:

sqlspec/adapters/asyncpg/driver.py

@@ -5,9 +5,7 @@
 from io import BytesIO
 from typing import TYPE_CHECKING, Any, Final, cast
 
-import asyncpg
-
-from sqlspec.adapters.asyncpg._typing import AsyncpgCursor, AsyncpgSessionContext
+from sqlspec.adapters.asyncpg._typing import AsyncpgCursor, AsyncpgPostgresError, AsyncpgSessionContext
 from sqlspec.adapters.asyncpg.core import (
     PREPARED_STATEMENT_CACHE_SIZE,
     AsyncpgStreamSource,
@@ -77,7 +75,7 @@ class AsyncpgExceptionHandler(BaseAsyncExceptionHandler):
 
     def _handle_exception(self, exc_type: "type[BaseException] | None", exc_val: "BaseException") -> bool:
         _ = exc_type
-        if isinstance(exc_val, asyncpg.PostgresError) or has_sqlstate(exc_val):
+        if isinstance(exc_val, AsyncpgPostgresError) or has_sqlstate(exc_val):
             self.pending_exception = create_mapped_exception(exc_val)
             return True
         return False
@@ -217,23 +215,23 @@ async def begin(self) -> None:
         """Begin a database transaction."""
         try:
             await self.connection.execute("BEGIN")
-        except asyncpg.PostgresError as e:
+        except AsyncpgPostgresError as e:
             msg = f"Failed to begin async transaction: {e}"
             raise SQLSpecError(msg) from e
 
     async def commit(self) -> None:
         """Commit the current transaction."""
         try:
             await self.connection.execute("COMMIT")
-        except asyncpg.PostgresError as e:
+        except AsyncpgPostgresError as e:
             msg = f"Failed to commit async transaction: {e}"
             raise SQLSpecError(msg) from e
 
     async def rollback(self) -> None:
         """Rollback the current transaction."""
         try:
             await self.connection.execute("ROLLBACK")
-        except asyncpg.PostgresError as e:
+        except AsyncpgPostgresError as e:
             msg = f"Failed to rollback async transaction: {e}"
             raise SQLSpecError(msg) from e
 
@@ -414,13 +412,12 @@ async def load_from_arrow(
         telemetry: "StorageTelemetry | None" = None,
     ) -> "StorageBridgeJob":
         """Load Arrow data into a PostgreSQL table via COPY."""
-
         self._require_capability("arrow_import_enabled")
         arrow_table = self._coerce_arrow_table(source)
         if overwrite:
             try:
                 await self.connection.execute(f"TRUNCATE TABLE {table}")
-            except asyncpg.PostgresError as exc:
+            except AsyncpgPostgresError as exc:
                 msg = f"Failed to truncate table '{table}': {exc}"
                 raise SQLSpecError(msg) from exc
         columns, records = self._arrow_table_to_rows(arrow_table)
@@ -504,7 +501,7 @@ async def _handle_copy_operation(self, cursor: "AsyncpgConnection", statement: "
 
         execution_args = statement.statement_config.execution_args
         metadata: dict[str, Any] = dict(execution_args) if execution_args else {}
-        if getattr(statement, "is_processed", False):
+        if statement.is_processed:
             sql_text = statement.get_processed_state().compiled_sql
         else:
             sql_text, _ = self._get_compiled_sql(statement, statement.statement_config)

sqlspec/adapters/bigquery/_typing.py

@@ -8,6 +8,9 @@
 from typing import TYPE_CHECKING, Any
 
 from google.cloud.bigquery import ArrayQueryParameter, Client, QueryJob, ScalarQueryParameter
+from google.cloud.exceptions import GoogleCloudError
+
+from sqlspec.typing import import_optional
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -19,12 +22,24 @@
 
     BigQueryConnection: TypeAlias = Client
     BigQueryParam: TypeAlias = ArrayQueryParameter | ScalarQueryParameter
+    BigQueryStorageWriteModule: Any
+    BigQueryStorageWriteTypes: Any
 
 if not TYPE_CHECKING:
     BigQueryConnection = Client
     BigQueryParam = ArrayQueryParameter | ScalarQueryParameter
-
-__all__ = ("BigQueryConnection", "BigQueryCursor", "BigQueryParam", "BigQuerySessionContext")
+    BigQueryStorageWriteModule = import_optional("google.cloud.bigquery_storage_v1")
+    BigQueryStorageWriteTypes = import_optional("google.cloud.bigquery_storage_v1.types")
+
+__all__ = (
+    "BigQueryConnection",
+    "BigQueryCursor",
+    "BigQueryParam",
+    "BigQuerySessionContext",
+    "BigQueryStorageWriteModule",
+    "BigQueryStorageWriteTypes",
+    "GoogleCloudError",
+)
 
 
 class BigQueryCursor: