sqlakit 0.17.0__tar.gz → 0.19.0__tar.gz

{sqlakit-0.17.0 → sqlakit-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.17.0
+Version: 0.19.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov
@@ -429,10 +429,11 @@ On shutdown, `dispose()` closes the pool.
 
 [Getting started](docs/getting-started.md) builds a database, a model and a
 test from an empty file. The rest is under [`docs/`](docs/):
-[queries](docs/queries.md), [SQL templates](docs/sql.md),
-[models](docs/models.md), [testing](docs/testing.md),
-[debugging](docs/debugging.md), [multiple databases](docs/routing.md) and
-[the reference](docs/reference.md). Complete example apps live in
-[`examples/`](examples/), and each one is run by the test suite.
+[compared to SQLAlchemy](docs/comparison.md), [queries](docs/queries.md),
+[SQL templates](docs/sql.md), [models](docs/models.md),
+[testing](docs/testing.md), [debugging](docs/debugging.md),
+[multiple databases](docs/routing.md) and [the reference](docs/reference.md).
+Complete example apps live in [`examples/`](examples/), and each one is run by
+the test suite.
 
 What changed in each version is in the [changelog](CHANGELOG.md).

{sqlakit-0.17.0 → sqlakit-0.19.0}/README.md

@@ -396,10 +396,11 @@ On shutdown, `dispose()` closes the pool.
 
 [Getting started](docs/getting-started.md) builds a database, a model and a
 test from an empty file. The rest is under [`docs/`](docs/):
-[queries](docs/queries.md), [SQL templates](docs/sql.md),
-[models](docs/models.md), [testing](docs/testing.md),
-[debugging](docs/debugging.md), [multiple databases](docs/routing.md) and
-[the reference](docs/reference.md). Complete example apps live in
-[`examples/`](examples/), and each one is run by the test suite.
+[compared to SQLAlchemy](docs/comparison.md), [queries](docs/queries.md),
+[SQL templates](docs/sql.md), [models](docs/models.md),
+[testing](docs/testing.md), [debugging](docs/debugging.md),
+[multiple databases](docs/routing.md) and [the reference](docs/reference.md).
+Complete example apps live in [`examples/`](examples/), and each one is run by
+the test suite.
 
 What changed in each version is in the [changelog](CHANGELOG.md).

{sqlakit-0.17.0 → sqlakit-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.17.0"
+version = "0.19.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"

{sqlakit-0.17.0 → sqlakit-0.19.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.17.0"
+version = "0.19.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"

{sqlakit-0.17.0 → sqlakit-0.19.0}/sqlakit/__init__.py

@@ -24,6 +24,7 @@ from .exceptions import (
     DatabaseNotConfiguredError,
     DefaultAliasError,
     DetachedInstanceError,
+    DuplicateKeyError,
     InstanceNotFoundError,
     InvalidCursorError,
     InvalidDatabaseConfigError,
@@ -83,6 +84,7 @@ __all__ = [
     "DebugServer",
     "DefaultAliasError",
     "DetachedInstanceError",
+    "DuplicateKeyError",
     "EngineArgs",
     "InstanceNotFoundError",
     "InvalidCursorError",

{sqlakit-0.17.0 → sqlakit-0.19.0}/sqlakit/_query.py

@@ -43,6 +43,7 @@ from ._model import resolve_alias, soft_delete_column
 from .exceptions import (
     BulkQueryError,
     ConflictingJoinError,
+    DuplicateKeyError,
     InstanceNotFoundError,
     InvalidCursorError,
     InvalidNullsError,
@@ -53,6 +54,7 @@ from .exceptions import (
     PageItemsMismatchError,
     RawStatementError,
     UncomparableOrderingError,
+    UnknownFieldError,
     UnknownOrderFieldError,
     UnorderedPageError,
 )
@@ -734,9 +736,13 @@ class BaseQuery(Generic[ModelT]):
         ```
 
         The attribute holds what this statement selects into it, so a count or
-        a window function arrives on the instance rather than beside it.
+        a window function arrives on the instance rather than beside it. An
+        instance the session already holds is read again, so the value follows
+        the expression given this time rather than the one it was loaded with.
         """
-        return self.options(with_expression(key, expression))
+        return self.options(with_expression(key, expression)).execution_options(
+            populate_existing=True
+        )
 
     def with_for_update(
         self,
@@ -1518,6 +1524,59 @@ class _Rows(Protocol[RowT_co]):
     def one_or_none(self) -> RowT_co | None: ...
 
 
+def key_names(model: type[Any], keys: Sequence[Any]) -> list[str]:
+    """Return the attribute names `in_bulk` keys by, checked against the model.
+
+    With no columns the key is the primary key. A key has to be a column
+    attribute of the model itself: an expression cannot be read off a row, and
+    a column of another table with the same name would read the wrong value.
+
+    Raises:
+        UnknownFieldError: if a key is not a column of the model.
+
+    """
+    mapper = sa.inspect(model, raiseerr=True)
+    if not keys:
+        return [
+            mapper.get_property_by_column(column).key for column in mapper.primary_key
+        ]
+    names = []
+    for key in keys:
+        name = getattr(key, "key", None)
+        owner = getattr(key, "class_", None)
+        if (
+            name is None
+            or owner is None
+            or not issubclass(model, owner)
+            or name not in mapper.column_attrs
+        ):
+            raise UnknownFieldError(model.__name__, str(key))
+        names.append(name)
+    return names
+
+
+def keyed(
+    rows: Iterable[Any], model: type[Any], names: Sequence[str]
+) -> dict[Any, Any]:
+    """Return the rows under the value each has in these attributes, one row per key.
+
+    One name keys by its value, several by the tuple of theirs, in the order
+    the rows arrived.
+
+    Raises:
+        DuplicateKeyError: if two rows share a key.
+
+    """
+    result: dict[Any, Any] = {}
+    for row in rows:
+        values = tuple(getattr(row, name) for name in names)
+        key = values[0] if len(values) == 1 else values
+        if key in result:
+            raise DuplicateKeyError(model.__name__, names, key)
+        result[key] = row
+    return result
+
+
 def one_row(rows: _Rows[RowT], name: str) -> RowT:
     """Return the single row, saying what had none or too many.
 

{sqlakit-0.17.0 → sqlakit-0.19.0}/sqlakit/asyncio/orm.py

@@ -31,6 +31,8 @@ from sqlakit._query import (
     BaseQuery,
     CursorPage,
     Page,
+    key_names,
+    keyed,
     merged,
     one_row,
     one_row_or_none,
@@ -152,6 +154,61 @@ class Query(BaseQuery[ModelT]):
         result = await self._rows(self._executable())
         return result.all()
 
+    @overload
+    async def in_bulk(self) -> dict[Any, ModelT]: ...
+
+    @overload
+    async def in_bulk(
+        self, key: _TypedColumnClauseArgument[C0], /
+    ) -> dict[C0, ModelT]: ...
+
+    @overload
+    async def in_bulk(
+        self,
+        key: _TypedColumnClauseArgument[C0],
+        other: _TypedColumnClauseArgument[C1],
+        /,
+    ) -> dict[tuple[C0, C1], ModelT]: ...
+
+    @overload
+    async def in_bulk(
+        self,
+        key: _TypedColumnClauseArgument[C0],
+        other: _TypedColumnClauseArgument[C1],
+        third: _TypedColumnClauseArgument[C2],
+        /,
+    ) -> dict[tuple[C0, C1, C2], ModelT]: ...
+
+    @overload
+    async def in_bulk(
+        self, *keys: _TypedColumnClauseArgument[Any]
+    ) -> dict[Any, ModelT]: ...
+
+    async def in_bulk(
+        self, *keys: _TypedColumnClauseArgument[Any]
+    ) -> dict[Any, ModelT]:
+        """Return every matching row, under the value it has in these columns.
+
+        ```python
+        User.query.where(User.id.in_(ids)).in_bulk()  # dict[int, User], by key
+        User.query.in_bulk(User.email)  # dict[str, User]
+        Seat.query.in_bulk(Seat.row, Seat.col)  # dict[tuple[int, str], Seat]
+        ```
+
+        One column keys by its value and several by the tuple of theirs, so
+        the checker knows the key's type. The rows keep the query's order, and
+        a key column the query defers is loaded with the row.
+
+        Raises:
+            DuplicateKeyError: if two rows share a key.
+            UnknownFieldError: if a key is not a column of the model.
+
+        """
+        # A key the model defers is read with the row rather than one row at a time.
+        names = key_names(self.model, keys)
+        rows = await self.undefer(*keys).all()
+        return keyed(rows, self.model, names)
+
     async def first(self) -> ModelT | None:
         """Return the first matching row, or None."""
         # A raw statement takes no limit; the first row is read off the result.
@@ -545,12 +602,28 @@ class QueryDescriptor(Generic[QueryT]):
 
         query = QueryDescriptor(AppQuery)
     ```
+
+    Given `Query` itself, as `ModelMixin` does, it reads as a query of the model
+    it is read from: `User.query` is a `Query[User]`, so `User.query.get(1)` is
+    a `User | None`.
     """
 
     def __init__(self, query_class: type[QueryT]) -> None:
         self.query_class = query_class
 
-    def __get__(self, instance: object | None, owner: type[Any]) -> QueryT:
+    # `ClassVar` cannot hold a type variable, so the base declares the query
+    # every model has and a read narrows it to the model it is read from.
+    @overload
+    def __get__(
+        self: QueryDescriptor[Query[Any]],
+        instance: object | None,
+        owner: type[ModelT],
+    ) -> Query[ModelT]: ...
+
+    @overload
+    def __get__(self, instance: object | None, owner: type[Any]) -> QueryT: ...
+
+    def __get__(self, instance: object | None, owner: type[Any]) -> Query[Any]:
         return self.query_class(owner, owner.db)
 
 

{sqlakit-0.17.0 → sqlakit-0.19.0}/sqlakit/exceptions.py

@@ -479,6 +479,22 @@ class InvalidNullsError(SQLAKitError, ValueError):
         super().__init__(f"`nulls` is `first` or `last`, not `{nulls!r}`.")
 
 
+class DuplicateKeyError(SQLAKitError, ValueError):
+    """Raised when `in_bulk` finds two rows under one key."""
+
+    def __init__(
+        self, model: str, key: Iterable[str] = (), value: object = None
+    ) -> None:
+        super().__init__(
+            f"`in_bulk` keys {model} rows by {', '.join(key) or 'the primary key'}, "
+            f"and two rows share {value!r}. Key by something unique, or narrow "
+            f"the query to one row per key."
+        )
+        self.model = model
+        self.key = tuple(key)
+        self.value = value
+
+
 class KeyLookupError(SQLAKitError, TypeError):
     """Raised when a lookup by primary key is asked to honour what it cannot."""
 

{sqlakit-0.17.0 → sqlakit-0.19.0}/sqlakit/orm.py

@@ -32,6 +32,8 @@ from ._query import (
     BaseQuery,
     CursorPage,
     Page,
+    key_names,
+    keyed,
     merged,
     one_row,
     one_row_or_none,
@@ -148,6 +150,55 @@ class Query(BaseQuery[ModelT]):
         """Return every matching row."""
         return self._rows(self._executable()).all()
 
+    @overload
+    def in_bulk(self) -> dict[Any, ModelT]: ...
+
+    @overload
+    def in_bulk(self, key: _TypedColumnClauseArgument[C0], /) -> dict[C0, ModelT]: ...
+
+    @overload
+    def in_bulk(
+        self,
+        key: _TypedColumnClauseArgument[C0],
+        other: _TypedColumnClauseArgument[C1],
+        /,
+    ) -> dict[tuple[C0, C1], ModelT]: ...
+
+    @overload
+    def in_bulk(
+        self,
+        key: _TypedColumnClauseArgument[C0],
+        other: _TypedColumnClauseArgument[C1],
+        third: _TypedColumnClauseArgument[C2],
+        /,
+    ) -> dict[tuple[C0, C1, C2], ModelT]: ...
+
+    @overload
+    def in_bulk(self, *keys: _TypedColumnClauseArgument[Any]) -> dict[Any, ModelT]: ...
+
+    def in_bulk(self, *keys: _TypedColumnClauseArgument[Any]) -> dict[Any, ModelT]:
+        """Return every matching row, under the value it has in these columns.
+
+        ```python
+        User.query.where(User.id.in_(ids)).in_bulk()  # dict[int, User], by key
+        User.query.in_bulk(User.email)  # dict[str, User]
+        Seat.query.in_bulk(Seat.row, Seat.col)  # dict[tuple[int, str], Seat]
+        ```
+
+        One column keys by its value and several by the tuple of theirs, so
+        the checker knows the key's type. The rows keep the query's order, and
+        a key column the query defers is loaded with the row.
+
+        Raises:
+            DuplicateKeyError: if two rows share a key.
+            UnknownFieldError: if a key is not a column of the model.
+
+        """
+        # A key the model defers is read with the row rather than one row at a time.
+        names = key_names(self.model, keys)
+        rows = self.undefer(*keys).all()
+        return keyed(rows, self.model, names)
+
     def first(self) -> ModelT | None:
         """Return the first matching row, or None."""
         # A raw statement takes no limit; the first row is read off the result.
@@ -533,12 +584,28 @@ class QueryDescriptor(Generic[QueryT]):
 
         query = QueryDescriptor(AppQuery)
     ```
+
+    Given `Query` itself, as `ModelMixin` does, it reads as a query of the model
+    it is read from: `User.query` is a `Query[User]`, so `User.query.get(1)` is
+    a `User | None`.
     """
 
     def __init__(self, query_class: type[QueryT]) -> None:
         self.query_class = query_class
 
-    def __get__(self, instance: object | None, owner: type[Any]) -> QueryT:
+    # `ClassVar` cannot hold a type variable, so the base declares the query
+    # every model has and a read narrows it to the model it is read from.
+    @overload
+    def __get__(
+        self: QueryDescriptor[Query[Any]],
+        instance: object | None,
+        owner: type[ModelT],
+    ) -> Query[ModelT]: ...
+
+    @overload
+    def __get__(self, instance: object | None, owner: type[Any]) -> QueryT: ...
+
+    def __get__(self, instance: object | None, owner: type[Any]) -> Query[Any]:
         return self.query_class(owner, owner.db)