sqlspec 0.16.0__cp313-cp313-macosx_14_0_arm64.whl

sqlspec/exceptions.py

@@ -0,0 +1,193 @@
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any, Optional, Union
+
+__all__ = (
+    "FileNotFoundInStorageError",
+    "ImproperConfigurationError",
+    "IntegrityError",
+    "MissingDependencyError",
+    "MultipleResultsFoundError",
+    "NotFoundError",
+    "RepositoryError",
+    "SQLBuilderError",
+    "SQLConversionError",
+    "SQLFileNotFoundError",
+    "SQLFileParseError",
+    "SQLParsingError",
+    "SQLSpecError",
+    "SerializationError",
+    "StorageOperationFailedError",
+)
+
+
+class SQLSpecError(Exception):
+    """Base exception class for SQLSpec exceptions."""
+
+    detail: str
+
+    def __init__(self, *args: Any, detail: str = "") -> None:
+        """Initialize SQLSpecError.
+
+        Args:
+            *args: args are converted to :class:`str` before passing to :class:`Exception`
+            detail: detail of the exception.
+        """
+        str_args = [str(arg) for arg in args if arg]
+        if not detail:
+            if str_args:
+                detail, *str_args = str_args
+            elif hasattr(self, "detail"):
+                detail = self.detail
+        self.detail = detail
+        super().__init__(*str_args)
+
+    def __repr__(self) -> str:
+        if self.detail:
+            return f"{self.__class__.__name__} - {self.detail}"
+        return self.__class__.__name__
+
+    def __str__(self) -> str:
+        return " ".join((*self.args, self.detail)).strip()
+
+
+class MissingDependencyError(SQLSpecError, ImportError):
+    """Raised when a required dependency is not installed."""
+
+    def __init__(self, package: str, install_package: Optional[str] = None) -> None:
+        super().__init__(
+            f"Package {package!r} is not installed but required. You can install it by running "
+            f"'pip install sqlspec[{install_package or package}]' to install sqlspec with the required extra "
+            f"or 'pip install {install_package or package}' to install the package separately"
+        )
+
+
+class BackendNotRegisteredError(SQLSpecError):
+    """Raised when a requested storage backend key is not registered."""
+
+    def __init__(self, backend_key: str) -> None:
+        super().__init__(f"Storage backend '{backend_key}' is not registered. Please register it before use.")
+
+
+class SQLParsingError(SQLSpecError):
+    """Issues parsing SQL statements."""
+
+    def __init__(self, message: Optional[str] = None) -> None:
+        if message is None:
+            message = "Issues parsing SQL statement."
+        super().__init__(message)
+
+
+class SQLBuilderError(SQLSpecError):
+    """Issues Building or Generating SQL statements."""
+
+    def __init__(self, message: Optional[str] = None) -> None:
+        if message is None:
+            message = "Issues building SQL statement."
+        super().__init__(message)
+
+
+class SQLConversionError(SQLSpecError):
+    """Issues converting SQL statements."""
+
+    def __init__(self, message: Optional[str] = None) -> None:
+        if message is None:
+            message = "Issues converting SQL statement."
+        super().__init__(message)
+
+
+class ImproperConfigurationError(SQLSpecError):
+    """Raised when configuration is invalid or incomplete."""
+
+
+class SerializationError(SQLSpecError):
+    """Encoding or decoding of an object failed."""
+
+
+class RepositoryError(SQLSpecError):
+    """Base repository exception type."""
+
+
+class IntegrityError(RepositoryError):
+    """Data integrity error."""
+
+
+class NotFoundError(RepositoryError):
+    """An identity does not exist."""
+
+
+class MultipleResultsFoundError(RepositoryError):
+    """A single database result was required but more than one were found."""
+
+
+class StorageOperationFailedError(SQLSpecError):
+    """Raised when a storage backend operation fails (e.g., network, permission, API error)."""
+
+
+class FileNotFoundInStorageError(StorageOperationFailedError):
+    """Raised when a file or object is not found in the storage backend."""
+
+
+class SQLFileNotFoundError(SQLSpecError):
+    """Raised when a SQL file cannot be found."""
+
+    def __init__(self, name: str, path: "Optional[str]" = None) -> None:
+        """Initialize the error.
+
+        Args:
+            name: Name of the SQL file.
+            path: Optional path where the file was expected.
+        """
+        message = f"SQL file '{name}' not found at path: {path}" if path else f"SQL file '{name}' not found"
+        super().__init__(message)
+        self.name = name
+        self.path = path
+
+
+class SQLFileParseError(SQLSpecError):
+    """Raised when a SQL file cannot be parsed."""
+
+    def __init__(self, name: str, path: str, original_error: "Exception") -> None:
+        """Initialize the error.
+
+        Args:
+            name: Name of the SQL file.
+            path: Path to the SQL file.
+            original_error: The underlying parsing error.
+        """
+        message = f"Failed to parse SQL file '{name}' at {path}: {original_error}"
+        super().__init__(message)
+        self.name = name
+        self.path = path
+        self.original_error = original_error
+
+
+@contextmanager
+def wrap_exceptions(
+    wrap_exceptions: bool = True, suppress: "Optional[Union[type[Exception], tuple[type[Exception], ...]]]" = None
+) -> Generator[None, None, None]:
+    """Context manager for exception handling with optional suppression.
+
+    Args:
+        wrap_exceptions: If True, wrap exceptions in RepositoryError. If False, let them pass through.
+        suppress: Exception type(s) to suppress completely (like contextlib.suppress).
+                 If provided, these exceptions are caught and ignored.
+    """
+    try:
+        yield
+
+    except Exception as exc:
+        if suppress is not None and (
+            (isinstance(suppress, type) and isinstance(exc, suppress))
+            or (isinstance(suppress, tuple) and isinstance(exc, suppress))
+        ):
+            return  # Suppress this exception
+
+        # If it's already a SQLSpec exception, don't wrap it
+        if isinstance(exc, SQLSpecError):
+            raise
+
+        if wrap_exceptions is False:
+            raise
+        msg = "An error occurred during the operation."
+        raise RepositoryError(detail=msg) from exc

sqlspec/extensions/aiosql/__init__.py

@@ -0,0 +1,10 @@
+"""SQLSpec aiosql integration for loading SQL files.
+
+This module provides a simple way to load aiosql-style SQL files and use them
+with SQLSpec drivers. It focuses on just the file parsing functionality,
+returning SQL objects that work with existing SQLSpec execution.
+"""
+
+from sqlspec.extensions.aiosql.adapter import AiosqlAsyncAdapter, AiosqlSyncAdapter
+
+__all__ = ("AiosqlAsyncAdapter", "AiosqlSyncAdapter")

sqlspec/extensions/aiosql/adapter.py

@@ -0,0 +1,461 @@
+"""AioSQL adapter implementation for SQLSpec.
+
+This module provides adapter classes that implement the aiosql adapter protocols
+while using SQLSpec drivers under the hood. This enables users to load SQL queries
+from files using aiosql while leveraging all of SQLSpec's advanced features.
+"""
+
+import logging
+from collections.abc import AsyncGenerator, Generator
+from contextlib import asynccontextmanager, contextmanager
+from typing import TYPE_CHECKING, Any, ClassVar, Optional, TypeVar, Union, cast
+
+from sqlspec.core.result import SQLResult
+from sqlspec.core.statement import SQL, StatementConfig
+from sqlspec.exceptions import MissingDependencyError
+from sqlspec.typing import AIOSQL_INSTALLED
+
+if TYPE_CHECKING:
+    from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
+
+logger = logging.getLogger("sqlspec.extensions.aiosql")
+
+__all__ = ("AiosqlAsyncAdapter", "AiosqlSyncAdapter")
+
+T = TypeVar("T")
+
+
+class AsyncCursorLike:
+    def __init__(self, result: Any) -> None:
+        self.result = result
+
+    async def fetchall(self) -> list[Any]:
+        if isinstance(self.result, SQLResult) and self.result.data is not None:
+            return list(self.result.data)
+        return []
+
+    async def fetchone(self) -> Optional[Any]:
+        rows = await self.fetchall()
+        return rows[0] if rows else None
+
+
+class CursorLike:
+    def __init__(self, result: Any) -> None:
+        self.result = result
+
+    def fetchall(self) -> list[Any]:
+        if isinstance(self.result, SQLResult) and self.result.data is not None:
+            return list(self.result.data)
+        return []
+
+    def fetchone(self) -> Optional[Any]:
+        rows = self.fetchall()
+        return rows[0] if rows else None
+
+
+def _check_aiosql_available() -> None:
+    if not AIOSQL_INSTALLED:
+        msg = "aiosql"
+        raise MissingDependencyError(msg, "aiosql")
+
+
+def _normalize_dialect(dialect: "Union[str, Any, None]") -> str:
+    """Normalize dialect name for SQLGlot compatibility.
+
+    Args:
+        dialect: Original dialect name (can be str, Dialect, type[Dialect], or None)
+
+    Returns:
+        Converted dialect name compatible with SQLGlot
+    """
+    if dialect is None:
+        return "sql"
+
+    if hasattr(dialect, "__name__"):
+        dialect_str = str(dialect.__name__).lower()  # pyright: ignore
+    elif hasattr(dialect, "name"):
+        dialect_str = str(dialect.name).lower()  # pyright: ignore
+    elif isinstance(dialect, str):
+        dialect_str = dialect.lower()
+    else:
+        dialect_str = str(dialect).lower()
+
+    dialect_mapping = {
+        "postgresql": "postgres",
+        "psycopg": "postgres",
+        "asyncpg": "postgres",
+        "psqlpy": "postgres",
+        "sqlite3": "sqlite",
+        "aiosqlite": "sqlite",
+    }
+    return dialect_mapping.get(dialect_str, dialect_str)
+
+
+class _AiosqlAdapterBase:
+    """Base adapter class providing common functionality for aiosql integration."""
+
+    def __init__(self, driver: "Union[SyncDriverAdapterBase, AsyncDriverAdapterBase]") -> None:
+        """Initialize the base adapter.
+
+        Args:
+            driver: SQLSpec driver to use for execution.
+        """
+        _check_aiosql_available()
+        self.driver = driver
+
+    def process_sql(self, query_name: str, op_type: "Any", sql: str) -> str:
+        """Process SQL string for aiosql compatibility.
+
+        Args:
+            query_name: Name of the query
+            op_type: Operation type
+            sql: SQL string to process
+
+        Returns:
+            Processed SQL string
+        """
+        return sql
+
+    def _create_sql_object(self, sql: str, parameters: "Any" = None) -> SQL:
+        """Create SQL object with proper configuration.
+
+        Args:
+            sql: SQL string
+            parameters: Query parameters
+
+        Returns:
+            Configured SQL object
+        """
+        return SQL(
+            sql,
+            parameters,
+            config=StatementConfig(enable_validation=False),
+            dialect=_normalize_dialect(getattr(self.driver, "dialect", "sqlite")),
+        )
+
+
+class AiosqlSyncAdapter(_AiosqlAdapterBase):
+    """Synchronous adapter that implements aiosql protocol using SQLSpec drivers.
+
+    This adapter bridges aiosql's synchronous driver protocol with SQLSpec's sync drivers,
+    enabling queries loaded by aiosql to be executed with SQLSpec drivers.
+    """
+
+    is_aio_driver: ClassVar[bool] = False
+
+    def __init__(self, driver: "SyncDriverAdapterBase") -> None:
+        """Initialize the sync adapter.
+
+        Args:
+            driver: SQLSpec sync driver to use for execution
+        """
+        super().__init__(driver)
+
+    def select(
+        self, conn: Any, query_name: str, sql: str, parameters: "Any", record_class: Optional[Any] = None
+    ) -> Generator[Any, None, None]:
+        """Execute a SELECT query and return results as generator.
+
+        Args:
+            conn: Database connection (passed through to SQLSpec driver)
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+            record_class: Deprecated - use schema_type in driver.execute instead
+
+        Yields:
+            Query result rows
+
+        Note:
+            The record_class parameter is ignored for compatibility. Use schema_type
+            in driver.execute or _sqlspec_schema_type in parameters for type mapping.
+        """
+        if record_class is not None:
+            logger.warning(
+                "record_class parameter is deprecated and ignored. "
+                "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
+            )
+
+        result = self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
+
+        if isinstance(result, SQLResult) and result.data is not None:
+            yield from result.data
+
+    def select_one(
+        self, conn: Any, query_name: str, sql: str, parameters: "Any", record_class: Optional[Any] = None
+    ) -> Optional[dict[str, Any]]:
+        """Execute a SELECT query and return first result.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+            record_class: Deprecated - use schema_type in driver.execute instead
+
+        Returns:
+            First result row or None
+
+        Note:
+            The record_class parameter is ignored for compatibility. Use schema_type
+            in driver.execute or _sqlspec_schema_type in parameters for type mapping.
+        """
+        if record_class is not None:
+            logger.warning(
+                "record_class parameter is deprecated and ignored. "
+                "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
+            )
+
+        result = cast("SQLResult", self.driver.execute(self._create_sql_object(sql, parameters), connection=conn))
+
+        if hasattr(result, "data") and result.data and isinstance(result, SQLResult):
+            return cast("Optional[dict[str, Any]]", result.data[0])
+        return None
+
+    def select_value(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
+        """Execute a SELECT query and return first value of first row.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+
+        Returns:
+            First value of first row or None
+        """
+        row = self.select_one(conn, query_name, sql, parameters)
+        if row is None:
+            return None
+
+        if isinstance(row, dict):
+            return next(iter(row.values())) if row else None
+        if hasattr(row, "__getitem__"):
+            return row[0] if len(row) > 0 else None
+        return row
+
+    @contextmanager
+    def select_cursor(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Generator[Any, None, None]:
+        """Execute a SELECT query and return cursor context manager.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+
+        Yields:
+            Cursor-like object with results
+        """
+        result = self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
+
+        yield CursorLike(result)
+
+    def insert_update_delete(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> int:
+        """Execute INSERT/UPDATE/DELETE and return affected rows.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+
+        Returns:
+            Number of affected rows
+        """
+        result = cast("SQLResult", self.driver.execute(self._create_sql_object(sql, parameters), connection=conn))
+
+        return result.rows_affected if hasattr(result, "rows_affected") else 0
+
+    def insert_update_delete_many(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> int:
+        """Execute INSERT/UPDATE/DELETE with many parameter sets.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Sequence of parameter sets
+
+        Returns:
+            Number of affected rows
+        """
+        result = cast(
+            "SQLResult", self.driver.execute_many(self._create_sql_object(sql), parameters=parameters, connection=conn)
+        )
+
+        return result.rows_affected if hasattr(result, "rows_affected") else 0
+
+    def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
+        """Execute INSERT with RETURNING and return result.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+
+        Returns:
+            Returned value or None
+        """
+        return self.select_one(conn, query_name, sql, parameters)
+
+
+class AiosqlAsyncAdapter(_AiosqlAdapterBase):
+    """Asynchronous adapter that implements aiosql protocol using SQLSpec drivers.
+
+    This adapter bridges aiosql's async driver protocol with SQLSpec's async drivers,
+    enabling queries loaded by aiosql to be executed with SQLSpec async drivers.
+    """
+
+    is_aio_driver: ClassVar[bool] = True
+
+    def __init__(self, driver: "AsyncDriverAdapterBase") -> None:
+        """Initialize the async adapter.
+
+        Args:
+            driver: SQLSpec async driver to use for execution
+        """
+        super().__init__(driver)
+
+    async def select(
+        self, conn: Any, query_name: str, sql: str, parameters: "Any", record_class: Optional[Any] = None
+    ) -> list[Any]:
+        """Execute a SELECT query and return results as list.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+            record_class: Deprecated - use schema_type in driver.execute instead
+
+        Returns:
+            List of query result rows
+
+        Note:
+            The record_class parameter is ignored for compatibility. Use schema_type
+            in driver.execute or _sqlspec_schema_type in parameters for type mapping.
+        """
+        if record_class is not None:
+            logger.warning(
+                "record_class parameter is deprecated and ignored. "
+                "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
+            )
+
+        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
+
+        if hasattr(result, "data") and result.data is not None and isinstance(result, SQLResult):
+            return list(result.data)
+        return []
+
+    async def select_one(
+        self, conn: Any, query_name: str, sql: str, parameters: "Any", record_class: Optional[Any] = None
+    ) -> Optional[Any]:
+        """Execute a SELECT query and return first result.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+            record_class: Deprecated - use schema_type in driver.execute instead
+
+        Returns:
+            First result row or None
+
+        Note:
+            The record_class parameter is ignored for compatibility. Use schema_type
+            in driver.execute or _sqlspec_schema_type in parameters for type mapping.
+        """
+        if record_class is not None:
+            logger.warning(
+                "record_class parameter is deprecated and ignored. "
+                "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
+            )
+
+        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
+
+        if hasattr(result, "data") and result.data and isinstance(result, SQLResult):
+            return result.data[0]
+        return None
+
+    async def select_value(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
+        """Execute a SELECT query and return first value of first row.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+
+        Returns:
+            First value of first row or None
+        """
+        row = await self.select_one(conn, query_name, sql, parameters)
+        if row is None:
+            return None
+
+        if isinstance(row, dict):
+            return next(iter(row.values())) if row else None
+        if hasattr(row, "__getitem__"):
+            return row[0] if len(row) > 0 else None
+        return row
+
+    @asynccontextmanager
+    async def select_cursor(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> AsyncGenerator[Any, None]:
+        """Execute a SELECT query and return cursor context manager.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+
+        Yields:
+            Cursor-like object with results
+        """
+        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
+
+        yield AsyncCursorLike(result)
+
+    async def insert_update_delete(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> None:
+        """Execute INSERT/UPDATE/DELETE.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+
+        Note:
+            Returns None per aiosql async protocol
+        """
+        await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
+
+    async def insert_update_delete_many(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> None:
+        """Execute INSERT/UPDATE/DELETE with many parameter sets.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Sequence of parameter sets
+
+        Note:
+            Returns None per aiosql async protocol
+        """
+        await self.driver.execute_many(self._create_sql_object(sql), parameters=parameters, connection=conn)  # type: ignore[misc]
+
+    async def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
+        """Execute INSERT with RETURNING and return result.
+
+        Args:
+            conn: Database connection
+            query_name: Name of the query
+            sql: SQL string
+            parameters: Query parameters
+
+        Returns:
+            Returned value or None
+        """
+        return await self.select_one(conn, query_name, sql, parameters)

sqlspec/extensions/litestar/__init__.py

@@ -0,0 +1,6 @@
+from sqlspec.extensions.litestar import handlers, providers
+from sqlspec.extensions.litestar.cli import database_group
+from sqlspec.extensions.litestar.config import DatabaseConfig
+from sqlspec.extensions.litestar.plugin import SQLSpec
+
+__all__ = ("DatabaseConfig", "SQLSpec", "database_group", "handlers", "providers")