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

sqlspec/__metadata__.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from importlib.metadata import PackageNotFoundError, metadata, version
 
-__all__ = ["__version__", "__project__"]
+__all__ = ["__project__", "__version__"]
 
 try:
     __version__ = version("sqlspec")

sqlspec/_serialization.py

@@ -14,7 +14,7 @@ try:
 except ImportError:
     try:
         from orjson import dumps as _encode_json  # pyright: ignore[reportMissingImports]
-        from orjson import loads as decode_json  # type: ignore[no-redef,assignment]
+        from orjson import loads as decode_json  # type: ignore[no-redef]
 
         def encode_json(data: Any) -> str:
             return _encode_json(data).decode("utf-8")  # type: ignore[no-any-return]

sqlspec/_typing.py

@@ -0,0 +1,112 @@
+"""This is a simple wrapper around a few important classes in each library.
+
+This is used to ensure compatibility when one or more of the libraries are installed.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    ClassVar,
+    Protocol,
+    cast,
+    runtime_checkable,
+)
+
+from typing_extensions import TypeVar, dataclass_transform
+
+T = TypeVar("T")
+T_co = TypeVar("T_co", covariant=True)
+
+
+try:
+    from pydantic import BaseModel, FailFast, TypeAdapter
+
+    PYDANTIC_INSTALLED = True
+except ImportError:
+
+    @runtime_checkable
+    class BaseModel(Protocol):  # type: ignore[no-redef]
+        """Placeholder Implementation"""
+
+        model_fields: ClassVar[dict[str, Any]]
+
+        def model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]:
+            """Placeholder"""
+            return {}
+
+    @runtime_checkable
+    class TypeAdapter(Protocol[T_co]):  # type: ignore[no-redef]
+        """Placeholder Implementation"""
+
+        def __init__(
+            self,
+            type: Any,  # noqa: A002
+            *,
+            config: Any | None = None,
+            _parent_depth: int = 2,
+            module: str | None = None,
+        ) -> None:
+            """Init"""
+
+        def validate_python(
+            self,
+            object: Any,  # noqa: A002
+            /,
+            *,
+            strict: bool | None = None,
+            from_attributes: bool | None = None,
+            context: dict[str, Any] | None = None,
+        ) -> T_co:
+            """Stub"""
+            return cast("T_co", object)
+
+    @runtime_checkable
+    class FailFast(Protocol):  # type: ignore[no-redef]
+        """Placeholder Implementation for FailFast"""
+
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            """Init"""
+
+    PYDANTIC_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
+
+try:
+    from msgspec import (
+        UNSET,
+        Struct,
+        UnsetType,  # pyright: ignore[reportAssignmentType]
+        convert,
+    )
+
+    MSGSPEC_INSTALLED: bool = True
+except ImportError:
+    import enum
+
+    @dataclass_transform()
+    @runtime_checkable
+    class Struct(Protocol):  # type: ignore[no-redef]
+        """Placeholder Implementation"""
+
+        __struct_fields__: ClassVar[tuple[str, ...]]
+
+    def convert(*args: Any, **kwargs: Any) -> Any:  # type: ignore[no-redef]
+        """Placeholder implementation"""
+        return {}
+
+    class UnsetType(enum.Enum):  # type: ignore[no-redef]
+        UNSET = "UNSET"
+
+    UNSET = UnsetType.UNSET  # pyright: ignore[reportConstantRedefinition]
+    MSGSPEC_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
+
+__all__ = (
+    "MSGSPEC_INSTALLED",
+    "PYDANTIC_INSTALLED",
+    "UNSET",
+    "BaseModel",
+    "FailFast",
+    "Struct",
+    "TypeAdapter",
+    "UnsetType",
+    "convert",
+)

sqlspec/adapters/adbc/config.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeVar
+
+from sqlspec.config import GenericDatabaseConfig
+from sqlspec.utils.empty import Empty
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from typing import Any
+
+    from adbc_driver_manager.dbapi import Connection, Cursor
+
+    from sqlspec.utils.empty import EmptyType
+
+__all__ = ("AdbcDatabaseConfig",)
+
+ConnectionT = TypeVar("ConnectionT", bound="Connection")
+CursorT = TypeVar("CursorT", bound="Cursor")
+
+
+@dataclass
+class AdbcDatabaseConfig(GenericDatabaseConfig):
+    """Configuration for ADBC connections.
+
+    This class provides configuration options for ADBC database connections using the
+    ADBC Driver Manager.([1](https://arrow.apache.org/adbc/current/python/api/adbc_driver_manager.html))
+    """
+
+    uri: str | EmptyType = Empty
+    """Database URI"""
+    driver_name: str | EmptyType = Empty
+    """Name of the ADBC driver to use"""
+    db_kwargs: dict[str, Any] | None = None
+    """Additional database-specific connection parameters"""
+
+    @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
+        }
+
+    @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
+
+        with connect(**self.connection_params) as connection:
+            yield connection

sqlspec/adapters/aiosqlite/__init__.py

@@ -0,0 +1,3 @@
+from .config import AiosqliteConfig
+
+__all__ = ("AiosqliteConfig",)

sqlspec/adapters/aiosqlite/config.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.config import GenericDatabaseConfig
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.utils.dataclass import simple_asdict
+from sqlspec.utils.empty import Empty, EmptyType
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+    from sqlite3 import Connection as SQLite3Connection
+    from typing import Literal
+
+    from aiosqlite import Connection
+
+__all__ = ("AiosqliteConfig",)
+
+
+@dataclass
+class AiosqliteConfig(GenericDatabaseConfig):
+    """Configuration for Aiosqlite database connections.
+
+    This class provides configuration options for Aiosqlite database connections, wrapping all parameters
+    available to aiosqlite.connect().
+
+    For details see: https://github.com/omnilib/aiosqlite/blob/main/aiosqlite/__init__.pyi
+    """
+
+    database: str
+    """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
+    """How many seconds the connection should wait before raising an OperationalError when a table is locked. If another thread or process has acquired a shared lock, a wait for the specified timeout occurs."""
+
+    detect_types: int | EmptyType = Empty
+    """Control whether and how data types are detected. It can be 0 (default) or a combination of PARSE_DECLTYPES and PARSE_COLNAMES."""
+
+    isolation_level: Literal["DEFERRED", "IMMEDIATE", "EXCLUSIVE"] | None | EmptyType = Empty
+    """The isolation_level of the connection. This can be None for autocommit mode or one of "DEFERRED", "IMMEDIATE" or "EXCLUSIVE"."""
+
+    check_same_thread: bool | EmptyType = Empty
+    """If True (default), ProgrammingError is raised if the database connection is used by a thread other than the one that created it. If False, the connection may be shared across multiple threads."""
+
+    factory: type[SQLite3Connection] | EmptyType = Empty
+    """A custom Connection class factory. If given, must be a callable that returns a Connection instance."""
+
+    cached_statements: int | EmptyType = Empty
+    """The number of statements that SQLite will cache for this connection. The default is 128."""
+
+    uri: bool | EmptyType = Empty
+    """If set to True, database is interpreted as a URI with supported options."""
+
+    @property
+    def connection_config_dict(self) -> dict[str, Any]:
+        """Return the connection configuration as a dict.
+
+        Returns:
+            A string keyed dict of config kwargs for the aiosqlite.connect() function.
+        """
+        return simple_asdict(self, exclude_empty=True, convert_nested=False)
+
+    async def create_connection(self) -> Connection:
+        """Create and return a new database connection.
+
+        Returns:
+            A new Aiosqlite connection instance.
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established.
+        """
+        import aiosqlite
+
+        try:
+            return await aiosqlite.connect(**self.connection_config_dict)
+        except Exception as e:
+            msg = f"Could not configure the Aiosqlite connection. Error: {e!s}"
+            raise ImproperConfigurationError(msg) from e
+
+    @asynccontextmanager
+    async def lifespan(self, *args: Any, **kwargs: Any) -> AsyncGenerator[None, None]:
+        """Manage the lifecycle of a database connection.
+
+        Yields:
+            None
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established.
+        """
+        connection = await self.create_connection()
+        try:
+            yield
+        finally:
+            await connection.close()
+
+    @asynccontextmanager
+    async def provide_connection(self, *args: Any, **kwargs: Any) -> AsyncGenerator[Connection, None]:
+        """Create and provide a database connection.
+
+        Yields:
+            An Aiosqlite connection instance.
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established.
+        """
+        connection = await self.create_connection()
+        try:
+            yield connection
+        finally:
+            await connection.close()

sqlspec/adapters/asyncmy/__init__.py

@@ -0,0 +1,3 @@
+from .config import AsyncMyConfig, AsyncmyPoolConfig
+
+__all__ = ("AsyncMyConfig", "AsyncmyPoolConfig")

sqlspec/adapters/asyncmy/config.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeVar
+
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.utils.dataclass import simple_asdict
+from sqlspec.utils.empty import Empty, EmptyType
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+    from typing import Any
+
+    from asyncmy.connection import Connection
+    from asyncmy.cursors import Cursor, DictCursor
+    from asyncmy.pool import Pool
+
+__all__ = (
+    "AsyncMyConfig",
+    "AsyncmyPoolConfig",
+)
+
+
+T = TypeVar("T")
+
+
+@dataclass
+class AsyncmyPoolConfig:
+    """Configuration for Asyncmy's connection pool.
+
+    This class provides configuration options for Asyncmy database connection pools.
+
+    For details see: https://github.com/long2ice/asyncmy
+    """
+
+    host: str | EmptyType = Empty
+    """Host where the database server is located."""
+
+    user: str | EmptyType = Empty
+    """The username used to authenticate with the database."""
+
+    password: str | EmptyType = Empty
+    """The password used to authenticate with the database."""
+
+    database: str | EmptyType = Empty
+    """The database name to use."""
+
+    port: int | EmptyType = Empty
+    """The TCP/IP port of the MySQL server. Must be an integer."""
+
+    unix_socket: str | EmptyType = Empty
+    """The location of the Unix socket file."""
+
+    charset: str | EmptyType = Empty
+    """The character set to use for the connection."""
+
+    connect_timeout: float | EmptyType = Empty
+    """Timeout before throwing an error when connecting."""
+
+    read_default_file: str | EmptyType = Empty
+    """MySQL configuration file to read."""
+
+    read_default_group: str | EmptyType = Empty
+    """Group to read from the configuration file."""
+
+    autocommit: bool | EmptyType = Empty
+    """If True, autocommit mode will be enabled."""
+
+    local_infile: bool | EmptyType = Empty
+    """If True, enables LOAD LOCAL INFILE."""
+
+    ssl: dict[str, Any] | bool | EmptyType = Empty
+    """If present, a dictionary of SSL connection parameters, or just True."""
+
+    sql_mode: str | EmptyType = Empty
+    """Default SQL_MODE to use."""
+
+    init_command: str | EmptyType = Empty
+    """Initial SQL statement to execute once connected."""
+
+    cursor_class: type[Cursor] | type[DictCursor] | EmptyType = Empty
+    """Custom cursor class to use."""
+
+    minsize: int | EmptyType = Empty
+    """Minimum number of connections to keep in the pool."""
+
+    maxsize: int | EmptyType = Empty
+    """Maximum number of connections allowed in the pool."""
+
+    echo: bool | EmptyType = Empty
+    """If True, logging will be enabled for all SQL statements."""
+
+    pool_recycle: int | EmptyType = Empty
+    """Number of seconds after which a connection is recycled."""
+
+    @property
+    def pool_config_dict(self) -> dict[str, Any]:
+        """Return the pool configuration as a dict.
+
+        Returns:
+            A string keyed dict of config kwargs for the Asyncmy create_pool function.
+        """
+        return simple_asdict(self, exclude_empty=True, convert_nested=False)
+
+
+@dataclass
+class AsyncMyConfig:
+    """Asyncmy Configuration."""
+
+    pool_config: AsyncmyPoolConfig | None = None
+    """Asyncmy Pool configuration"""
+
+    pool_instance: Pool | None = None
+    """Optional pool to use.
+
+    If set, the plugin will use the provided pool rather than instantiate one.
+    """
+
+    @property
+    def pool_config_dict(self) -> dict[str, Any]:
+        """Return the pool configuration as a dict.
+
+        Returns:
+            A string keyed dict of config kwargs for the Asyncmy create_pool function.
+        """
+        if self.pool_config:
+            return simple_asdict(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)
+
+    async def create_pool(self) -> Pool:
+        """Return a pool. If none exists yet, create one.
+
+        Returns:
+            Getter that returns the pool instance used by the plugin.
+
+        Raises:
+            ImproperConfigurationError: If the pool could not be created.
+        """
+        if self.pool_instance is not None:
+            return self.pool_instance
+
+        if self.pool_config is None:
+            msg = "One of 'pool_config' or 'pool_instance' must be provided."
+            raise ImproperConfigurationError(msg)
+
+        try:
+            import asyncmy
+
+            self.pool_instance = await asyncmy.create_pool(**self.pool_config_dict)
+            return self.pool_instance
+        except Exception as e:
+            msg = f"Could not configure the Asyncmy pool. Error: {e!s}"
+            raise ImproperConfigurationError(msg) from e
+
+    async def provide_pool(self, *args: Any, **kwargs: Any) -> Pool:
+        """Create a pool instance.
+
+        Returns:
+            A Pool instance.
+        """
+        return await self.create_pool()
+
+    @asynccontextmanager
+    async def lifespan(self, *args: Any, **kwargs: Any) -> AsyncGenerator[None, None]:
+        """Manage the lifecycle of a database connection pool.
+
+        Yields:
+            None
+
+        Raises:
+            ImproperConfigurationError: If the pool could not be established.
+        """
+        pool = await self.create_pool()
+        try:
+            yield
+        finally:
+            pool.close()
+            await pool.wait_closed()
+
+    @asynccontextmanager
+    async def provide_connection(self, *args: Any, **kwargs: Any) -> AsyncGenerator[Connection, None]:
+        """Create and provide a database connection.
+
+        Yields:
+            An Asyncmy connection instance.
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established.
+        """
+        pool = await self.provide_pool(*args, **kwargs)
+        async with pool.acquire() as connection:
+            yield connection

sqlspec/adapters/asyncpg/config.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeVar
+
+from asyncpg import Record
+from asyncpg import create_pool as asyncpg_create_pool
+
+from sqlspec._serialization import decode_json, encode_json
+from sqlspec.config import GenericDatabaseConfig, GenericPoolConfig
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.utils.dataclass import simple_asdict
+from sqlspec.utils.empty import Empty, EmptyType
+
+if TYPE_CHECKING:
+    from asyncio import AbstractEventLoop
+    from collections.abc import AsyncGenerator, Awaitable, Callable, Coroutine
+    from typing import Any
+
+    from asyncpg.connection import Connection
+    from asyncpg.pool import Pool, PoolConnectionProxy
+
+__all__ = (
+    "AsyncPgConfig",
+    "AsyncPgPoolConfig",
+)
+
+
+T = TypeVar("T")
+
+
+@dataclass
+class AsyncPgPoolConfig(GenericPoolConfig):
+    """Configuration for Asyncpg's :class:`Pool <asyncpg.pool.Pool>`.
+
+    For details see: https://magicstack.github.io/asyncpg/current/api/index.html#connection-pools
+    """
+
+    dsn: str
+    """Connection arguments specified using as a single string in the following format: ``postgres://user:pass@host:port/database?option=value``
+    """
+    connect_kwargs: dict[Any, Any] | None | EmptyType = Empty
+    """A dictionary of arguments which will be passed directly to the ``connect()`` method as keyword arguments.
+    """
+    connection_class: type[Connection] | None | EmptyType = Empty
+    """The class to use for connections. Must be a subclass of Connection
+    """
+    record_class: type[Record] | EmptyType = Empty
+    """If specified, the class to use for records returned by queries on the connections in this pool. Must be a subclass of Record."""
+
+    min_size: int | EmptyType = Empty
+    """The number of connections to keep open inside the connection pool."""
+    max_size: int | EmptyType = Empty
+    """The number of connections to allow in connection pool “overflow”, that is connections that can be opened above
+    and beyond the pool_size setting, which defaults to 10."""
+
+    max_queries: int | EmptyType = Empty
+    """Number of queries after a connection is closed and replaced with a new connection.
+    """
+    max_inactive_connection_lifetime: float | EmptyType = Empty
+    """Number of seconds after which inactive connections in the pool will be closed. Pass 0 to disable this mechanism."""
+
+    setup: Coroutine[None, type[Connection], Any] | EmptyType = Empty
+    """A coroutine to prepare a connection right before it is returned from Pool.acquire(). An example use case would be to automatically set up notifications listeners for all connections of a pool."""
+    init: Coroutine[None, type[Connection], Any] | EmptyType = Empty
+    """A coroutine to prepare a connection right before it is returned from Pool.acquire(). An example use case would be to automatically set up notifications listeners for all connections of a pool."""
+
+    loop: AbstractEventLoop | EmptyType = Empty
+    """An asyncio event loop instance. If None, the default event loop will be used."""
+
+
+@dataclass
+class AsyncPgConfig(GenericDatabaseConfig):
+    """Asyncpg Configuration."""
+
+    pool_config: AsyncPgPoolConfig | None = None
+    """Asyncpg Pool configuration"""
+    json_deserializer: Callable[[str], Any] = decode_json
+    """For dialects that support the :class:`JSON <sqlalchemy.types.JSON>` datatype, this is a Python callable that will
+    convert a JSON string to a Python object. By default, this is set to SQLSpec's
+    :attr:`decode_json() <sqlspec._serialization.decode_json>` function."""
+    json_serializer: Callable[[Any], str] = encode_json
+    """For dialects that support the JSON datatype, this is a Python callable that will render a given object as JSON.
+    By default, SQLSpec's :attr:`encode_json() <sqlspec._serialization.encode_json>` is used."""
+    pool_instance: Pool | None = None
+    """Optional pool to use.
+
+    If set, the plugin will use the provided pool rather than instantiate one.
+    """
+
+    @property
+    def pool_config_dict(self) -> dict[str, Any]:
+        """Return the pool configuration as a dict.
+
+        Returns:
+            A string keyed dict of config kwargs for the Asyncpg :func:`create_pool <asyncpg.pool.create_pool>`
+            function.
+        """
+        if self.pool_config:
+            return simple_asdict(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)
+
+    async def create_pool(self) -> Pool:
+        """Return a pool. If none exists yet, create one.
+
+        Returns:
+            Getter that returns the pool instance used by the plugin.
+        """
+        if self.pool_instance is not None:
+            return self.pool_instance
+
+        if self.pool_config is None:
+            msg = "One of 'pool_config' or 'pool_instance' must be provided."
+            raise ImproperConfigurationError(msg)
+
+        pool_config = self.pool_config_dict
+        self.pool_instance = await asyncpg_create_pool(**pool_config)
+        if self.pool_instance is None:
+            msg = "Could not configure the 'pool_instance'. Please check your configuration."
+            raise ImproperConfigurationError(
+                msg,
+            )
+        return self.pool_instance
+
+    @asynccontextmanager
+    async def lifespan(self, *args: Any, **kwargs) -> AsyncGenerator[None, None]:
+        db_pool = await self.create_pool()
+        try:
+            yield
+        finally:
+            db_pool.terminate()
+            await db_pool.close()
+
+    def provide_pool(self, *args: Any, **kwargs) -> Awaitable[Pool]:
+        """Create a pool instance.
+
+        Returns:
+            A Pool instance.
+        """
+        return self.create_pool()
+
+    @asynccontextmanager
+    async def provide_connection(
+        self, *args: Any, **kwargs: Any
+    ) -> AsyncGenerator[Connection | PoolConnectionProxy, None]:
+        """Create a connection instance.
+
+        Returns:
+            A connection instance.
+        """
+        db_pool = await self.provide_pool(*args, **kwargs)
+        async with db_pool.acquire() as connection:
+            yield connection