sqlakit 0.15.0__tar.gz → 0.17.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.15.0
+Version: 0.17.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov

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

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

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

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

{sqlakit-0.15.0 → sqlakit-0.17.0}/sqlakit/_model.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 # Imported here rather than under TYPE_CHECKING: SQLAlchemy resolves the
 # annotation of `deleted_at` in this module, and needs both names at runtime.
+from collections.abc import Iterable  # noqa: TC003
 from datetime import datetime  # noqa: TC003
 from typing import (
     TYPE_CHECKING,
@@ -274,6 +275,46 @@ def db_for(model: type[Any]) -> BaseDatabase[Any, Any]:
     return placement
 
 
+def names_of(
+    attributes: tuple[Any, ...], listed: Iterable[str] | None
+) -> list[str] | None:
+    """Return the attributes to reload, as the session names them.
+
+    A rename and an editor follow the attribute a model declares, and neither
+    follows a string, so a caller may name either.
+    """
+    named = [
+        attribute if isinstance(attribute, str) else attribute.key
+        for attribute in attributes
+    ]
+    named += list(listed or ())
+    return named or None
+
+
+def every_attribute(model: type[Any]) -> list[str]:
+    """Return every attribute a model declares, relationships included."""
+    return list(sa.inspect(model).attrs.keys())
+
+
+def related_to(instance: Any) -> list[Any]:  # noqa: ANN401 - a model of either API
+    """Return the instances the loaded relationships of this one hold.
+
+    A relationship read again hands back the instances the session already
+    holds, with the values they were loaded with, so a caller that wants the
+    rows as they are now expires them.
+    """
+    state = sa.inspect(instance)
+    found = []
+    for name in state.mapper.relationships.keys():  # noqa: SIM118
+        if name in state.unloaded:
+            continue
+        value = state.dict.get(name)
+        if value is None:
+            continue
+        found.extend(value if isinstance(value, (list, set, tuple)) else [value])
+    return found
+
+
 def resolve_alias(model: type[Any], alias: str) -> BaseDatabase[Any, Any]:
     """Return the database a model knows under that alias.
 

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

@@ -24,9 +24,14 @@ from sqlalchemy.ext.compiler import compiles
 from sqlalchemy.orm import (
     InstrumentedAttribute,
     contains_eager,
+    defer,
     joinedload,
+    load_only,
     selectinload,
     subqueryload,
+    undefer,
+    undefer_group,
+    with_expression,
 )
 from sqlalchemy.orm.exc import MultipleResultsFound, NoResultFound
 from sqlalchemy.sql import operators
@@ -507,10 +512,23 @@ class BaseQuery(Generic[ModelT]):
         self._reject_statement("where")
         return self.with_select(self._select.where(*criteria))
 
-    def filter_by(self, **values: Any) -> Self:  # noqa: ANN401
-        """Narrow the rows by equality, as `Select.filter_by` does."""
+    def filter_by(
+        self,
+        values: Mapping[str, Any] | None = None,
+        /,
+        **fields: Any,  # noqa: ANN401
+    ) -> Self:
+        """Narrow the rows by equality, as `Select.filter_by` does.
+
+        ```python
+        db.query(User).filter_by(team="red")
+        db.query(User).filter_by(request.query_params)
+        ```
+
+        The fields are keywords, a mapping, or both, as `create()` takes them.
+        """
         self._reject_statement("filter_by")
-        return self.with_select(self._select.filter_by(**values))
+        return self.with_select(self._select.filter_by(**merged(values, fields)))
 
     def join(
         self,
@@ -659,6 +677,67 @@ class BaseQuery(Generic[ModelT]):
         """Read a relationship from a join this query already makes."""
         return self.options(_chain(contains_eager, keys))
 
+    def load_only(self, *columns: Any) -> Self:  # noqa: ANN401
+        """Load these columns of the row, and defer the rest.
+
+        ```python
+        db.query(User).load_only(User.id, User.name).all()
+        ```
+
+        The rows are still instances: a column left out is read from the
+        database when something touches it, one statement per instance, which
+        is the cost this trades the narrower row for. `only_columns` is the
+        other one: it gives the instances up and reads values.
+        """
+        return self.options(load_only(*columns))
+
+    def defer(self, *columns: Any) -> Self:  # noqa: ANN401
+        """Leave these columns out of the row until something reads them.
+
+        ```python
+        db.query(Post).defer(Post.body).all()
+        ```
+
+        For the wide column of a table read for everything else.
+        """
+        return self.options(*(defer(column) for column in columns))
+
+    def undefer(self, *columns: Any) -> Self:  # noqa: ANN401
+        """Load these columns with the row, though the model defers them.
+
+        ```python
+        db.query(Post).undefer(Post.body).all()
+        ```
+
+        The other side of `mapped_column(deferred=True)`, for the read that
+        wants the column after all.
+        """
+        return self.options(*(undefer(column) for column in columns))
+
+    def undefer_group(self, name: str) -> Self:
+        """Load the columns a model defers under this group name.
+
+        ```python
+        db.query(Post).undefer_group("body").all()
+        ```
+
+        The group is the one `mapped_column(deferred_group="body")` names, for
+        the columns a read wants together or not at all.
+        """
+        return self.options(undefer_group(name))
+
+    def with_expression(self, key: Any, expression: Any) -> Self:  # noqa: ANN401
+        """Give a `query_expression()` attribute its value for this read.
+
+        ```python
+        db.query(Post).with_expression(Post.comments, _comment_count()).all()
+        ```
+
+        The attribute holds what this statement selects into it, so a count or
+        a window function arrives on the instance rather than beside it.
+        """
+        return self.options(with_expression(key, expression))
+
     def with_for_update(
         self,
         *,

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

@@ -21,6 +21,9 @@ from sqlakit._model import (
     BaseModel,
     BaseSoftDeletes,
     DatabaseDescriptor,
+    every_attribute,
+    names_of,
+    related_to,
     soft_delete_column,
     tables_for,
 )
@@ -43,6 +46,7 @@ if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Iterable, Mapping, Sequence
 
     from sqlalchemy.engine import CursorResult, Result, ScalarResult
+    from sqlalchemy.orm import InstrumentedAttribute
     from sqlalchemy.sql import Executable
     from sqlalchemy.sql._typing import (
         _ColumnExpressionArgument,
@@ -633,25 +637,45 @@ class ModelMixin(BaseModel[Database]):
 
     async def refresh(
         self,
-        *,
+        *attributes: str | InstrumentedAttribute[Any],
         attribute_names: Iterable[str] | None = None,
+        with_relationships: bool = False,
         with_for_update: ForUpdateParameter = None,
     ) -> None:
         """Read this instance back from the database.
 
+        ```python
+        await user.refresh()  # every column, and the relationships already loaded
+        await user.refresh(User.team)  # and one that was not, though it raises on load
+        await user.refresh(with_relationships=True)  # every relationship the model has
+        ```
+
         Args:
-            attribute_names: The attributes to reload, rather than all of them.
-                A relationship named here is loaded again too.
+            attributes: The attributes to read again, rather than all of them, as
+                the model declares them or by name. A relationship named here is
+                loaded, which is how a `lazy="raise"` one is read after a refresh.
+            attribute_names: The same, for names a caller holds as a list.
+            with_relationships: Read every relationship the model declares, loaded
+                or not, which costs a statement each. For a test that compares the
+                whole instance and would otherwise name them one by one.
             with_for_update: Lock the row while it is read, as
                 ``Session.refresh`` takes it: `True` for a plain ``FOR UPDATE``,
                 or a mapping such as ``{"read": True}``.
 
         """
+        names = names_of(attributes, attribute_names)
+        if with_relationships:
+            names = list(dict.fromkeys([*(names or ()), *every_attribute(type(self))]))
         await self.db.session.refresh(
             self,
-            attribute_names=attribute_names,
+            attribute_names=names,
             with_for_update=with_for_update,
         )
+        if with_relationships:
+            # The relationships hand back the instances the session holds, and
+            # those carry the values they were loaded with.
+            for related in related_to(self):
+                self.db.session.expire(related)
 
     async def _persist(self) -> None:
         db = self.db

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

@@ -22,6 +22,9 @@ from ._model import (
     BaseModel,
     BaseSoftDeletes,
     DatabaseDescriptor,
+    every_attribute,
+    names_of,
+    related_to,
     soft_delete_column,
     tables_for,
 )
@@ -42,6 +45,7 @@ if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator, Mapping, Sequence
 
     from sqlalchemy.engine import CursorResult, Result, ScalarResult
+    from sqlalchemy.orm import InstrumentedAttribute
     from sqlalchemy.sql import Executable
     from sqlalchemy.sql._typing import (
         _ColumnExpressionArgument,
@@ -327,6 +331,10 @@ class Query(BaseQuery[ModelT]):
         ```python
         names = User.query.where(User.is_active).only_columns(User.name).all()
         ```
+
+        One column arrives as values and several as tuples, and neither is an
+        instance. `load_only` is the other one: the rows stay instances, and
+        the columns it leaves out are read when something touches them.
         """
         return ColumnQuery(
             self.model,
@@ -616,25 +624,45 @@ class ModelMixin(BaseModel[Database]):
 
     def refresh(
         self,
-        *,
+        *attributes: str | InstrumentedAttribute[Any],
         attribute_names: Iterable[str] | None = None,
+        with_relationships: bool = False,
         with_for_update: ForUpdateParameter = None,
     ) -> None:
         """Read this instance back from the database.
 
+        ```python
+        user.refresh()  # every column, and the relationships already loaded
+        user.refresh(User.team)  # and one that was not, though it raises on load
+        user.refresh(with_relationships=True)  # every relationship the model has
+        ```
+
         Args:
-            attribute_names: The attributes to reload, rather than all of them.
-                A relationship named here is loaded again too.
+            attributes: The attributes to read again, rather than all of them, as
+                the model declares them or by name. A relationship named here is
+                loaded, which is how a `lazy="raise"` one is read after a refresh.
+            attribute_names: The same, for names a caller holds as a list.
+            with_relationships: Read every relationship the model declares, loaded
+                or not, which costs a statement each. For a test that compares the
+                whole instance and would otherwise name them one by one.
             with_for_update: Lock the row while it is read, as
                 ``Session.refresh`` takes it: `True` for a plain ``FOR UPDATE``,
                 or a mapping such as ``{"read": True}``.
 
         """
+        names = names_of(attributes, attribute_names)
+        if with_relationships:
+            names = list(dict.fromkeys([*(names or ()), *every_attribute(type(self))]))
         self.db.session.refresh(
             self,
-            attribute_names=attribute_names,
+            attribute_names=names,
             with_for_update=with_for_update,
         )
+        if with_relationships:
+            # The relationships hand back the instances the session holds, and
+            # those carry the values they were loaded with.
+            for related in related_to(self):
+                self.db.session.expire(related)
 
     def _persist(self) -> None:
         db = self.db