sqlspec 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

sqlspec/adapters/oracledb/config/_common.py

@@ -5,8 +5,8 @@ from typing import TYPE_CHECKING, Generic, TypeVar
 
 from oracledb import ConnectionPool
 
-from sqlspec.config import GenericDatabaseConfig, GenericPoolConfig
-from sqlspec.utils.empty import Empty
+from sqlspec.base import DatabaseConfigProtocol, GenericDatabaseConfig, GenericPoolConfig
+from sqlspec.typing import Empty
 
 if TYPE_CHECKING:
     import ssl
@@ -17,7 +17,7 @@ if TYPE_CHECKING:
     from oracledb.connection import AsyncConnection, Connection
     from oracledb.pool import AsyncConnectionPool, ConnectionPool
 
-    from sqlspec.utils.empty import EmptyType
+    from sqlspec.typing import EmptyType
 
 __all__ = (
     "OracleGenericDatabaseConfig",
@@ -32,7 +32,7 @@ PoolT = TypeVar("PoolT", bound="ConnectionPool | AsyncConnectionPool")
 
 
 @dataclass
-class OracleGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
+class OracleGenericPoolConfig(Generic[ConnectionT, PoolT], GenericPoolConfig):
     """Configuration for Oracle database connection pools.
 
     This class provides configuration options for both synchronous and asynchronous Oracle
@@ -58,7 +58,7 @@ class OracleGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
     """New password for password change operations"""
     wallet_password: str | EmptyType = Empty
     """Password for accessing Oracle Wallet"""
-    access_token: str | tuple | Callable | EmptyType = Empty
+    access_token: str | tuple[str, ...] | Callable[[], str] | EmptyType = Empty
     """Token for token-based authentication"""
     host: str | EmptyType = Empty
     """Database server hostname"""
@@ -112,11 +112,11 @@ class OracleGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
     """If True, allows connections with different tags"""
     config_dir: str | EmptyType = Empty
     """Directory containing Oracle configuration files"""
-    appcontext: list | EmptyType = Empty
+    appcontext: list[str] | EmptyType = Empty
     """Application context list"""
-    shardingkey: list | EmptyType = Empty
+    shardingkey: list[str] | EmptyType = Empty
     """Sharding key list"""
-    supershardingkey: list | EmptyType = Empty
+    supershardingkey: list[str] | EmptyType = Empty
     """Super sharding key list"""
     debug_jdwp: str | EmptyType = Empty
     """JDWP debugging string"""
@@ -137,7 +137,7 @@ class OracleGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
 
 
 @dataclass
-class OracleGenericDatabaseConfig(Generic[PoolT, ConnectionT], GenericDatabaseConfig):
+class OracleGenericDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT], GenericDatabaseConfig):
     """Oracle database Configuration.
 
     This class provides the base configuration for Oracle database connections, extending

sqlspec/adapters/oracledb/config/_sync.py

@@ -13,7 +13,7 @@ from sqlspec.adapters.oracledb.config._common import (
     OracleGenericPoolConfig,
 )
 from sqlspec.exceptions import ImproperConfigurationError
-from sqlspec.utils.dataclass import simple_asdict
+from sqlspec.typing import dataclass_to_dict
 
 if TYPE_CHECKING:
     from collections.abc import Generator
@@ -26,14 +26,17 @@ __all__ = (
 
 
 @dataclass
-class OracleSyncPoolConfig(OracleGenericPoolConfig[ConnectionPool, Connection]):
+class OracleSyncPoolConfig(OracleGenericPoolConfig[Connection, ConnectionPool]):
     """Sync Oracle Pool Config"""
 
 
 @dataclass
-class OracleSyncDatabaseConfig(OracleGenericDatabaseConfig[ConnectionPool, Connection]):
+class OracleSyncDatabaseConfig(OracleGenericDatabaseConfig[Connection, ConnectionPool]):
     """Oracle database Configuration."""
 
+    __is_async__ = False
+    __supports_connection_pooling__ = True
+
     pool_config: OracleSyncPoolConfig | None = None
     """Oracle Pool configuration"""
     pool_instance: ConnectionPool | None = None
@@ -51,7 +54,7 @@ class OracleSyncDatabaseConfig(OracleGenericDatabaseConfig[ConnectionPool, Conne
             function.
         """
         if self.pool_config:
-            return simple_asdict(self.pool_config, exclude_empty=True, convert_nested=False)
+            return dataclass_to_dict(self.pool_config, exclude_empty=True, convert_nested=False)
         msg = "'pool_config' methods can not be used when a 'pool_instance' is provided."
         raise ImproperConfigurationError(msg)
 
@@ -70,18 +73,11 @@ class OracleSyncDatabaseConfig(OracleGenericDatabaseConfig[ConnectionPool, Conne
 
         pool_config = self.pool_config_dict
         self.pool_instance = oracledb_create_pool(**pool_config)
-        if self.pool_instance is None:
+        if self.pool_instance is None:  # pyright: ignore[reportUnnecessaryComparison]
             msg = "Could not configure the 'pool_instance'. Please check your configuration."
             raise ImproperConfigurationError(msg)
         return self.pool_instance
 
-    def lifespan(self, *args: Any, **kwargs: Any) -> Generator[None, None, None]:
-        db_pool = self.create_pool()
-        try:
-            yield
-        finally:
-            db_pool.close()
-
     def provide_pool(self, *args: Any, **kwargs: Any) -> ConnectionPool:
         """Create a pool instance.
 
@@ -98,5 +94,5 @@ class OracleSyncDatabaseConfig(OracleGenericDatabaseConfig[ConnectionPool, Conne
             A connection instance.
         """
         db_pool = self.provide_pool(*args, **kwargs)
-        with db_pool.acquire() as connection:
+        with db_pool.acquire() as connection:  # pyright: ignore[reportUnknownMemberType]
             yield connection

sqlspec/adapters/psycopg/config/__init__.py

@@ -1,5 +1,5 @@
-from ._async import PsycoPgAsyncDatabaseConfig, PsycoPgAsyncPoolConfig
-from ._sync import PsycoPgSyncDatabaseConfig, PsycoPgSyncPoolConfig
+from sqlspec.adapters.psycopg.config._async import PsycoPgAsyncDatabaseConfig, PsycoPgAsyncPoolConfig
+from sqlspec.adapters.psycopg.config._sync import PsycoPgSyncDatabaseConfig, PsycoPgSyncPoolConfig
 
 __all__ = (
     "PsycoPgAsyncDatabaseConfig",

sqlspec/adapters/psycopg/config/_async.py

@@ -12,7 +12,7 @@ from sqlspec.adapters.psycopg.config._common import (
     PsycoPgGenericPoolConfig,
 )
 from sqlspec.exceptions import ImproperConfigurationError
-from sqlspec.utils.dataclass import simple_asdict
+from sqlspec.typing import dataclass_to_dict
 
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Awaitable
@@ -26,14 +26,17 @@ __all__ = (
 
 
 @dataclass
-class PsycoPgAsyncPoolConfig(PsycoPgGenericPoolConfig[AsyncConnectionPool, AsyncConnection]):
+class PsycoPgAsyncPoolConfig(PsycoPgGenericPoolConfig[AsyncConnection, AsyncConnectionPool]):
     """Async Psycopg Pool Config"""
 
 
 @dataclass
-class PsycoPgAsyncDatabaseConfig(PsycoPgGenericDatabaseConfig[AsyncConnectionPool, AsyncConnection]):
+class PsycoPgAsyncDatabaseConfig(PsycoPgGenericDatabaseConfig[AsyncConnection, AsyncConnectionPool]):
     """Async Psycopg database Configuration."""
 
+    __is_async__ = True
+    __supports_connection_pooling__ = True
+
     pool_config: PsycoPgAsyncPoolConfig | None = None
     """Psycopg Pool configuration"""
     pool_instance: AsyncConnectionPool | None = None
@@ -43,7 +46,7 @@ class PsycoPgAsyncDatabaseConfig(PsycoPgGenericDatabaseConfig[AsyncConnectionPoo
     def pool_config_dict(self) -> dict[str, Any]:
         """Return the pool configuration as a dict."""
         if self.pool_config:
-            return simple_asdict(self.pool_config, exclude_empty=True, convert_nested=False)
+            return dataclass_to_dict(self.pool_config, exclude_empty=True, convert_nested=False)
         msg = "'pool_config' methods can not be used when a 'pool_instance' is provided."
         raise ImproperConfigurationError(msg)
 
@@ -58,20 +61,11 @@ class PsycoPgAsyncDatabaseConfig(PsycoPgGenericDatabaseConfig[AsyncConnectionPoo
 
         pool_config = self.pool_config_dict
         self.pool_instance = AsyncConnectionPool(**pool_config)
-        if self.pool_instance is None:
+        if self.pool_instance is None:  # pyright: ignore[reportUnnecessaryComparison]
             msg = "Could not configure the 'pool_instance'. Please check your configuration."  # type: ignore[unreachable]
             raise ImproperConfigurationError(msg)
         return self.pool_instance
 
-    @asynccontextmanager
-    async def lifespan(self, *args: Any, **kwargs: Any) -> AsyncGenerator[None, None]:
-        """Manage the lifecycle of the connection pool."""
-        pool = await self.create_pool()
-        try:
-            yield
-        finally:
-            await pool.close()
-
     def provide_pool(self, *args: Any, **kwargs: Any) -> Awaitable[AsyncConnectionPool]:
         """Create and return a connection pool."""
         return self.create_pool()

sqlspec/adapters/psycopg/config/_common.py

@@ -3,8 +3,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Generic, TypeVar
 
-from sqlspec.config import GenericDatabaseConfig, GenericPoolConfig
-from sqlspec.utils.empty import Empty
+from sqlspec.base import DatabaseConfigProtocol, GenericDatabaseConfig, GenericPoolConfig
+from sqlspec.typing import Empty
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -13,7 +13,8 @@ if TYPE_CHECKING:
     from psycopg import AsyncConnection, Connection
     from psycopg_pool import AsyncConnectionPool, ConnectionPool
 
-    from sqlspec.utils.empty import EmptyType
+    from sqlspec.typing import EmptyType
+
 
 __all__ = (
     "PsycoPgGenericDatabaseConfig",
@@ -26,7 +27,7 @@ PoolT = TypeVar("PoolT", bound="ConnectionPool | AsyncConnectionPool")
 
 
 @dataclass
-class PsycoPgGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
+class PsycoPgGenericPoolConfig(Generic[ConnectionT, PoolT], GenericPoolConfig):
     """Configuration for Psycopg connection pools.
 
     This class provides configuration options for both synchronous and asynchronous Psycopg
@@ -61,7 +62,7 @@ class PsycoPgGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
 
 
 @dataclass
-class PsycoPgGenericDatabaseConfig(Generic[PoolT, ConnectionT], GenericDatabaseConfig):
+class PsycoPgGenericDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT], GenericDatabaseConfig):
     """Psycopg database Configuration.
 
     This class provides the base configuration for Psycopg database connections, extending

sqlspec/adapters/psycopg/config/_sync.py

@@ -12,7 +12,7 @@ from sqlspec.adapters.psycopg.config._common import (
     PsycoPgGenericPoolConfig,
 )
 from sqlspec.exceptions import ImproperConfigurationError
-from sqlspec.utils.dataclass import simple_asdict
+from sqlspec.typing import dataclass_to_dict
 
 if TYPE_CHECKING:
     from collections.abc import Generator
@@ -26,14 +26,17 @@ __all__ = (
 
 
 @dataclass
-class PsycoPgSyncPoolConfig(PsycoPgGenericPoolConfig[ConnectionPool, Connection]):
+class PsycoPgSyncPoolConfig(PsycoPgGenericPoolConfig[Connection, ConnectionPool]):
     """Sync Psycopg Pool Config"""
 
 
 @dataclass
-class PsycoPgSyncDatabaseConfig(PsycoPgGenericDatabaseConfig[ConnectionPool, Connection]):
+class PsycoPgSyncDatabaseConfig(PsycoPgGenericDatabaseConfig[Connection, ConnectionPool]):
     """Sync Psycopg database Configuration."""
 
+    __is_async__ = False
+    __supports_connection_pooling__ = True
+
     pool_config: PsycoPgSyncPoolConfig | None = None
     """Psycopg Pool configuration"""
     pool_instance: ConnectionPool | None = None
@@ -43,7 +46,7 @@ class PsycoPgSyncDatabaseConfig(PsycoPgGenericDatabaseConfig[ConnectionPool, Con
     def pool_config_dict(self) -> dict[str, Any]:
         """Return the pool configuration as a dict."""
         if self.pool_config:
-            return simple_asdict(self.pool_config, exclude_empty=True, convert_nested=False)
+            return dataclass_to_dict(self.pool_config, exclude_empty=True, convert_nested=False)
         msg = "'pool_config' methods can not be used when a 'pool_instance' is provided."
         raise ImproperConfigurationError(msg)
 
@@ -58,20 +61,11 @@ class PsycoPgSyncDatabaseConfig(PsycoPgGenericDatabaseConfig[ConnectionPool, Con
 
         pool_config = self.pool_config_dict
         self.pool_instance = ConnectionPool(**pool_config)
-        if self.pool_instance is None:
+        if self.pool_instance is None:  # pyright: ignore[reportUnnecessaryComparison]
             msg = "Could not configure the 'pool_instance'. Please check your configuration."  # type: ignore[unreachable]
             raise ImproperConfigurationError(msg)
         return self.pool_instance
 
-    @contextmanager
-    def lifespan(self, *args: Any, **kwargs: Any) -> Generator[None, None, None]:
-        """Manage the lifecycle of the connection pool."""
-        pool = self.create_pool()
-        try:
-            yield
-        finally:
-            pool.close()
-
     def provide_pool(self, *args: Any, **kwargs: Any) -> ConnectionPool:
         """Create and return a connection pool."""
         return self.create_pool()

sqlspec/adapters/sqlite/config.py

@@ -4,10 +4,9 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Literal
 
-from sqlspec.config import GenericDatabaseConfig
+from sqlspec.base import GenericDatabaseConfig, NoPoolConfig
 from sqlspec.exceptions import ImproperConfigurationError
-from sqlspec.utils.dataclass import simple_asdict
-from sqlspec.utils.empty import Empty, EmptyType
+from sqlspec.typing import Empty, EmptyType, dataclass_to_dict
 
 if TYPE_CHECKING:
     from collections.abc import Generator
@@ -17,7 +16,7 @@ __all__ = ("SqliteConfig",)
 
 
 @dataclass
-class SqliteConfig(GenericDatabaseConfig):
+class SqliteConfig(NoPoolConfig["Connection"], GenericDatabaseConfig):
     """Configuration for SQLite database connections.
 
     This class provides configuration options for SQLite database connections, wrapping all parameters
@@ -26,7 +25,7 @@ class SqliteConfig(GenericDatabaseConfig):
     For details see: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect
     """
 
-    database: str
+    database: str = ":memory:"
     """The path to the database file to be opened. Pass ":memory:" to open a connection to a database that resides in RAM instead of on disk."""
 
     timeout: float | EmptyType = Empty
@@ -57,7 +56,7 @@ class SqliteConfig(GenericDatabaseConfig):
         Returns:
             A string keyed dict of config kwargs for the sqlite3.connect() function.
         """
-        return simple_asdict(self, exclude_empty=True, convert_nested=False)
+        return dataclass_to_dict(self, exclude_empty=True, convert_nested=False)
 
     def create_connection(self) -> Connection:
         """Create and return a new database connection.
@@ -71,27 +70,11 @@ class SqliteConfig(GenericDatabaseConfig):
         import sqlite3
 
         try:
-            return sqlite3.connect(**self.connection_config_dict)
+            return sqlite3.connect(**self.connection_config_dict)  # type: ignore[no-any-return,unused-ignore]
         except Exception as e:
             msg = f"Could not configure the SQLite connection. Error: {e!s}"
             raise ImproperConfigurationError(msg) from e
 
-    @contextmanager
-    def lifespan(self, *args: Any, **kwargs: Any) -> Generator[None, None, None]:
-        """Manage the lifecycle of a database connection.
-
-        Yields:
-            None
-
-        Raises:
-            ImproperConfigurationError: If the connection could not be established.
-        """
-        connection = self.create_connection()
-        try:
-            yield
-        finally:
-            connection.close()
-
     @contextmanager
     def provide_connection(self, *args: Any, **kwargs: Any) -> Generator[Connection, None, None]:
         """Create and provide a database connection.

sqlspec/base.py

@@ -0,0 +1,87 @@
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator, Awaitable, Generator
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from dataclasses import dataclass
+from typing import Any, ClassVar, Generic, TypeVar, Union
+
+__all__ = (
+    "DatabaseConfigProtocol",
+    "GenericPoolConfig",
+    "NoPoolConfig",
+)
+
+ConnectionT = TypeVar("ConnectionT")
+PoolT = TypeVar("PoolT")
+
+
+@dataclass
+class DatabaseConfigProtocol(Generic[ConnectionT, PoolT], ABC):
+    """Protocol defining the interface for database configurations."""
+
+    __is_async__: ClassVar[bool] = False
+    __supports_connection_pooling__: ClassVar[bool] = False
+
+    @abstractmethod
+    def create_connection(self) -> Union[ConnectionT, Awaitable[ConnectionT]]:
+        """Create and return a new database connection."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def provide_connection(
+        self, *args: Any, **kwargs: Any
+    ) -> Union[
+        Generator[ConnectionT, None, None],
+        AsyncGenerator[ConnectionT, None],
+        AbstractContextManager[ConnectionT],
+        AbstractAsyncContextManager[ConnectionT],
+    ]:
+        """Provide a database connection context manager."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def connection_config_dict(self) -> dict[str, Any]:
+        """Return the connection configuration as a dict."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def create_pool(self) -> Union[PoolT, Awaitable[PoolT]]:
+        """Create and return connection pool."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def provide_pool(
+        self, *args: Any, **kwargs: Any
+    ) -> Union[PoolT, Awaitable[PoolT], AbstractContextManager[PoolT], AbstractAsyncContextManager[PoolT]]:
+        """Provide pool instance."""
+        raise NotImplementedError
+
+    @property
+    def is_async(self) -> bool:
+        """Return whether the configuration is for an async database."""
+        return self.__is_async__
+
+    @property
+    def support_connection_pooling(self) -> bool:
+        """Return whether the configuration supports connection pooling."""
+        return self.__supports_connection_pooling__
+
+
+class NoPoolConfig(DatabaseConfigProtocol[ConnectionT, None]):
+    """Base class for database configurations that do not implement a pool."""
+
+    def create_pool(self) -> None:
+        """This database backend has not implemented the pooling configurations."""
+
+    def provide_pool(self, *args: Any, **kwargs: Any) -> None:
+        """This database backend has not implemented the pooling configurations."""
+
+
+@dataclass
+class GenericPoolConfig:
+    """Generic Database Pool Configuration."""
+
+
+@dataclass
+class GenericDatabaseConfig:
+    """Generic Database Configuration."""

sqlspec/filters.py

@@ -2,11 +2,11 @@
 
 from __future__ import annotations
 
-from abc import ABC, abstractmethod
+from abc import ABC
 from collections import abc  # noqa: TC003
 from dataclasses import dataclass
 from datetime import datetime  # noqa: TC003
-from typing import Generic, Literal
+from typing import Generic, Literal, Protocol
 
 from typing_extensions import TypeVar
 
@@ -25,11 +25,14 @@ __all__ = (
 )
 
 T = TypeVar("T")
+StatementT = TypeVar("StatementT", bound="str")
 
 
-class StatementFilter(ABC):
-    @abstractmethod
-    def append_to_statement(self, statement: str) -> str:
+class StatementFilter(Protocol):
+    """Protocol for filters that can be appended to a statement."""
+
+    def append_to_statement(self, statement: StatementT) -> StatementT:
+        """Append the filter to the statement."""
         return statement