sqlakit 0.16.0__tar.gz → 0.18.0__tar.gz

{sqlakit-0.16.0 → sqlakit-0.18.0}/PKG-INFO

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

{sqlakit-0.16.0 → sqlakit-0.18.0}/pyproject.toml

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

{sqlakit-0.16.0 → sqlakit-0.18.0}/pyproject.toml.orig

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

{sqlakit-0.16.0 → sqlakit-0.18.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.16.0 → sqlakit-0.18.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,
@@ -541,12 +545,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)
 
 
@@ -633,25 +653,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.16.0 → sqlakit-0.18.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,
@@ -529,12 +533,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)
 
 
@@ -620,25 +640,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