fastapi-toolsets 5.1.0__tar.gz → 5.1.2__tar.gz

{fastapi_toolsets-5.1.0 → fastapi_toolsets-5.1.2}/PKG-INFO

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

fastapi_toolsets-5.1.2/pyproject.toml

@@ -0,0 +1,133 @@
+[project]
+name = "fastapi-toolsets"
+version = "5.1.2"
+description = "Production-ready utilities for FastAPI applications"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "fastapi",
+    "sqlalchemy",
+    "postgresql",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Framework :: FastAPI",
+    "Framework :: Pydantic",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development",
+    "Typing :: Typed",
+]
+dependencies = [
+    "asyncpg>=0.29.0",
+    "fastapi>=0.100.0",
+    "pydantic>=2.0",
+    "sqlalchemy[asyncio]>=2.0",
+]
+
+[[project.authors]]
+name = "d3vyce"
+email = "contact@d3vyce.fr"
+
+[project.urls]
+Homepage = "https://github.com/d3vyce/fastapi-toolsets"
+Documentation = "https://fastapi-toolsets.d3vyce.fr/"
+Repository = "https://github.com/d3vyce/fastapi-toolsets"
+Issues = "https://github.com/d3vyce/fastapi-toolsets/issues"
+
+[project.optional-dependencies]
+cli = ["typer>=0.9.0"]
+metrics = ["prometheus_client>=0.20.0"]
+pytest = [
+    "httpx>=0.25.0",
+    "pytest-xdist>=3.0.0",
+    "pytest>=8.0.0",
+]
+all = ["fastapi-toolsets[cli,metrics,pytest]"]
+
+[project.scripts]
+manager = "fastapi_toolsets.cli.app:cli"
+
+[dependency-groups]
+dev = [
+    { include-group = "tests" },
+    { include-group = "docs" },
+    { include-group = "docs-src" },
+    "fastapi-toolsets[all]",
+    "prek>=0.3.8",
+    "ruff>=0.1.0",
+    "ty>=0.0.1a0",
+]
+tests = [
+    "async-lru>=1.0",
+    "coverage>=7.0.0",
+    "httpx>=0.25.0",
+    "pytest-anyio>=0.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-xdist>=3.0.0",
+    "pytest>=8.0.0",
+]
+docs = [
+    "mike",
+    "mkdocstrings-python>=2.0.2",
+    "zensical>=0.0.30",
+]
+docs-src = ["bcrypt>=4.0.0"]
+
+[build-system]
+requires = ["uv_build>=0.10,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff.format]
+exclude = ["*.md"]
+
+[tool.ruff.lint]
+extend-select = ["E712"]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = [
+    "fastapi.Depends",
+    "fastapi.Security",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "RUF012",
+    "RUF059",
+    "SIM117",
+    "DTZ001",
+    "S110",
+    "BLE001",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.coverage.run]
+source = ["src/fastapi_toolsets"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[tool.uv.sources.mike]
+git = "https://github.com/squidfunk/mike.git"
+tag = "2.2.0+zensical-0.1.0"

fastapi_toolsets-5.1.0/pyproject.toml → fastapi_toolsets-5.1.2/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "5.1.0"
+version = "5.1.2"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"
@@ -91,7 +91,7 @@ docs-src = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.10,<0.12.0"]
+requires = ["uv_build>=0.10,<0.13.0"]
 build-backend = "uv_build"
 
 [tool.ruff.format]
@@ -101,7 +101,7 @@ exclude = ["*.md"]
 extend-select = ["E712"]
 
 [tool.ruff.lint.flake8-bugbear]
-extend-immutable-calls = ["fastapi.Depends"]
+extend-immutable-calls = ["fastapi.Depends", "fastapi.Security"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = ["RUF012", "RUF059", "SIM117", "DTZ001", "S110", "BLE001"]

{fastapi_toolsets-5.1.0 → fastapi_toolsets-5.1.2}/src/fastapi_toolsets/__init__.py

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

{fastapi_toolsets-5.1.0 → fastapi_toolsets-5.1.2}/src/fastapi_toolsets/crud/factory.py

@@ -14,12 +14,25 @@ from typing import Any, ClassVar, Generic, Literal, Self, TypeAlias, cast, overl
 
 from fastapi import Query
 from pydantic import BaseModel
-from sqlalchemy import Date, DateTime, Float, Integer, Numeric, Uuid, and_, func, select
+from sqlalchemy import (
+    Date,
+    DateTime,
+    Float,
+    Integer,
+    Numeric,
+    Uuid,
+    and_,
+    func,
+    select,
+    tuple_,
+)
 from sqlalchemy.dialects.postgresql import insert
 from sqlalchemy.exc import NoResultFound
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase, QueryableAttribute, selectinload
+from sqlalchemy.sql import operators
 from sqlalchemy.sql.base import ExecutableOption
+from sqlalchemy.sql.elements import UnaryExpression
 from sqlalchemy.sql.roles import WhereHavingRole
 
 from ..db import transaction
@@ -128,6 +141,32 @@ def _apply_joins(q: Any, joins: JoinType | None, outer_join: bool) -> Any:
     return q
 
 
+def _fans_out(
+    search_joins: Sequence[Any] | None, order_joins: Sequence[Any] | None
+) -> bool:
+    """True if any relationship join yields a collection."""
+    return any(
+        rel.property.uselist for rel in (*(search_joins or ()), *(order_joins or ()))
+    )
+
+
+def _grouped_order(clause: Any, table: Any) -> Any:
+    """Recast an order clause for a query grouped by the entity's key."""
+    inner = clause.element if isinstance(clause, UnaryExpression) else clause
+    expr = inner.__clause_element__() if hasattr(inner, "__clause_element__") else inner
+    tables = {
+        t
+        for c in getattr(expr, "base_columns", ())
+        if (t := getattr(c, "table", None)) is not None
+    }
+    if tables and tables <= {table}:
+        return clause
+    agg = func.min(inner)
+    if isinstance(clause, UnaryExpression) and clause.modifier is operators.desc_op:
+        return agg.desc()
+    return agg.asc()
+
+
 class AsyncCrud(Generic[ModelType]):
     """Generic async CRUD operations for SQLAlchemy models.
 
@@ -163,6 +202,64 @@ class AsyncCrud(Generic[ModelType]):
             ):
                 cls.searchable_fields = [pk_col, *raw_fields]
 
+    @classmethod
+    def _pk_attrs(cls: type[Self]) -> list[QueryableAttribute[Any]]:
+        """The model's primary key columns as instrumented attributes."""
+        return [
+            getattr(cls.model, cast(str, col.key))
+            for col in cls.model.__mapper__.primary_key
+        ]
+
+    @classmethod
+    async def _page_entities(
+        cls: type[Self],
+        session: AsyncSession,
+        q: Any,
+        *,
+        order_clauses: Sequence[Any],
+        limit: int,
+        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."""
+        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]]
+        id_q = (
+            q.order_by(None)
+            .with_only_columns(*pk_attrs)
+            .group_by(*pk_attrs)
+            .order_by(*grouped)
+            .limit(limit)
+        )
+        if offset:
+            id_q = id_q.offset(offset)
+        rows = (await session.execute(id_q)).all()
+        ids = [row[0] if len(pk_attrs) == 1 else tuple(row) for row in rows]
+        if not ids:
+            return []
+
+        where = (
+            pk_attrs[0].in_(ids) if len(pk_attrs) == 1 else tuple_(*pk_attrs).in_(ids)
+        )
+        item_q = select(cls.model).where(where)
+        if resolved := cls._resolve_load_options(load_options):
+            item_q = item_q.options(*resolved)
+        item_q = _apply_for_update(item_q, with_for_update)
+        found = (await session.execute(item_q)).unique().scalars().all()
+
+        rank = {pk: n for n, pk in enumerate(ids)}
+
+        def _key(obj: Any) -> Any:
+            values = tuple(getattr(obj, a.key) for a in pk_attrs)
+            return values[0] if len(pk_attrs) == 1 else values
+
+        return cast(
+            list[ModelType], sorted(found, key=lambda o: rank.get(_key(o), len(ids)))
+        )
+
     @classmethod
     def _resolve_load_options(
         cls, load_options: Sequence[ExecutableOption] | None
@@ -173,30 +270,17 @@ class AsyncCrud(Generic[ModelType]):
         return cls.default_load_options
 
     @classmethod
-    def _capture_pk_values(cls: type[Self], instance: ModelType) -> dict[str, Any]:
-        """Capture PK values off instance — call before commit expires attributes."""
-        return {
-            cast(str, col.key): getattr(instance, cast(str, col.key))
-            for col in cls.model.__mapper__.primary_key
-        }
-
-    @classmethod
-    async def _reload_with_options_by_pk(
-        cls: type[Self], session: AsyncSession, pk_values: dict[str, Any]
+    async def _reload_with_options(
+        cls: type[Self], session: AsyncSession, instance: DeclarativeBase
     ) -> ModelType:
-        """Re-query by previously captured PK values, with default_load_options applied."""
-        # Only called when cls.default_load_options is set (see call sites).
+        """Re-query instance by PK with default_load_options applied."""
+        mapper = cls.model.__mapper__
         pk_filters = [
-            getattr(cls.model, key) == value for key, value in pk_values.items()
+            getattr(cls.model, cast(str, col.key))
+            == getattr(instance, cast(str, col.key))
+            for col in mapper.primary_key
         ]
-        q = select(cls.model).where(and_(*pk_filters))
-        q = q.execution_options(populate_existing=True)
-        q = q.options(*cast(Sequence[ExecutableOption], cls.default_load_options))
-        result = await session.execute(q)
-        item = result.unique().scalar_one_or_none()
-        if item is None:  # pragma: no cover — row was just flushed in this transaction
-            raise NotFoundError()
-        return cast(ModelType, item)
+        return await cls.get(session, filters=pk_filters)
 
     @classmethod
     async def _resolve_m2m(
@@ -750,14 +834,9 @@ class AsyncCrud(Generic[ModelType]):
                     setattr(db_model, rel_attr, related_instances)
 
             session.add(db_model)
-            pk_values: dict[str, Any] | None = None
-            if cls.default_load_options:
-                await session.flush()
-                pk_values = cls._capture_pk_values(db_model)
-        if pk_values is not None:
-            db_model = await cls._reload_with_options_by_pk(session, pk_values)
-        else:
-            await session.refresh(db_model)
+        await session.refresh(db_model)
+        if cls.default_load_options:
+            db_model = await cls._reload_with_options(session, db_model)
         result = cast(ModelType, db_model)
         if schema:
             return Response(data=schema.model_validate(result))
@@ -1023,9 +1102,21 @@ class AsyncCrud(Generic[ModelType]):
             q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
             q = q.options(*resolved)
-        q = _apply_for_update(q, with_for_update)
         if order_by is not None:
             q = q.order_by(order_by)
+
+        if limit is not None and joins:
+            return await cls._page_entities(
+                session,
+                q,
+                order_clauses=[] if order_by is None else [order_by],
+                limit=limit,
+                offset=offset,
+                load_options=load_options,
+                with_for_update=with_for_update,
+            )
+
+        q = _apply_for_update(q, with_for_update)
         if offset is not None:
             q = q.offset(offset)
         if limit is not None:
@@ -1122,15 +1213,9 @@ class AsyncCrud(Generic[ModelType]):
                 m2m_resolved = await cls._resolve_m2m(session, obj, only_set=True)
                 for rel_attr, related_instances in m2m_resolved.items():
                     setattr(db_model, rel_attr, related_instances)
-
-            pk_values: dict[str, Any] | None = None
-            if cls.default_load_options:
-                await session.flush()
-                pk_values = cls._capture_pk_values(db_model)
-        if pk_values is not None:
-            db_model = await cls._reload_with_options_by_pk(session, pk_values)
-        else:
-            await session.refresh(db_model)
+        await session.refresh(db_model)
+        if cls.default_load_options:
+            db_model = await cls._reload_with_options(session, db_model)
         if schema:
             return Response(data=schema.model_validate(db_model))
         return db_model
@@ -1374,17 +1459,31 @@ 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)
-
-        if include_total:
-            q = q.offset(offset).limit(items_per_page)
-            result = await session.execute(q)
+        order_clauses: list[Any] = [] if order_by is None else [order_by]
+        q = q.order_by(*order_clauses)
+
+        fetch_limit = items_per_page if include_total else items_per_page + 1
+        total_count: int | None = None
+        # A to-many join repeats each entity, so LIMIT would slice joined rows
+        # and `.unique()` would shrink the page after the fact.
+        if _fans_out(search_joins, order_joins):
+            raw_items = await cls._page_entities(
+                session,
+                q,
+                order_clauses=order_clauses,
+                limit=fetch_limit,
+                offset=offset,
+                load_options=load_options,
+            )
+        else:
+            result = await session.execute(q.offset(offset).limit(fetch_limit))
             raw_items = cast(list[ModelType], result.unique().scalars().all())
+        fetched = len(raw_items)
+        raw_items = raw_items[:items_per_page]
 
+        if include_total:
             # Count query (with same joins and filters)
-            pk_col = cls.model.__mapper__.primary_key[0]
-            count_q = select(func.count(func.distinct(getattr(cls.model, pk_col.name))))
+            count_q = select(func.count(func.distinct(cls._pk_attrs()[0])))
             count_q = count_q.select_from(cls.model)
 
             # Apply explicit joins to count query
@@ -1397,16 +1496,11 @@ class AsyncCrud(Generic[ModelType]):
                 count_q = count_q.where(and_(*filters))
 
             count_result = await session.execute(count_q)
-            total_count: int = count_result.scalar_one()
+            total_count = count_result.scalar_one()
             has_more = page * items_per_page < total_count
         else:
-            # Fetch one extra row to detect if a next page exists without COUNT
-            q = q.offset(offset).limit(items_per_page + 1)
-            result = await session.execute(q)
-            raw_items = cast(list[ModelType], result.unique().scalars().all())
-            has_more = len(raw_items) > items_per_page
-            raw_items = raw_items[:items_per_page]
-            total_count = None
+            # One extra row was fetched to detect a next page without COUNT
+            has_more = fetched > items_per_page
 
         items: list[Any] = [schema.model_validate(item) for item in raw_items]
 
@@ -1543,18 +1637,30 @@ class AsyncCrud(Generic[ModelType]):
             q = q.options(*resolved)
 
         # Cursor column is always the primary sort; reverse direction for prev traversal
-        if direction is _CursorDirection.PREV:
-            q = q.order_by(cursor_column.desc())
-        else:
-            q = q.order_by(cursor_column)
+        cursor_clause = (
+            cursor_column.desc()
+            if direction is _CursorDirection.PREV
+            else cursor_column
+        )
+        order_clauses: list[Any] = [cursor_clause]
         if order_by is not None:
-            q = q.order_by(order_by)
-
-        # Fetch one extra to detect whether another page exists in this direction
-        q = q.limit(items_per_page + 1)
-        result = await session.execute(q)
-        raw_items = cast(list[ModelType], result.unique().scalars().all())
-
+            order_clauses.append(order_by)
+        q = q.order_by(*order_clauses)
+
+        # One extra row detects whether another page exists in this direction.
+        # Under a to-many join that extra row may be a duplicate of one already
+        # on the page, which reads as "no next page" and ends traversal early.
+        if _fans_out(search_joins, order_joins):
+            raw_items = await cls._page_entities(
+                session,
+                q,
+                order_clauses=order_clauses,
+                limit=items_per_page + 1,
+                load_options=load_options,
+            )
+        else:
+            result = await session.execute(q.limit(items_per_page + 1))
+            raw_items = cast(list[ModelType], result.unique().scalars().all())
         has_more = len(raw_items) > items_per_page
         items_page = raw_items[:items_per_page]
 

{fastapi_toolsets-5.1.0 → fastapi_toolsets-5.1.2}/src/fastapi_toolsets/crud/search.py

@@ -160,9 +160,11 @@ def build_search_filters(
             column = field
 
         # Build the filter (cast to String only when needed, to preserve
-        # pg_trgm GIN index usability on already-String columns)
+        # pg_trgm GIN index usability on already-String columns).
         column_as_string = (
-            column if isinstance(column.type, String) else column.cast(String)
+            column
+            if isinstance(column.type, String) and not isinstance(column.type, Enum)
+            else column.cast(String)
         )
         if config.case_sensitive:
             filters.append(column_as_string.like(f"%{query}%"))

{fastapi_toolsets-5.1.0 → fastapi_toolsets-5.1.2}/src/fastapi_toolsets/db/core.py

@@ -66,10 +66,8 @@ class _CommitOnResponseMiddleware:
 
         async def send_wrapper(message: Message) -> None:
             if message["type"] == "http.response.start":
-                # ``scope["state"]`` is the same dict ``request.state`` writes
-                # to, so this is the session stashed by the dependency.
                 state = scope.get("state")
-                session = state.get(self.state_attr) if state else None
+                session = state.pop(self.state_attr, None) if state else None
                 if session is not None and session.in_transaction():
                     await session.commit()
             await send(message)
@@ -158,7 +156,6 @@ class Database:
         # Private, per-instance state attribute; cannot collide with another
         # Database or be mismatched against the middleware.
         self._state_attr = f"_ft_db_session_{id(self):x}"
-        self._middleware_installed = False
         self._disposed = False
 
     async def _dispose(self) -> None:
@@ -206,7 +203,6 @@ class Database:
             ```
         """
         app.add_middleware(_CommitOnResponseMiddleware, state_attr=self._state_attr)
-        self._middleware_installed = True
 
         inner_lifespan = app.router.lifespan_context
 
@@ -243,10 +239,17 @@ class Database:
                 return await UserCrud.get(session, [User.id == user_id])
             ```
         """
+        borrowed = getattr(request.state, self._state_attr, None)
+        if borrowed is not None:
+            yield borrowed
+            return
         async with self._open() as session:
             setattr(request.state, self._state_attr, session)
             yield session
-            if not self._middleware_installed and session.in_transaction():
+            if (
+                getattr(request.state, self._state_attr, None) is session
+                and session.in_transaction()
+            ):
                 await session.commit()
 
     @asynccontextmanager

{fastapi_toolsets-5.1.0 → fastapi_toolsets-5.1.2}/src/fastapi_toolsets/dependencies.py

@@ -2,14 +2,15 @@
 
 import inspect
 import typing
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from typing import Any, cast
 
 from fastapi import Depends
 from fastapi.params import Depends as DependsClass
 from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.sql.base import ExecutableOption
 
-from .crud import CrudFactory
+from .crud import AsyncCrud, CrudFactory
 from .types import ModelType, SessionDependency
 
 __all__ = ["BodyDependency", "PathDependency"]
@@ -24,12 +25,59 @@ def _unwrap_session_dep(session_dep: SessionDependency) -> Callable[..., Any]:
     return session_dep
 
 
+def _fetch_dependency(
+    model: type[ModelType],
+    field: Any,
+    *,
+    session_dep: SessionDependency,
+    param_name: str,
+    crud: type[AsyncCrud[ModelType]] | None,
+    load_options: Sequence[ExecutableOption] | None,
+) -> ModelType:
+    """Build a Depends() that fetches one row by ``field == <param_name>``."""
+    session_callable = _unwrap_session_dep(session_dep)
+    if crud is not None and crud.model is not model:
+        raise ValueError(
+            f"crud is bound to {crud.model.__name__}, not {model.__name__}"
+        )
+    crud = crud or CrudFactory(model)
+
+    # `session` has no default here: the __signature__ override below is what
+    # FastAPI reads, and it always passes `session` explicitly.
+    async def dependency(session: AsyncSession, **kwargs: Any) -> ModelType:
+        return await crud.get(
+            session,
+            filters=[field == kwargs[param_name]],
+            load_options=load_options,
+        )
+
+    dependency.__signature__ = inspect.Signature(  # ty:ignore[unresolved-attribute]
+        parameters=[
+            inspect.Parameter(
+                param_name,
+                inspect.Parameter.KEYWORD_ONLY,
+                annotation=field.type.python_type,
+            ),
+            inspect.Parameter(
+                "session",
+                inspect.Parameter.KEYWORD_ONLY,
+                annotation=AsyncSession,
+                default=Depends(session_callable),
+            ),
+        ]
+    )
+
+    return cast(ModelType, Depends(cast(Callable[..., ModelType], dependency)))
+
+
 def PathDependency(
     model: type[ModelType],
     field: Any,
     *,
     session_dep: SessionDependency,
     param_name: str | None = None,
+    crud: type[AsyncCrud[ModelType]] | None = None,
+    load_options: Sequence[ExecutableOption] | None = None,
 ) -> ModelType:
     """Create a dependency that fetches a DB object from a path parameter.
 
@@ -38,6 +86,10 @@ def PathDependency(
         field: Model field to filter by (e.g., User.id)
         session_dep: Session dependency function (e.g., get_db)
         param_name: Path parameter name (defaults to model_field, e.g., user_id)
+        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
+            ``default_load_options`` entirely rather than merging with them.
 
     Returns:
         A Depends() instance that resolves to the model instance
@@ -55,36 +107,14 @@ def PathDependency(
         ): ...
         ```
     """
-    session_callable = _unwrap_session_dep(session_dep)
-    crud = CrudFactory(model)
-    name = (
-        param_name
-        if param_name is not None
-        else f"{model.__name__.lower()}_{field.key}"
+    return _fetch_dependency(
+        model,
+        field,
+        session_dep=session_dep,
+        param_name=param_name or f"{model.__name__.lower()}_{field.key}",
+        crud=crud,
+        load_options=load_options,
     )
-    python_type = field.type.python_type
-
-    async def dependency(
-        session: AsyncSession = Depends(session_callable), **kwargs: Any
-    ) -> ModelType:
-        value = kwargs[name]
-        return await crud.get(session, filters=[field == value])
-
-    dependency.__signature__ = inspect.Signature(  # ty:ignore[unresolved-attribute]
-        parameters=[
-            inspect.Parameter(
-                name, inspect.Parameter.KEYWORD_ONLY, annotation=python_type
-            ),
-            inspect.Parameter(
-                "session",
-                inspect.Parameter.KEYWORD_ONLY,
-                annotation=AsyncSession,
-                default=Depends(session_callable),
-            ),
-        ]
-    )
-
-    return cast(ModelType, Depends(cast(Callable[..., ModelType], dependency)))
 
 
 def BodyDependency(
@@ -93,6 +123,8 @@ def BodyDependency(
     *,
     session_dep: SessionDependency,
     body_field: str,
+    crud: type[AsyncCrud[ModelType]] | None = None,
+    load_options: Sequence[ExecutableOption] | None = None,
 ) -> ModelType:
     """Create a dependency that fetches a DB object from a body field.
 
@@ -101,6 +133,10 @@ def BodyDependency(
         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
+        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
+            ``default_load_options`` entirely rather than merging with them.
 
     Returns:
         A Depends() instance that resolves to the model instance
@@ -120,28 +156,11 @@ def BodyDependency(
         ): ...
         ```
     """
-    session_callable = _unwrap_session_dep(session_dep)
-    crud = CrudFactory(model)
-    python_type = field.type.python_type
-
-    async def dependency(
-        session: AsyncSession = Depends(session_callable), **kwargs: Any
-    ) -> ModelType:
-        value = kwargs[body_field]
-        return await crud.get(session, filters=[field == value])
-
-    dependency.__signature__ = inspect.Signature(  # ty:ignore[unresolved-attribute]
-        parameters=[
-            inspect.Parameter(
-                body_field, inspect.Parameter.KEYWORD_ONLY, annotation=python_type
-            ),
-            inspect.Parameter(
-                "session",
-                inspect.Parameter.KEYWORD_ONLY,
-                annotation=AsyncSession,
-                default=Depends(session_callable),
-            ),
-        ]
+    return _fetch_dependency(
+        model,
+        field,
+        session_dep=session_dep,
+        param_name=body_field,
+        crud=crud,
+        load_options=load_options,
     )
-
-    return cast(ModelType, Depends(cast(Callable[..., ModelType], dependency)))

{fastapi_toolsets-5.1.0 → fastapi_toolsets-5.1.2}/src/fastapi_toolsets/models/watched.py

@@ -8,6 +8,7 @@ from typing import Any
 from sqlalchemy import event, select, tuple_
 from sqlalchemy import inspect as sa_inspect
 from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
 from sqlalchemy.orm.attributes import set_committed_value as _sa_set_committed_value
 
 from ..logger import get_logger
@@ -189,17 +190,44 @@ async def _invoke_callback(
         await result
 
 
+def _loaded_relationships(obj: Any) -> set[str]:
+    """Relationship keys currently loaded on *obj*."""
+    state = sa_inspect(obj)
+    unloaded = state.unloaded
+    return {
+        rel.key
+        for rel in state.mapper.relationships
+        if rel.key not in unloaded and rel.lazy not in ("dynamic", "write_only")
+    }
+
+
+def _snapshot_loaded_relationships(session: Any) -> dict[int, set[str]]:
+    """Record loaded relationships for the tracked objects, keyed by ``id``."""
+    objs = list(session.info.get(_SESSION_CREATES, []))
+    objs += [obj for obj, _ in session.info.get(_SESSION_UPDATES, {}).values()]
+    return {id(obj): _loaded_relationships(obj) for obj in objs}
+
+
 async def _batch_reload(
-    session: AsyncSession, model: type, pk_tuples: list[tuple[Any, ...]]
+    session: AsyncSession,
+    model: type,
+    objs: list[Any],
+    preloaded: dict[int, set[str]],
 ) -> None:
-    """Re-populate all rows of *model* identified by *pk_tuples* in one round trip."""
+    """Re-populate all rows of *model* in one round trip."""
     pk_cols = sa_inspect(model, raiseerr=True).primary_key
+    pk_tuples = [sa_inspect(obj).key[1] for obj in objs]
     where = (
         pk_cols[0].in_([pk[0] for pk in pk_tuples])
         if len(pk_cols) == 1
         else tuple_(*pk_cols).in_(pk_tuples)
     )
     q = select(model).where(where).execution_options(populate_existing=True)
+    loaded: set[str] = set()
+    for obj in objs:
+        loaded |= preloaded.get(id(obj), set())
+    if loaded:
+        q = q.options(*(selectinload(getattr(model, key)) for key in loaded))
     await session.execute(q)
 
 
@@ -207,6 +235,7 @@ class EventSession(AsyncSession):
     """AsyncSession subclass that dispatches lifecycle callbacks after commit."""
 
     async def commit(self) -> None:
+        preloaded = _snapshot_loaded_relationships(self)
         await super().commit()
 
         creates: list[Any] = self.info.pop(_SESSION_CREATES, [])
@@ -249,25 +278,25 @@ class EventSession(AsyncSession):
         # session.get() per object.
         create_items: list[Any] = []
         update_items: list[tuple[Any, dict[str, dict[str, Any]]]] = []
-        pk_by_type: dict[type, list[tuple[Any, ...]]] = {}
+        objs_by_type: dict[type, list[Any]] = {}
 
         for obj in creates:
             state = sa_inspect(obj, raiseerr=False)
             if state is None or state.detached or state.transient:  # pragma: no cover
                 continue
             create_items.append(obj)
-            pk_by_type.setdefault(type(obj), []).append(state.key[1])
+            objs_by_type.setdefault(type(obj), []).append(obj)
 
         for obj, changes in field_changes.values():
             state = sa_inspect(obj, raiseerr=False)
             if state is None or state.detached or state.transient:  # pragma: no cover
                 continue
             update_items.append((obj, changes))
-            pk_by_type.setdefault(type(obj), []).append(state.key[1])
+            objs_by_type.setdefault(type(obj), []).append(obj)
 
-        for model, pk_tuples in pk_by_type.items():
+        for model, objs in objs_by_type.items():
             try:
-                await _batch_reload(self, model, pk_tuples)
+                await _batch_reload(self, model, objs, preloaded)
             except Exception as exc:
                 _logger.error(_CALLBACK_ERROR_MSG, exc_info=exc)