fastapi-toolsets 5.1.6__tar.gz → 5.1.7__tar.gz

{fastapi_toolsets-5.1.6 → fastapi_toolsets-5.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-toolsets
-Version: 5.1.6
+Version: 5.1.7
 Summary: Production-ready utilities for FastAPI applications
 Keywords: fastapi,sqlalchemy,postgresql
 Author: d3vyce

{fastapi_toolsets-5.1.6 → fastapi_toolsets-5.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "5.1.6"
+version = "5.1.7"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"

{fastapi_toolsets-5.1.6 → fastapi_toolsets-5.1.7}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "5.1.6"
+version = "5.1.7"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"

{fastapi_toolsets-5.1.6 → fastapi_toolsets-5.1.7}/src/fastapi_toolsets/__init__.py

@@ -24,4 +24,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "5.1.6"
+__version__ = "5.1.7"

{fastapi_toolsets-5.1.6 → fastapi_toolsets-5.1.7}/src/fastapi_toolsets/_orm.py

@@ -1,6 +1,6 @@
 """SQLAlchemy state and expression helpers."""
 
-from collections.abc import Sequence
+from collections.abc import Iterable, Sequence
 from typing import Any
 
 from sqlalchemy import inspect as sa_inspect
@@ -12,6 +12,11 @@ def key_expr(columns: Sequence[Any]) -> Any:
     return columns[0] if len(columns) == 1 else tuple_(*columns)
 
 
+def is_to_many(rels: Iterable[Any]) -> bool:
+    """True if the relationship path *rels* crosses a collection."""
+    return any(rel.property.uselist for rel in rels)
+
+
 def is_expired(obj: Any) -> bool:
     """True when *obj* or any of its attributes must be re-read from the database."""
     state = sa_inspect(obj)

{fastapi_toolsets-5.1.6 → fastapi_toolsets-5.1.7}/src/fastapi_toolsets/crud/factory.py

@@ -21,10 +21,14 @@ from sqlalchemy import (
     Float,
     Integer,
     Numeric,
+    PrimaryKeyConstraint,
+    String,
+    UniqueConstraint,
     Uuid,
     and_,
     func,
     select,
+    tuple_,
 )
 from sqlalchemy.dialects.postgresql import insert
 from sqlalchemy.exc import NoResultFound
@@ -37,7 +41,7 @@ from sqlalchemy.sql.elements import UnaryExpression
 from sqlalchemy.sql.roles import WhereHavingRole
 from sqlalchemy.sql.util import ClauseAdapter
 
-from .._orm import is_expired, key_expr, loaded_relationships
+from .._orm import is_expired, is_to_many, key_expr, loaded_relationships
 from ..db import transaction
 from ..exceptions import InvalidOrderFieldError, NotFoundError
 from ..schemas import (
@@ -89,23 +93,23 @@ class _CursorDirection(str, Enum):
 
 
 def _encode_cursor(
-    value: Any, *, direction: _CursorDirection = _CursorDirection.NEXT
+    value: Any,
+    *,
+    direction: _CursorDirection = _CursorDirection.NEXT,
+    key: Sequence[Any] = (),
 ) -> str:
-    """Encode a cursor column value and navigation direction as a URL-safe base64 string."""
-    return (
-        base64.urlsafe_b64encode(
-            json.dumps({"val": str(value), "dir": direction}).encode()
-        )
-        .decode()
-        .rstrip("=")
-    )
+    """Encode a cursor value, its row's tiebreak key and direction as URL-safe base64."""
+    payload: dict[str, Any] = {"val": str(value), "dir": direction}
+    if key:
+        payload["key"] = [str(v) for v in key]
+    return base64.urlsafe_b64encode(json.dumps(payload).encode()).decode().rstrip("=")
 
 
-def _decode_cursor(cursor: str) -> tuple[str, _CursorDirection]:
-    """Decode a URL-safe base64 cursor string into ``(raw_value, direction)``."""
+def _decode_cursor(cursor: str) -> tuple[str, list[str] | None, _CursorDirection]:
+    """Decode a URL-safe base64 cursor string into ``(raw_value, raw_key, direction)``."""
     padded = cursor + "=" * (-len(cursor) % 4)
     payload = json.loads(base64.urlsafe_b64decode(padded).decode())
-    return payload["val"], _CursorDirection(payload["dir"])
+    return payload["val"], payload.get("key"), _CursorDirection(payload["dir"])
 
 
 def _page_size_query(default: int, max_size: int) -> int:
@@ -137,6 +141,27 @@ def _parse_cursor_value(raw_val: str, col_type: Any) -> Any:
     )
 
 
+def _parse_key_value(raw_val: str, col_type: Any) -> Any:
+    """Parse a raw tiebreak key value, which unlike a cursor value may be a string."""
+    if isinstance(col_type, String):
+        return raw_val
+    return _parse_cursor_value(raw_val, col_type)
+
+
+def _is_unique(column: Any) -> bool:
+    """True if a primary key, constraint or index makes *column* alone unique."""
+    if column.unique:
+        return True
+    table = column.table
+    keys = [
+        c.columns
+        for c in table.constraints
+        if isinstance(c, (PrimaryKeyConstraint, UniqueConstraint))
+    ]
+    keys += [i.columns for i in table.indexes if i.unique]
+    return any(len(cols) == 1 and next(iter(cols)) is column for cols in keys)
+
+
 def _apply_joins(q: Any, joins: JoinType | None, outer_join: bool) -> Any:
     """Apply a list of (model, condition) joins to a SQLAlchemy select query."""
     if not joins:
@@ -152,9 +177,7 @@ def _repeats_rows(joins: JoinType | None, *rel_lists: Sequence[Any] | None) -> b
     A to-many relationship join yields one row per related row. A raw
     join's cardinality cannot be inspected, so it counts as repeating.
     """
-    return bool(joins) or any(
-        rel.property.uselist for rels in rel_lists for rel in (rels or ())
-    )
+    return bool(joins) or any(is_to_many(rels or ()) for rels in rel_lists)
 
 
 @dataclass
@@ -169,10 +192,16 @@ class _QueryPlan:
     fb_joins: list[Any]
 
 
-def _grouped_order(clause: Any, table: Any) -> Any:
-    """Recast an order clause for a query grouped by the entity's key."""
+def _order_expr(clause: Any) -> tuple[Any, Any]:
+    """Split an order clause into its sorted operand and that operand's SQL expression."""
     inner = clause.element if isinstance(clause, UnaryExpression) else clause
     expr = inner.__clause_element__() if hasattr(inner, "__clause_element__") else inner
+    return inner, expr
+
+
+def _grouped_order(clause: Any, table: Any) -> Any:
+    """Recast an order clause for a query grouped by the entity's key."""
+    inner, expr = _order_expr(clause)
     tables = {
         t
         for c in getattr(expr, "base_columns", ())
@@ -229,6 +258,26 @@ class AsyncCrud(Generic[ModelType]):
             for col in cls.model.__mapper__.primary_key
         ]
 
+    @classmethod
+    def _key_tiebreak(cls: type[Self], order_clauses: Sequence[Any]) -> list[Any]:
+        """The primary key columns *order_clauses* leave out, so ties keep one order."""
+        ordered = [_order_expr(c)[1] for c in order_clauses]
+        return [
+            attr
+            for attr, col in zip(cls._pk_attrs(), cls.model.__mapper__.primary_key)
+            if not any(e.compare(col) for e in ordered)
+        ]
+
+    @classmethod
+    def _tiebreak_attrs(
+        cls: type[Self], cursor_column: Any
+    ) -> list[QueryableAttribute[Any]]:
+        """The primary key columns ordering rows that share a *cursor_column* value."""
+        column = cursor_column.property.columns[0]
+        if _is_unique(column):
+            return []
+        return [a for a in cls._pk_attrs() if a.property.columns[0] is not column]
+
     @classmethod
     async def _page_entities(
         cls: type[Self],
@@ -236,16 +285,18 @@ class AsyncCrud(Generic[ModelType]):
         q: Any,
         *,
         order_clauses: Sequence[Any],
-        limit: int,
+        limit: int | None,
         offset: int | None = None,
         load_options: Sequence[ExecutableOption] | None = None,
         with_for_update: _ForUpdateMode = False,
     ) -> list[ModelType]:
-        """Return up to *limit* entities, paging over distinct primary keys."""
+        """Return up to *limit* (or all) entities, paging over distinct primary keys."""
         pk_attrs = cls._pk_attrs()
         table = cls.model.__table__
-        # Fall back to the primary key so the page boundary is deterministic.
-        grouped = [_grouped_order(c, table) for c in order_clauses] or [pk_attrs[0]]
+        grouped = [
+            *(_grouped_order(c, table) for c in order_clauses),
+            *cls._key_tiebreak(order_clauses),
+        ]
         id_q = (
             q.order_by(None)
             .with_only_columns(*pk_attrs)
@@ -284,14 +335,14 @@ class AsyncCrud(Generic[ModelType]):
         *,
         repeats: bool,
         order_clauses: Sequence[Any],
-        limit: int,
+        limit: int | None,
         offset: int | None = None,
         load_options: Sequence[ExecutableOption] | None = None,
         with_for_update: _ForUpdateMode = False,
     ) -> list[ModelType]:
         """Return up to *limit* entities of *q*, by key when a join *repeats* rows."""
         if repeats:
-            # LIMIT would slice joined rows and `.unique()` shrink the page.
+            # LIMIT and OFFSET would count joined rows, not entities.
             return await cls._page_entities(
                 session,
                 q,
@@ -301,6 +352,7 @@ class AsyncCrud(Generic[ModelType]):
                 load_options=load_options,
                 with_for_update=with_for_update,
             )
+        q = q.order_by(*cls._key_tiebreak(order_clauses))
         q = _apply_for_update(q, with_for_update)
         if offset:
             q = q.offset(offset)
@@ -1184,6 +1236,7 @@ class AsyncCrud(Generic[ModelType]):
         outer_join: bool = False,
         with_for_update: _ForUpdateMode = False,
         load_options: Sequence[ExecutableOption] | None = None,
+        order_by: OrderByClause | None = None,
         schema: type[SchemaType],
     ) -> Response[SchemaType] | None: ...
 
@@ -1198,6 +1251,7 @@ class AsyncCrud(Generic[ModelType]):
         outer_join: bool = False,
         with_for_update: _ForUpdateMode = False,
         load_options: Sequence[ExecutableOption] | None = None,
+        order_by: OrderByClause | None = None,
         schema: None = ...,
     ) -> ModelType | None: ...
 
@@ -1211,6 +1265,7 @@ class AsyncCrud(Generic[ModelType]):
         outer_join: bool = False,
         with_for_update: _ForUpdateMode = False,
         load_options: Sequence[ExecutableOption] | None = None,
+        order_by: OrderByClause | None = None,
         schema: type[BaseModel] | None = None,
     ) -> ModelType | Response[Any] | None:
         """Get the first matching record, or None.
@@ -1222,6 +1277,8 @@ class AsyncCrud(Generic[ModelType]):
             outer_join: Use LEFT OUTER JOIN instead of INNER JOIN
             with_for_update: Lock the row for update
             load_options: SQLAlchemy loader options (e.g., selectinload)
+            order_by: Column or expression deciding which match comes first.
+                Without it, any matching row may be returned.
             schema: Pydantic schema to serialize the result into. When provided,
                 the result is automatically wrapped in a ``Response[schema]``.
 
@@ -1235,6 +1292,8 @@ class AsyncCrud(Generic[ModelType]):
             q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
             q = q.options(*resolved)
+        if order_by is not None:
+            q = q.order_by(order_by)
         q = _apply_for_update(q, with_for_update)
         result = await session.execute(q.limit(1))
         item = result.unique().scalars().first()
@@ -1270,7 +1329,7 @@ class AsyncCrud(Generic[ModelType]):
                 ``"nowait"`` for ``FOR UPDATE NOWAIT``, ``"skip_locked"`` for
                 ``FOR UPDATE SKIP LOCKED``.
             load_options: SQLAlchemy loader options
-            order_by: Column or list of columns to order by
+            order_by: Column or expression to order by
             limit: Max number of rows to return
             offset: Rows to skip
 
@@ -1286,7 +1345,7 @@ class AsyncCrud(Generic[ModelType]):
         if order_by is not None:
             q = q.order_by(order_by)
 
-        if limit is not None:
+        if limit is not None or offset is not None:
             return await cls._fetch_page(
                 session,
                 q,
@@ -1299,8 +1358,6 @@ class AsyncCrud(Generic[ModelType]):
             )
 
         q = _apply_for_update(q, with_for_update)
-        if offset is not None:
-            q = q.offset(offset)
         result = await session.execute(q)
         return cast(Sequence[ModelType], result.unique().scalars().all())
 
@@ -1578,7 +1635,7 @@ class AsyncCrud(Generic[ModelType]):
             joins: List of (model, condition) tuples for joining related tables
             outer_join: Use LEFT OUTER JOIN instead of INNER JOIN
             load_options: SQLAlchemy loader options
-            order_by: Column or list of columns to order by
+            order_by: Column or expression to order by
             page: Page number (1-indexed)
             items_per_page: Number of items per page
             include_total: When ``False``, skip the ``COUNT`` query;
@@ -1705,7 +1762,8 @@ class AsyncCrud(Generic[ModelType]):
             outer_join: Use LEFT OUTER JOIN instead of INNER JOIN.
             load_options: SQLAlchemy loader options. Falls back to
                 ``default_load_options`` when not provided.
-            order_by: Additional ordering applied after the cursor column.
+            order_by: Additional ordering applied after the cursor column and
+                its primary key tiebreak, which already order rows fully.
             items_per_page: Number of items per page (default 20).
             search: Search query string or SearchConfig object.
             search_fields: Fields to search in (overrides class default).
@@ -1738,16 +1796,30 @@ class AsyncCrud(Generic[ModelType]):
             filter_by=filter_by,
             facet_fields=facet_fields,
         )
+        # Rows sharing a cursor value are ordered, and resumed, by primary key.
+        tiebreak = cls._tiebreak_attrs(cursor_column)
+
         # The cursor only positions the page: facets describe the whole result.
         direction = _CursorDirection.NEXT
         if cursor is not None:
-            raw_val, direction = _decode_cursor(cursor)
+            raw_val, raw_key, direction = _decode_cursor(cursor)
             col_type = cursor_column.property.columns[0].type
             cursor_val: Any = _parse_cursor_value(raw_val, col_type)
+            # Without a key (unique column, or a cursor from before keys) resume on the value.
+            bound: Any = cursor_column
+            if tiebreak and raw_key is not None:
+                bound = tuple_(cursor_column, *tiebreak)
+                cursor_val = (
+                    cursor_val,
+                    *(
+                        _parse_key_value(v, a.property.columns[0].type)
+                        for v, a in zip(raw_key, tiebreak, strict=True)
+                    ),
+                )
             if direction is _CursorDirection.PREV:
-                plan.filters.append(cursor_column < cursor_val)
+                plan.filters.append(bound < cursor_val)
             else:
-                plan.filters.append(cursor_column > cursor_val)
+                plan.filters.append(bound > cursor_val)
 
         q = select(cls.model)
         q = _apply_joins(q, joins, outer_join)
@@ -1757,13 +1829,11 @@ class AsyncCrud(Generic[ModelType]):
         if resolved := cls._resolve_load_options(load_options):
             q = q.options(*resolved)
 
-        # Cursor column is always the primary sort; reverse direction for prev traversal
-        cursor_clause = (
-            cursor_column.desc()
-            if direction is _CursorDirection.PREV
-            else cursor_column
-        )
-        order_clauses: list[Any] = [cursor_clause]
+        # Cursor column then key is always the primary sort; reverse direction for prev traversal
+        order_clauses: list[Any] = [
+            col.desc() if direction is _CursorDirection.PREV else col
+            for col in (cursor_column, *tiebreak)
+        ]
         if order_by is not None:
             order_clauses.append(order_by)
         q = q.order_by(*order_clauses)
@@ -1784,21 +1854,22 @@ class AsyncCrud(Generic[ModelType]):
         if direction is _CursorDirection.PREV:
             items_page = list(reversed(items_page))
 
+        def _cursor_at(item: Any, to: _CursorDirection) -> str:
+            return _encode_cursor(
+                getattr(item, cursor_col_name),
+                direction=to,
+                key=[getattr(item, a.key) for a in tiebreak],
+            )
+
         # next_cursor: points past the last item in ascending order
         next_cursor: str | None = None
         if direction is _CursorDirection.NEXT:
             if has_more and items_page:
-                next_cursor = _encode_cursor(
-                    getattr(items_page[-1], cursor_col_name),
-                    direction=_CursorDirection.NEXT,
-                )
+                next_cursor = _cursor_at(items_page[-1], _CursorDirection.NEXT)
         else:
             # Going backward: always provide a next_cursor to allow returning forward
             if items_page:
-                next_cursor = _encode_cursor(
-                    getattr(items_page[-1], cursor_col_name),
-                    direction=_CursorDirection.NEXT,
-                )
+                next_cursor = _cursor_at(items_page[-1], _CursorDirection.NEXT)
 
         # prev_cursor: points before the first item in ascending order
         prev_cursor: str | None = None
@@ -1806,9 +1877,7 @@ class AsyncCrud(Generic[ModelType]):
             (direction is _CursorDirection.NEXT and cursor is not None)
             or (direction is _CursorDirection.PREV and has_more)
         ):
-            prev_cursor = _encode_cursor(
-                getattr(items_page[0], cursor_col_name), direction=_CursorDirection.PREV
-            )
+            prev_cursor = _cursor_at(items_page[0], _CursorDirection.PREV)
 
         items: list[Any] = [schema.model_validate(item) for item in items_page]
 

{fastapi_toolsets-5.1.6 → fastapi_toolsets-5.1.7}/src/fastapi_toolsets/crud/search.py

@@ -11,6 +11,7 @@ from sqlalchemy import (
     Table,
     and_,
     any_,
+    false,
     func,
     or_,
     select,
@@ -32,7 +33,7 @@ from sqlalchemy.types import (
     Uuid,
 )
 
-from .._orm import key_expr
+from .._orm import is_to_many, key_expr
 from ..exceptions import (
     InvalidFacetFilterError,
     InvalidSearchColumnError,
@@ -120,6 +121,11 @@ class SearchPlan:
 
 
 _EMPTY_PLAN = SearchPlan([], [], [], [])
+_NO_MATCH_PLAN = SearchPlan([false()], [], [false()], [])
+
+_INTEGER_CHARS = frozenset("0123456789-")
+_UUID_CHARS = frozenset("0123456789abcdef-")
+_LIKE_SPECIAL = frozenset("%_\\")
 
 _Entry = tuple[tuple[Any, ...], "ColumnElement[bool]"]
 
@@ -165,18 +171,44 @@ def build_search_plan(
             raise InvalidSearchColumnError(search_column, sorted(index))
         fields = [index[search_column]]
 
-    entries = [(_field_rels(f), _search_condition(f, query, config)) for f in fields]
+    chars = set(query if config.case_sensitive else query.lower())
+    possible = [f for f in fields if _can_contain(_field_column(f), chars)]
+    if not possible or (config.match_mode == "all" and len(possible) < len(fields)):
+        return _NO_MATCH_PLAN
+
+    entries = [(_field_rels(f), _search_condition(f, query, config)) for f in possible]
     page = _render_search(entries, [], config.match_mode)
-    to_many = [e for e in entries if any(r.property.uselist for r in e[0])]
+    related = [e for e in entries if e[0]]
+    to_many = [e for e in related if is_to_many(e[0])]
     # All or nothing, so the aggregate form matches the page form exactly.
-    if to_many and all(_semi_joinable(r) for rels, _ in to_many for r in rels):
-        joined = [e for e in entries if e not in to_many]
+    if related and _all_semi_joinable(related):
+        agg = _render_search([], entries, config.match_mode)
+    elif to_many and _all_semi_joinable(to_many):
+        # Not `e not in to_many`: == on relationship attributes builds SQL.
+        joined = [e for e in entries if not is_to_many(e[0])]
         agg = _render_search(joined, to_many, config.match_mode)
     else:
         agg = page
     return SearchPlan(*page, *agg)
 
 
+def _can_contain(column: Any, chars: set[str]) -> bool:
+    """False when the text of an integer or UUID column can never contain *chars*."""
+    if chars & _LIKE_SPECIAL:
+        return True
+    col_type = column.type
+    if isinstance(col_type, Integer):
+        return chars <= _INTEGER_CHARS
+    if isinstance(col_type, Uuid):
+        return chars <= _UUID_CHARS
+    return True
+
+
+def _all_semi_joinable(entries: Sequence[_Entry]) -> bool:
+    """True if every relationship of *entries* can be filtered with a subquery."""
+    return all(_semi_joinable(rel) for rels, _ in entries for rel in rels)
+
+
 def _render_search(
     joined: Sequence[_Entry], subqueries: Sequence[_Entry], match_mode: str
 ) -> tuple[list["ColumnElement[bool]"], list[InstrumentedAttribute[Any]]]:
@@ -221,11 +253,16 @@ def _field_rels(field: SearchFieldType) -> tuple[Any, ...]:
     return tuple(field[:-1]) if isinstance(field, tuple) else ()
 
 
+def _field_column(field: SearchFieldType) -> Any:
+    """Column a search field reads, at the end of its relationship path."""
+    return field[-1] if isinstance(field, tuple) else field
+
+
 def _search_condition(
     field: SearchFieldType, query: str, config: SearchConfig
 ) -> "ColumnElement[bool]":
     """LIKE/ILIKE condition on the field's column."""
-    column = field[-1] if isinstance(field, tuple) else field
+    column = _field_column(field)
     # Cast to String only when needed, to preserve pg_trgm GIN index
     # usability on already-String columns.
     column_as_string = (
@@ -252,6 +289,7 @@ def _is_plain_join(condition: Any, pairs: Sequence[tuple[Any, Any]]) -> bool:
     return found == expected
 
 
+@functools.lru_cache(maxsize=128)
 def _semi_joinable(rel: Any) -> bool:
     """True if *rel* can be filtered with an `IN (subquery)` instead of a join."""
     prop = rel.property
@@ -470,7 +508,7 @@ def _facet_rows(
         prefiltered
         or not all(_semi_joinable(rel) for rel in rels)
         or any(rel.property.uselist and str(rel) in joined for rel in rels)
-        or (base_joins and not any(rel.property.uselist for rel in rels))
+        or (base_joins and not is_to_many(rels))
     )
     joins = [*base_joins, *rels] if keep_join else base_joins
     rows = apply_search_joins(select(model), joins)

{fastapi_toolsets-5.1.6 → fastapi_toolsets-5.1.7}/src/fastapi_toolsets/dependencies.py

@@ -5,7 +5,7 @@ import typing
 from collections.abc import Callable, Sequence
 from typing import Any, cast
 
-from fastapi import Depends
+from fastapi import Body, Depends, Path
 from fastapi.params import Depends as DependsClass
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.sql.base import ExecutableOption
@@ -31,10 +31,14 @@ def _fetch_dependency(
     *,
     session_dep: SessionDependency,
     param_name: str,
+    source: Any,
     crud: type[AsyncCrud[ModelType]] | None,
     load_options: Sequence[ExecutableOption] | None,
 ) -> ModelType:
-    """Build a Depends() that fetches one row by ``field == <param_name>``."""
+    """Build a Depends() that fetches one row by ``field == <param_name>``.
+
+    *source* (``Path()`` or ``Body()``) tells FastAPI where the value comes from.
+    """
     session_callable = _unwrap_session_dep(session_dep)
     if crud is not None and crud.model is not model:
         raise ValueError(
@@ -57,6 +61,7 @@ def _fetch_dependency(
                 param_name,
                 inspect.Parameter.KEYWORD_ONLY,
                 annotation=field.type.python_type,
+                default=source,
             ),
             inspect.Parameter(
                 "session",
@@ -112,6 +117,7 @@ def PathDependency(
         field,
         session_dep=session_dep,
         param_name=param_name or f"{model.__name__.lower()}_{field.key}",
+        source=Path(),
         crud=crud,
         load_options=load_options,
     )
@@ -132,7 +138,8 @@ def BodyDependency(
         model: SQLAlchemy model class
         field: Model field to filter by (e.g., User.id)
         session_dep: Session dependency function (e.g., get_db)
-        body_field: Name of the field in the request body
+        body_field: Key of the JSON request body holding the value. Other body
+            parameters of the endpoint then sit under their own names.
         crud: Existing CRUD class to fetch with, so its ``default_load_options``
             apply. Defaults to a bare ``CrudFactory(model)``.
         load_options: SQLAlchemy loader options for the fetch. Overrides the CRUD's
@@ -161,6 +168,7 @@ def BodyDependency(
         field,
         session_dep=session_dep,
         param_name=body_field,
+        source=Body(embed=True),
         crud=crud,
         load_options=load_options,
     )

{fastapi_toolsets-5.1.6 → fastapi_toolsets-5.1.7}/src/fastapi_toolsets/models/watched.py

@@ -289,21 +289,29 @@ async def _batch_reload(
 
 
 class _EventSessionTransaction(AsyncSessionTransaction):
-    """Transaction context manager that dispatches on a real commit."""
+    """Transaction that dispatches on a real commit, on block exit or ``commit()``."""
 
     __slots__ = ()
 
-    async def __aexit__(self, type_: object, value: object, traceback: object) -> None:
+    def _committing_session(self) -> "EventSession | None":
+        """The EventSession a commit of this transaction would really commit."""
         session = self.session
-        commits = (
-            type_ is None
-            and not self.nested
-            and isinstance(session, EventSession)
-            and self.is_active
-        )
-        preloaded = _snapshot_loaded_relationships(session) if commits else {}
+        if self.nested or not self.is_active or not isinstance(session, EventSession):
+            return None
+        return session
+
+    async def __aexit__(self, type_: object, value: object, traceback: object) -> None:
+        session = self._committing_session() if type_ is None else None
+        preloaded = {} if session is None else _snapshot_loaded_relationships(session)
         await super().__aexit__(type_, value, traceback)
-        if commits:
+        if session is not None:
+            await session._dispatch_pending(preloaded)
+
+    async def commit(self) -> None:
+        session = self._committing_session()
+        preloaded = {} if session is None else _snapshot_loaded_relationships(session)
+        await super().commit()
+        if session is not None:
             await session._dispatch_pending(preloaded)