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

sqlspec/adapters/psycopg/config/_common.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from sqlspec.config import GenericDatabaseConfig, GenericPoolConfig
+from sqlspec.typing import Empty
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from typing import Any
+
+    from psycopg import AsyncConnection, Connection
+    from psycopg_pool import AsyncConnectionPool, ConnectionPool
+
+    from sqlspec.typing import EmptyType
+
+
+__all__ = (
+    "PsycoPgGenericDatabaseConfig",
+    "PsycoPgGenericPoolConfig",
+)
+
+
+ConnectionT = TypeVar("ConnectionT", bound="Connection | AsyncConnection")
+PoolT = TypeVar("PoolT", bound="ConnectionPool | AsyncConnectionPool")
+
+
+@dataclass
+class PsycoPgGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
+    """Configuration for Psycopg connection pools.
+
+    This class provides configuration options for both synchronous and asynchronous Psycopg
+    database connection pools. It supports all standard Psycopg connection parameters and pool-specific
+    settings.([1](https://www.psycopg.org/psycopg3/docs/api/pool.html))
+    """
+
+    conninfo: str | EmptyType = Empty
+    """Connection string in libpq format"""
+    kwargs: dict[str, Any] | EmptyType = Empty
+    """Additional connection parameters"""
+    min_size: int | EmptyType = Empty
+    """Minimum number of connections in the pool"""
+    max_size: int | EmptyType = Empty
+    """Maximum number of connections in the pool"""
+    name: str | EmptyType = Empty
+    """Name of the connection pool"""
+    timeout: float | EmptyType = Empty
+    """Timeout for acquiring connections"""
+    max_waiting: int | EmptyType = Empty
+    """Maximum number of waiting clients"""
+    max_lifetime: float | EmptyType = Empty
+    """Maximum connection lifetime"""
+    max_idle: float | EmptyType = Empty
+    """Maximum idle time for connections"""
+    reconnect_timeout: float | EmptyType = Empty
+    """Time between reconnection attempts"""
+    num_workers: int | EmptyType = Empty
+    """Number of background workers"""
+    configure: Callable[[ConnectionT], None] | EmptyType = Empty
+    """Callback to configure new connections"""
+
+
+@dataclass
+class PsycoPgGenericDatabaseConfig(Generic[PoolT, ConnectionT], GenericDatabaseConfig):
+    """Psycopg database Configuration.
+
+    This class provides the base configuration for Psycopg database connections, extending
+    the generic database configuration with Psycopg-specific settings.([1](https://www.psycopg.org/psycopg3/docs/api/connections.html))
+
+    The configuration supports all standard Psycopg connection parameters and can be used
+    with both synchronous and asynchronous connections.([2](https://www.psycopg.org/psycopg3/docs/api/connections.html))
+    """

sqlspec/adapters/psycopg/config/_sync.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from psycopg import Connection
+from psycopg_pool import ConnectionPool
+
+from sqlspec.adapters.psycopg.config._common import (
+    PsycoPgGenericDatabaseConfig,
+    PsycoPgGenericPoolConfig,
+)
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.typing import dataclass_to_dict
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from typing import Any
+
+
+__all__ = (
+    "PsycoPgSyncDatabaseConfig",
+    "PsycoPgSyncPoolConfig",
+)
+
+
+@dataclass
+class PsycoPgSyncPoolConfig(PsycoPgGenericPoolConfig[ConnectionPool, Connection]):
+    """Sync Psycopg Pool Config"""
+
+
+@dataclass
+class PsycoPgSyncDatabaseConfig(PsycoPgGenericDatabaseConfig[ConnectionPool, Connection]):
+    """Sync Psycopg database Configuration."""
+
+    pool_config: PsycoPgSyncPoolConfig | None = None
+    """Psycopg Pool configuration"""
+    pool_instance: ConnectionPool | None = None
+    """Optional pool to use"""
+
+    @property
+    def pool_config_dict(self) -> dict[str, Any]:
+        """Return the pool configuration as a dict."""
+        if self.pool_config:
+            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)
+
+    def create_pool(self) -> ConnectionPool:
+        """Create and return a connection pool."""
+        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 = ConnectionPool(**pool_config)
+        if self.pool_instance is None:
+            msg = "Could not configure the 'pool_instance'. Please check your configuration."  # type: ignore[unreachable]
+            raise ImproperConfigurationError(msg)
+        return self.pool_instance
+
+    def provide_pool(self, *args: Any, **kwargs: Any) -> ConnectionPool:
+        """Create and return a connection pool."""
+        return self.create_pool()
+
+    @contextmanager
+    def provide_connection(self, *args: Any, **kwargs: Any) -> Generator[Connection, None, None]:
+        """Create and provide a database connection."""
+        pool = self.provide_pool(*args, **kwargs)
+        with pool.connection() as connection:
+            yield connection

sqlspec/adapters/sqlite/config.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from sqlspec.config import GenericDatabaseConfig
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.typing import Empty, EmptyType, dataclass_to_dict
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from sqlite3 import Connection
+
+__all__ = ("SqliteConfig",)
+
+
+@dataclass
+class SqliteConfig(GenericDatabaseConfig):
+    """Configuration for SQLite database connections.
+
+    This class provides configuration options for SQLite database connections, wrapping all parameters
+    available to sqlite3.connect().
+
+    For details see: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect
+    """
+
+    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[Connection] | 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 sqlite3.connect() function.
+        """
+        return dataclass_to_dict(self, exclude_empty=True, convert_nested=False)
+
+    def create_connection(self) -> Connection:
+        """Create and return a new database connection.
+
+        Returns:
+            A new SQLite connection instance.
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established.
+        """
+        import sqlite3
+
+        try:
+            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 provide_connection(self, *args: Any, **kwargs: Any) -> Generator[Connection, None, None]:
+        """Create and provide a database connection.
+
+        Yields:
+            A SQLite connection instance.
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established.
+        """
+        connection = self.create_connection()
+        try:
+            yield connection
+        finally:
+            connection.close()

sqlspec/config.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+__all__ = (
+    "GenericDatabaseConfig",
+    "GenericPoolConfig",
+)
+
+
+@dataclass
+class GenericDatabaseConfig:
+    """Generic Database Configuration."""
+
+
+@dataclass
+class GenericPoolConfig:
+    """Generic Database Pool Configuration."""

sqlspec/exceptions.py

@@ -2,6 +2,17 @@ from __future__ import annotations
 
 from typing import Any
 
+__all__ = (
+    "ImproperConfigurationError",
+    "IntegrityError",
+    "MissingDependencyError",
+    "MultipleResultsFoundError",
+    "NotFoundError",
+    "RepositoryError",
+    "SQLSpecError",
+    "SerializationError",
+)
+
 
 class SQLSpecError(Exception):
     """Base exception class from which all Advanced Alchemy exceptions inherit."""
@@ -47,6 +58,24 @@ class MissingDependencyError(SQLSpecError, ImportError):
         )
 
 
+class SQLLoadingError(SQLSpecError):
+    """Issues loading referenced SQL file."""
+
+    def __init__(self, message: str | None = None) -> None:
+        if message is None:
+            message = "Issues loading referenced SQL file."
+        super().__init__(message)
+
+
+class SQLParsingError(SQLSpecError):
+    """Issues parsing SQL statements."""
+
+    def __init__(self, message: str | None = None) -> None:
+        if message is None:
+            message = "Issues parsing SQL statement."
+        super().__init__(message)
+
+
 class ImproperConfigurationError(SQLSpecError):
     """Improper Configuration error.
 

sqlspec/extensions/litestar/plugin.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from litestar.plugins import InitPluginProtocol
+
+if TYPE_CHECKING:
+    from litestar.config.app import AppConfig
+
+
+T = TypeVar("T")
+
+
+class SQLSpecPlugin(InitPluginProtocol):
+    """Aiosql plugin."""
+
+    __slots__ = ("_config",)
+
+    def __init__(self, config: Any) -> None:
+        """Initialize ``AiosqlPlugin``.
+
+        Args:
+            config: configure and start Aiosql.
+        """
+        self._config = config
+
+    def on_app_init(self, app_config: AppConfig) -> AppConfig:
+        """Configure application for use with Aiosql.
+
+        Args:
+            app_config: The :class:`AppConfig <.config.app.AppConfig>` instance.
+        """
+        app_config.signature_namespace.update(self._config.signature_namespace)
+        return app_config

sqlspec/filters.py

@@ -2,35 +2,41 @@
 
 from __future__ import annotations
 
-from collections import abc  # noqa: TCH003
+from abc import ABC
+from collections import abc  # noqa: TC003
 from dataclasses import dataclass
-from datetime import datetime  # noqa: TCH003
-from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar
+from datetime import datetime  # noqa: TC003
+from typing import Generic, Literal, Protocol
 
-if TYPE_CHECKING:
-    from typing_extensions import TypeAlias
-
-T = TypeVar("T")
+from typing_extensions import TypeVar
 
 __all__ = (
     "BeforeAfter",
     "CollectionFilter",
-    "FilterTypes",
+    "InAnyFilter",
     "LimitOffset",
     "NotInCollectionFilter",
     "NotInSearchFilter",
     "OnBeforeAfter",
     "OrderBy",
+    "PaginationFilter",
     "SearchFilter",
+    "StatementFilter",
 )
 
+T = TypeVar("T")
+
+
+class StatementFilter(Protocol):
+    """Protocol for filters that can be appended to a statement."""
 
-FilterTypes: TypeAlias = "BeforeAfter | OnBeforeAfter | CollectionFilter[Any] | LimitOffset | OrderBy | SearchFilter | NotInCollectionFilter[Any] | NotInSearchFilter"
-"""Aggregate type alias of the types supported for collection filtering."""
+    def append_to_statement(self, statement: str) -> str:
+        """Append the filter to the statement."""
+        return statement
 
 
 @dataclass
-class BeforeAfter:
+class BeforeAfter(StatementFilter):
     """Data required to filter a query on a ``datetime`` column."""
 
     field_name: str
@@ -42,7 +48,7 @@ class BeforeAfter:
 
 
 @dataclass
-class OnBeforeAfter:
+class OnBeforeAfter(StatementFilter):
     """Data required to filter a query on a ``datetime`` column."""
 
     field_name: str
@@ -53,8 +59,12 @@ class OnBeforeAfter:
     """Filter results where field on or later than this."""
 
 
+class InAnyFilter(StatementFilter, ABC):
+    """Subclass for methods that have a `prefer_any` attribute."""
+
+
 @dataclass
-class CollectionFilter(Generic[T]):
+class CollectionFilter(InAnyFilter, Generic[T]):
     """Data required to construct a ``WHERE ... IN (...)`` clause."""
 
     field_name: str
@@ -66,7 +76,7 @@ class CollectionFilter(Generic[T]):
 
 
 @dataclass
-class NotInCollectionFilter(Generic[T]):
+class NotInCollectionFilter(InAnyFilter, Generic[T]):
     """Data required to construct a ``WHERE ... NOT IN (...)`` clause."""
 
     field_name: str
@@ -77,8 +87,12 @@ class NotInCollectionFilter(Generic[T]):
     An empty list or ``None`` will return all rows."""
 
 
+class PaginationFilter(StatementFilter, ABC):
+    """Subclass for methods that function as a pagination type."""
+
+
 @dataclass
-class LimitOffset:
+class LimitOffset(PaginationFilter):
     """Data required to add limit/offset filtering to a query."""
 
     limit: int
@@ -88,7 +102,7 @@ class LimitOffset:
 
 
 @dataclass
-class OrderBy:
+class OrderBy(StatementFilter):
     """Data required to construct a ``ORDER BY ...`` clause."""
 
     field_name: str
@@ -98,24 +112,17 @@ class OrderBy:
 
 
 @dataclass
-class SearchFilter:
+class SearchFilter(StatementFilter):
     """Data required to construct a ``WHERE field_name LIKE '%' || :value || '%'`` clause."""
 
-    field_name: str
-    """Name of the model attribute to sort on."""
+    field_name: str | set[str]
+    """Name of the model attribute to search on."""
     value: str
-    """Values for ``LIKE`` clause."""
+    """Search value."""
     ignore_case: bool | None = False
     """Should the search be case insensitive."""
 
 
 @dataclass
-class NotInSearchFilter:
+class NotInSearchFilter(SearchFilter):
     """Data required to construct a ``WHERE field_name NOT LIKE '%' || :value || '%'`` clause."""
-
-    field_name: str
-    """Name of the model attribute to search on."""
-    value: str
-    """Values for ``NOT LIKE`` clause."""
-    ignore_case: bool | None = False
-    """Should the search be case insensitive."""