sqlakit 0.1.0__py3-none-any.whl

sqlakit/asyncio/sql.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+
+import sqlalchemy as sa
+
+from sqlakit._sql import (
+    BaseSQLQuery,
+    Templates,
+    require_pydantic,
+    templates_of,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Sequence
+
+    from sqlalchemy.engine import Result, ScalarResult
+    from sqlalchemy.ext.asyncio import AsyncConnection
+    from sqlalchemy.sql import Executable
+
+    from ._db import Database
+
+__all__ = ["SQL", "SQLQuery", "SQLRows", "Templates"]
+
+RowT = TypeVar("RowT")
+OtherT = TypeVar("OtherT")
+
+
+class SQL:
+    """The SQL templates of one database, awaited.
+
+    Reached as `db.sql`, and where the templates are is the database's own
+    `templates=`:
+
+    ```python
+    db = Database(DB_URL, templates="app/sql")
+
+    await db.sql("reports/by_team.sql", since=since).typed(TeamReport).all()
+    await db.sql.from_string("SELECT count(*) FROM users").scalars().one()
+    ```
+    """
+
+    def __init__(self, db: Database) -> None:
+        self.db = db
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.db!r})"
+
+    def __call__(self, template: str, **context: Any) -> SQLQuery:  # noqa: ANN401
+        """Read the rows of a template. Short for `from_file`.
+
+        ```python
+        await db.sql("users/active.sql", team="red").all()
+        ```
+        """
+        return self.from_file(template, **context)
+
+    def from_file(self, template: str, **context: Any) -> SQLQuery:  # noqa: ANN401
+        """Read the rows of a template kept under the database's ``templates=``.
+
+        ```python
+        await db.sql.from_file("users/active.sql", team="red").all()
+        ```
+
+        The keyword arguments are the template's context.
+        """
+        return SQLQuery(self.db, template, context)
+
+    def from_string(self, source: str, **context: Any) -> SQLQuery:  # noqa: ANN401
+        """Read the rows of SQL written out here rather than kept in a file.
+
+        ```python
+        await db.sql.from_string(
+            "SELECT id FROM users WHERE team = {{ team }}", team="red"
+        )
+        ```
+
+        Values are named in `{{ }}` and passed by keyword, as in a template. A
+        `:name` or a `?` binds nothing here, and rendering says so rather than
+        reaching the driver. It needs no ``templates=``.
+        """
+        return SQLQuery(self.db, source, context, inline=True)
+
+    def from_statement(self, statement: Executable) -> SQLQuery:
+        """Read the rows of a statement built with SQLAlchemy.
+
+        ```python
+        await db.sql.from_statement(sa.text("SELECT ...").bindparams(id=1)).all()
+        ```
+
+        Nothing is rendered: the statement is the one that runs, parameters
+        and all. What this adds is the reading, `typed` and `chunks` included.
+        """
+        return SQLQuery(self.db, statement, {})
+
+    @property
+    def templates(self) -> Templates:
+        """Where this database looks for its templates."""
+        return templates_of(self.db)
+
+    def check(self) -> None:
+        """Compile every `.sql` template, so a broken one fails where deploys do.
+
+        Call it at startup, next to the rest of the wiring: a template is read
+        when something asks for it, and that is a poor time to find a typo.
+        """
+        self.templates.check()
+
+
+class SQLRows(BaseSQLQuery[RowT, "Database"]):
+    """The rows of a SQL template, on the connection of the block it runs in.
+
+    What the rows are is settled: reading them is all that is left.
+    """
+
+    async def all(self) -> Sequence[RowT]:
+        """Return every row."""
+        rows = await self._rows()
+        return cast("Sequence[RowT]", self._shaped(rows.all()))
+
+    async def first(self) -> RowT | None:
+        """Return the first row, or None."""
+        rows = await self._rows()
+        return cast("RowT | None", self._shaped_one(rows.first()))
+
+    async def one(self) -> RowT:
+        """Return the single row.
+
+        Raises:
+            NoResultFound: if there is none.
+            MultipleResultsFound: if there is more than one.
+
+        """
+        rows = await self._rows()
+        return cast("RowT", self._shaped_one(rows.one()))
+
+    async def one_or_none(self) -> RowT | None:
+        """Return the single row, or None.
+
+        Raises:
+            MultipleResultsFound: if there is more than one.
+
+        """
+        rows = await self._rows()
+        return cast("RowT | None", self._shaped_one(rows.one_or_none()))
+
+    async def chunks(self, size: int) -> AsyncIterator[Sequence[RowT]]:
+        """Read every row, ``size`` of them at a time.
+
+        One statement, fetched in batches, for a job that walks a table too large to
+        hold. The rows come off a cursor the database holds open, so the whole walk
+        is one transaction.
+        """
+        connection = await self._connection()
+        streamed = await connection.stream(self._executable(size=size))
+        rows = streamed.scalars() if self.scalar else streamed
+        async for batch in rows.partitions(size):
+            yield cast("Sequence[RowT]", self._shaped(batch))
+
+    async def execute(self) -> int:
+        """Run it for what it writes, and return how many rows it touched.
+
+        For a template that inserts, updates or deletes. Inside a transaction the
+        write is part of it and the block decides. In a block with no transaction
+        the call commits for itself, as ORM writes do.
+        """
+        connection = await self._connection()
+        result = await connection.execute(self.statement)
+        if not self.db.in_transaction():
+            await connection.commit()
+        return result.rowcount
+
+    async def _rows(self) -> Result[Any] | ScalarResult[Any]:
+        connection = await self._connection()
+        result = await connection.execute(self.statement)
+        return result.scalars() if self.scalar else result
+
+    async def _connection(self) -> AsyncConnection:
+        """Return this block's connection, with any pending ORM writes on it."""
+        if self.db.in_session():
+            await self.db.session.flush()
+        return self.db.connection
+
+
+class SQLQuery(SQLRows[sa.Row[Any]]):
+    """The rows a SQL template returns, as `db.sql(...)` hands them over.
+
+    `typed` and `scalars` say what one row is; both return rows that read the
+    same way and carry no further say, so each is asked once.
+    """
+
+    def typed(self, type_: type[OtherT], /) -> SQLRows[OtherT]:
+        """Read the rows as this type, one row at a time.
+
+        ```python
+        await db.sql("reports/by_team.sql", since=since).typed(TeamReport).all()
+        ```
+
+        The type is what one row becomes, and the terminal decides the container.
+        Anything pydantic can validate works: a model, a dataclass, a
+        `TypedDict`. The type also says how much of the row it takes: one built
+        from columns is given the whole row, and anything else is given the
+        first column, so `SELECT count(*)` with `typed(int)` reads as an `int`.
+
+        Raises:
+            MissingDependencyError: if pydantic is not installed.
+
+        """
+        require_pydantic()
+        return cast("SQLRows[OtherT]", self._as(SQLRows, type_=type_))
+
+    def scalars(self) -> SQLRows[Any]:
+        """Read the first column of each row instead of whole rows.
+
+        ```python
+        await db.sql.from_string("SELECT count(*) FROM users").scalars().one()
+        ```
+
+        `typed()` does the same when the type is worth naming; this is for when it is
+        not, and needs no pydantic.
+        """
+        return self._as(SQLRows, scalar=True)

sqlakit/exceptions.py

@@ -0,0 +1,423 @@
+from collections.abc import Iterable
+
+from sqlalchemy.orm import exc as sa_exc
+
+DEFAULT_ALIAS = "default"
+
+__all__ = [
+    "AsyncFilterError",
+    "BulkQueryError",
+    "ConflictingDatabaseUrlError",
+    "DatabaseAlreadyConfiguredError",
+    "DatabaseNotConfiguredError",
+    "DetachedInstanceError",
+    "InstanceNotFoundError",
+    "InvalidCursorError",
+    "InvalidDatabaseConfigError",
+    "InvalidOrderFieldError",
+    "MissingConnectionError",
+    "MissingDatabaseUrlError",
+    "MissingDefaultDatabaseError",
+    "MissingDependencyError",
+    "MissingSessionError",
+    "MultipleInstancesFoundError",
+    "NullCursorValueError",
+    "RawStatementError",
+    "RetryNotSupportedError",
+    "SQLAKitError",
+    "SQLNotConfiguredError",
+    "StrayParameterError",
+    "TemplateNotFoundError",
+    "TransactionRolledBackError",
+    "UnknownDatabaseError",
+    "UnknownFieldError",
+    "UnknownImportPathError",
+    "UnorderedPageError",
+]
+
+
+class SQLAKitError(Exception):
+    """Base class for all sqlakit errors."""
+
+
+class MissingConnectionError(SQLAKitError, RuntimeError):
+    """Raised when no connection is bound to the current context."""
+
+    def __init__(
+        self,
+        message: str = (
+            "No connection is bound to the current context. "
+            "Enter `Database.connect()` or `Database.transaction()` first."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class MissingSessionError(SQLAKitError, RuntimeError):
+    """Raised when no session is bound to the current context."""
+
+    def __init__(
+        self,
+        message: str = (
+            "No session is bound to the current context. "
+            "Enter `Database.session_factory()` or `Database.connect()` first."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class RetryNotSupportedError(SQLAKitError, TypeError):
+    """Raised when a transaction with ``retry_on`` is entered as a block."""
+
+    def __init__(
+        self,
+        message: str = (
+            "A transaction with `retry_on` cannot be used as a context manager: "
+            "retrying re-runs the block, which only a decorator can do. "
+            "Use `@db.transaction(retry_on=...)` instead."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class DatabaseNotConfiguredError(SQLAKitError, RuntimeError):
+    """Raised when the importable database is used before it has a URL."""
+
+    def __init__(
+        self,
+        message: str = (
+            "The database is not configured. "
+            "Call `db.configure(url, ...)` once, at startup, before using it."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class DatabaseAlreadyConfiguredError(SQLAKitError, RuntimeError):
+    """Raised when reconfiguring a database whose engine is already in use."""
+
+    def __init__(
+        self,
+        message: str = (
+            "The database is already connected. Dispose of the engine before "
+            "configuring it again."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class UnknownDatabaseError(SQLAKitError, KeyError):
+    """Raised when asking for a database alias that was never configured."""
+
+    def __init__(self, alias: str, known: tuple[str, ...] = ()) -> None:
+        super().__init__(
+            f"No database is configured as {alias!r}. "
+            f"Configured: {', '.join(map(repr, known)) or 'none'}."
+        )
+
+
+class MissingDefaultDatabaseError(SQLAKitError, ValueError):
+    """Raised when a configuration keyed by alias carries no default."""
+
+    def __init__(self, aliases: tuple[str, ...] = ()) -> None:
+        super().__init__(
+            f"A configuration keyed by alias has to carry a {DEFAULT_ALIAS!r}: "
+            f"that is the database reached without naming an alias. "
+            f"Got: {', '.join(map(repr, aliases)) or 'nothing'}."
+        )
+
+
+class InvalidDatabaseConfigError(SQLAKitError, ValueError):
+    """Raised when a configuration cannot be turned into a database."""
+
+
+class MissingDatabaseUrlError(InvalidDatabaseConfigError):
+    """Raised when a configuration says nowhere to connect."""
+
+    def __init__(
+        self,
+        message: str = (
+            "A database has to be configured with a `url`, or with at least a "
+            "`drivername` to build one from."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class ConflictingDatabaseUrlError(InvalidDatabaseConfigError):
+    """Raised when a configuration says where to connect twice over."""
+
+    def __init__(self, parts: tuple[str, ...] = ()) -> None:
+        super().__init__(
+            "A database is configured with a `url` or with its parts "
+            f"({', '.join(parts)}), not with both."
+        )
+
+
+class TransactionRolledBackError(SQLAKitError, RuntimeError):
+    """Raised when a block finds its transaction already rolled back."""
+
+    def __init__(
+        self,
+        message: str = (
+            "The transaction was rolled back from inside the block, leaving "
+            "nothing to commit. A session that only takes part in a "
+            "transaction rolls back the whole of it; for a block that has to "
+            "fail on its own, use `transaction(savepoint=True)`."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class DetachedInstanceError(SQLAKitError, sa_exc.DetachedInstanceError):
+    """Raised when saving an instance whose session is gone.
+
+    A subclass of SQLAlchemy's error of the same name, so code that catches
+    either one catches this.
+    """
+
+    def __init__(self, model: str) -> None:
+        super().__init__(
+            f"This {model} belongs to a session that has closed, so saving it "
+            f"would silently copy it into another one. Load it again in this "
+            f"block, or merge it yourself with `session.merge(...)`."
+        )
+
+
+class InstanceNotFoundError(SQLAKitError, sa_exc.NoResultFound):
+    """Raised when a query that must match one instance matches none.
+
+    A subclass of SQLAlchemy's `NoResultFound`, so code that catches either one
+    catches this. It names the model, which is what an API answering 404 wants:
+
+    ```python
+    except InstanceNotFoundError as error:
+        raise HTTPException(404, f"{error.model} not found")
+    ```
+    """
+
+    def __init__(self, model: str) -> None:
+        self.model = model
+        super().__init__(f"No {model} matches this query.")
+
+
+class MultipleInstancesFoundError(SQLAKitError, sa_exc.MultipleResultsFound):
+    """Raised when a query that must match one instance matches several.
+
+    A subclass of SQLAlchemy's `MultipleResultsFound`, so code that catches
+    either one catches this. Reaching it means the query is not as narrow as
+    the call assumed, or the column it narrows on is not unique.
+    """
+
+    def __init__(self, model: str) -> None:
+        self.model = model
+        super().__init__(f"More than one {model} matches this query.")
+
+
+class InvalidCursorError(SQLAKitError, ValueError):
+    """Raised when a pagination cursor was not made here, or not for this order."""
+
+    def __init__(
+        self,
+        message: str = (
+            "This cursor does not belong to this query. Pass back the one the "
+            "previous page returned, unchanged, and order the query the same way."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class MissingDependencyError(SQLAKitError, ImportError):
+    """Raised when something optional is used and its package is not installed."""
+
+    def __init__(
+        self, package: str, needed_by: str, install: str | None = None
+    ) -> None:
+        self.package = package
+        super().__init__(
+            f"`{package}` is not installed, and {needed_by} cannot work "
+            f"without it. Install `{install or package}`."
+        )
+
+
+class SQLNotConfiguredError(SQLAKitError, RuntimeError):
+    """Raised when a database is asked for a template file and has no path."""
+
+    def __init__(
+        self,
+        message: str = (
+            "This database does not know where its SQL templates are. Pass "
+            "`templates=` to `Database(...)` or to `db.configure(...)`, or "
+            "write the SQL out with `db.sql.from_string(...)`."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class TemplateNotFoundError(SQLAKitError, FileNotFoundError):
+    """Raised when no configured path holds the template asked for."""
+
+    def __init__(self, template: str, paths: Iterable[object] = ()) -> None:
+        self.template = template
+        looked = ", ".join(str(path) for path in paths)
+        super().__init__(
+            f"No SQL template named `{template}`. Looked in: {looked or 'nowhere'}."
+        )
+
+
+class AsyncFilterError(SQLAKitError, TypeError):
+    """Raised when a template is given a filter or global that has to be awaited."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(
+            f"`{name}` is a coroutine function, and templates render "
+            f"synchronously: rendering builds SQL and awaits nothing, in the "
+            f"async API as well. Await the value first, and pass what it "
+            f"returns in the context."
+        )
+
+
+class StrayParameterError(SQLAKitError, ValueError):
+    """Raised when rendered SQL holds a parameter the template never bound."""
+
+    def __init__(self, names: Iterable[str] = (), template: str | None = None) -> None:
+        self.names = tuple(names)
+        where = f"`{template}`" if template else "This SQL"
+        listed = ", ".join(f"`:{name}`" for name in self.names)
+        written = ", ".join(f"`{{{{ {name} }}}}`" for name in self.names)
+        super().__init__(
+            f"{where} reads as though {listed} were a parameter, and nothing "
+            f"binds it. Values come from the template: write {written} and "
+            f"pass them in the context. A colon that belongs to the SQL, "
+            f"inside a JSON document or a string that starts with one, is "
+            f"written `\\:`."
+        )
+
+
+class RawStatementError(SQLAKitError, TypeError):
+    """Raised when building on a query that already carries a statement."""
+
+    def __init__(self, method: str = "this", advice: str | None = None) -> None:
+        super().__init__(
+            f"A query built from a statement cannot be narrowed further: "
+            f"{advice or f'put `{method}` in the statement itself'}."
+        )
+
+
+class NullCursorValueError(InvalidCursorError):
+    """Raised when a page would have to start at a row that is NULL in the order."""
+
+    def __init__(self, column: str = "the ordering") -> None:
+        super().__init__(
+            f"Cannot page past a row whose `{column}` is NULL: comparing against "
+            f"NULL matches nothing. Order by a column that is never NULL, or "
+            f"add one."
+        )
+
+
+class BulkQueryError(SQLAKitError, TypeError):
+    """Raised when a bulk update or delete is asked to honour what it cannot."""
+
+    def __init__(self, method: str = "update", dropped: tuple[str, ...] = ()) -> None:
+        super().__init__(
+            f"A bulk `{method}` writes one statement, which has no room for "
+            f"{', '.join(dropped) or 'this'}. Narrow it with `where` alone, or "
+            f"read the rows and write them one by one."
+        )
+
+
+class PageItemsMismatchError(SQLAKitError, TypeError):
+    """Raised when a page transform returns the wrong number of items."""
+
+    def __init__(self, expected: int = 0, got: int = 0) -> None:
+        super().__init__(
+            f"The page holds {expected} items and the transform returned {got}. "
+            f"Totals and cursors belong to the page's rows, so a transform has "
+            f"to return one item per row."
+        )
+
+
+class UnknownOrderFieldError(SQLAKitError, ValueError):
+    """Raised when an ordering names a field the model does not offer."""
+
+    def __init__(self, field: str, orderable: Iterable[str] = ()) -> None:
+        offered = ", ".join(sorted(orderable))
+        super().__init__(
+            f"`{field}` is not something this model orders by. "
+            f"It offers: {offered or 'nothing'}."
+        )
+
+
+class UnknownImportPathError(SQLAKitError, ImportError):
+    """Raised when a dotted path names nothing that can be imported."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        super().__init__(
+            f"`{path}` does not name anything importable. A path is "
+            f"`package.module.name`, or `package.module:name` when the name "
+            f"could be read as a module of its own."
+        )
+
+
+class UnknownFieldError(SQLAKitError, AttributeError):
+    """Raised when a model is handed a field it does not have."""
+
+    def __init__(self, model: str, field: str) -> None:
+        self.model = model
+        self.field = field
+        super().__init__(f"`{model}` has no field `{field}`.")
+
+
+class InvalidOrderFieldError(SQLAKitError, TypeError):
+    """Raised when ``__orderable__`` names something the model does not have.
+
+    A mistake in the declaration rather than in the request, which is why it is
+    not the error a bad sort string raises: answering a client with 400 for it
+    would blame the wrong side.
+    """
+
+    def __init__(self, model: str, field: str) -> None:
+        self.model = model
+        self.field = field
+        super().__init__(
+            f"`{model}.__orderable__` names `{field}`, which is not a mapped "
+            f"column of it. Name a column, or return a mapping from a "
+            f"classmethod for fields that are not columns."
+        )
+
+
+class KeyLookupError(SQLAKitError, TypeError):
+    """Raised when a lookup by primary key is asked to honour what it cannot."""
+
+    def __init__(self, carried: tuple[str, ...] = ()) -> None:
+        super().__init__(
+            f"`get` looks a row up by its primary key, which has no room for "
+            f"{', '.join(carried) or 'this'}. Read the rows the query narrows "
+            f"to with `one`, `first` or `all` instead."
+        )
+
+
+class UncomparableOrderingError(SQLAKitError, TypeError):
+    """Raised when a cursor page is ordered by something it cannot compare."""
+
+    def __init__(self, clause: object) -> None:
+        super().__init__(
+            f"A cursor cannot page an ordering by `{clause}`. It compares rows "
+            f"by the values it reads back from them, so the order has to name "
+            f"columns of the model rather than text or an expression."
+        )
+
+
+class UnorderedPageError(SQLAKitError, TypeError):
+    """Raised when a page is read from a query that names no order."""
+
+    def __init__(
+        self,
+        message: str = (
+            "Pagination needs an order. Without one the database returns rows "
+            "in whatever order it finds them, so pages repeat and skip rows. "
+            "Add `.order_by(...)`."
+        ),
+    ) -> None:
+        super().__init__(message)