dynamicforms-fastapi-viewsets 0.12.1__tar.gz → 0.13.1__tar.gz

{dynamicforms_fastapi_viewsets-0.12.1 → dynamicforms_fastapi_viewsets-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dynamicforms-fastapi-viewsets
-Version: 0.12.1
+Version: 0.13.1
 Summary: Django REST Framework-style viewsets for FastAPI, with optional Celery-backed async execution and a Vue/TypeScript client counterpart.
 Project-URL: Homepage, https://github.com/dynamicforms/fastapi-viewsets
 Project-URL: Repository, https://github.com/dynamicforms/fastapi-viewsets

{dynamicforms_fastapi_viewsets-0.12.1 → dynamicforms_fastapi_viewsets-0.13.1}/fastapi_viewsets/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.12.1"
+__version__ = "0.13.1"
 
 from .error_namespace import ERROR_NAMESPACE, ERROR_NAMESPACE_PYDANTIC
 

{dynamicforms_fastapi_viewsets-0.12.1 → dynamicforms_fastapi_viewsets-0.13.1}/fastapi_viewsets/decorators/route_viewset.py

@@ -216,12 +216,14 @@ def route_viewset(
             on a shared mixin cannot know which viewset it will end up on. Here it can: parameters
             no allowed shape uses are dropped so they never reach the schema, the `X-List-Shape`
             header is kept only when there is a choice to make, and the return annotation becomes
-            the union of exactly the models this viewset can produce.
+            the union of exactly the models this viewset can produce. A declared `default_sort` becomes
+            the `sort` parameter's default.
             """
             from fastapi_viewsets.list_shapes import response_model, shape_examples, SHAPE_HEADER
-            from fastapi_viewsets.mixins import T as ItemVar
+            from fastapi_viewsets.mixins import check_declared_sort, T as ItemVar
 
             default, allowed = cls.resolve_shapes()
+            item_type = type_map.get(ItemVar, ItemVar)
             uses = {
                 "offset": "paginated" in allowed,
                 "cursor": "cursor" in allowed,
@@ -243,9 +245,11 @@ def route_viewset(
                             ),
                         ]
                     )
+                if name == "sort" and cls.default_sort is not None:
+                    check_declared_sort(cls.default_sort, item_type)
+                    parameter = parameter.replace(default=cls.default_sort)
                 params.append(parameter)
 
-            item_type = type_map.get(ItemVar, ItemVar)
             nonlocal shape_openapi_extra
             shape_openapi_extra = shape_examples(allowed, item_type)
             return sig.replace(parameters=params, return_annotation=response_model(allowed, item_type))

{dynamicforms_fastapi_viewsets-0.12.1 → dynamicforms_fastapi_viewsets-0.13.1}/fastapi_viewsets/events/redis.py

@@ -102,16 +102,15 @@ class PerLoopRedis:
         return client
 
     async def _close_with_loop(self, loop: asyncio.AbstractEventLoop, client: "Redis") -> None:
+        # A task destroyed with its closed loop is finalised by the garbage collector, which can run
+        # inside `client()` while it holds `_lock`: taking the lock there deadlocks, so that loop's
+        # client is left to the next `client()` call.
         try:
             await loop.create_future()
         except asyncio.CancelledError:
             self._forget(loop, client)
             await client.aclose()
             raise
-        except GeneratorExit:
-            # The task is destroyed with its loop: there is no loop to close the client on.
-            self._forget(loop, client)
-            raise
 
     def _forget(self, loop: asyncio.AbstractEventLoop, client: "Redis") -> None:
         with self._lock:

{dynamicforms_fastapi_viewsets-0.12.1 → dynamicforms_fastapi_viewsets-0.13.1}/fastapi_viewsets/mixins.py

@@ -201,6 +201,15 @@ class SortStateColumn(BaseModel):
 SortState = list[SortStateColumn]
 
 
+SORT_DESCRIPTION = (
+    "Ordering: comma-separated `column:direction` entries in priority order (`name:asc,score:desc`)."
+    " The direction is `asc` or `desc`, `asc` when omitted; an entry with any other direction is"
+    " ignored. Without the parameter the list is ordered by its default value, where the endpoint"
+    " declares one; an empty value leaves the list unordered."
+)
+"""The `sort` parameter's description on every list endpoint."""
+
+
 def parse_sort_param(sort_csv: str | None) -> SortState:
     """
     Parse the 'sort' query parameter (comma-separated) into a SortState.
@@ -227,6 +236,31 @@ def parse_sort_param(sort_csv: str | None) -> SortState:
     return result
 
 
+def check_declared_sort(sort_csv: str, model: Any = None) -> SortState:
+    """
+    Parses a sort a viewset declares (`ListMixin.default_sort`) in the `sort` parameter's syntax.
+
+    Raises ValueError for an empty entry and an unrecognised direction, which `parse_sort_param`
+    skips in a request, and, when `model` is a pydantic model, for a column that is neither one of
+    its fields nor one of its computed fields.
+    """
+    entries = [entry.strip() for entry in sort_csv.split(",")]
+    if not all(entries):
+        raise ValueError(f"default_sort {sort_csv!r} has an empty entry")
+    result: SortState = []
+    for entry in entries:
+        column, _, raw_direction = entry.rpartition(":")
+        if not column:
+            column, raw_direction = entry, SortDirection.asc.value
+        if raw_direction not in SortDirection.__members__:
+            raise ValueError(f"default_sort {sort_csv!r}: direction of {column!r} is not 'asc' or 'desc'")
+        fields = getattr(model, "model_fields", None)
+        if isinstance(fields, dict) and column not in fields and column not in model.model_computed_fields:
+            raise ValueError(f"default_sort {sort_csv!r}: {model.__name__} has no field {column!r}")
+        result.append(SortStateColumn(column_name=column, direction=SortDirection(raw_direction)))
+    return result
+
+
 ###################################################################################################
 # LIST
 ###################################################################################################
@@ -284,6 +318,17 @@ class ListMixin(Generic[T, TFilter], ABC):
     what stops a cursor walking straight past the NULL rows.
     """
 
+    default_sort: str | None = None
+    """
+    The ordering of a list request that sends no `sort` parameter, in that parameter's syntax:
+    `"name:asc"`, `"category:asc,score:desc"`. None leaves such a request unordered; so does an empty
+    `sort=` on a viewset that declares one.
+
+    `route_viewset` publishes it as the `sort` parameter's default in the schema, where the TS
+    client's `defaultSort()` reads it, and raises ValueError for an empty entry, an unrecognised
+    direction or a column the response model has neither a field nor a computed field for.
+    """
+
     @property
     def nulls_first(self) -> bool:
         return self.nulls != "last"
@@ -298,7 +343,7 @@ class ListMixin(Generic[T, TFilter], ABC):
         self: "ImplMixin[Any, T] | ListMixin[T]",
         context: Context,
         fltr: Annotated[TFilter, Query()] = None,
-        sort: str | None = None,
+        sort: Annotated[str | None, Query(description=SORT_DESCRIPTION)] = None,
         offset: Annotated[int, Query(ge=0)] = 0,
         limit: Annotated[int | None, Query(ge=1)] = None,
         cursor: str | None = None,
@@ -320,7 +365,7 @@ class ListMixin(Generic[T, TFilter], ABC):
 
         query = build_list_query(
             fltr,
-            sort,
+            self.default_sort if sort is None else sort,
             offset=offset,
             limit=(
                 None
@@ -775,73 +820,122 @@ class LookupFilter(BaseModel):
 
 
 TLookupFilter = TypeVar("TLookupFilter", default=LookupFilter)
+TLookupItem = TypeVar("TLookupItem", default=LookupItem)
 
 
-class LookupMixin(Generic[TLookupFilter], ABC):
+class LookupMixin(Generic[TLookupFilter, TLookupItem], ABC):
     """
     Lookup endpoint with optional search filtering.
 
-    Adds a GET /lookup endpoint that returns a list of LookupItem objects — useful for populating
-    select/autocomplete widgets.
+    Adds a GET /lookup endpoint that returns a list of TLookupItem objects (default: LookupItem) -
+    useful for populating select/autocomplete widgets.
+
+    The fields of TLookupFilter (default: LookupFilter, a single `q`) are the endpoint's query
+    parameters. The request runs through the same stages as a list:
 
-    The mixin is generic over TLookupFilter (default: LookupFilter). When no type argument is
-    given, the endpoint exposes a single 'q' query parameter and filter_lookup filters by
-    case-insensitive title match. Supply a custom filter model as a type argument to add extra
-    query parameters and override filter_lookup.
+    1. `perform_lookup(context)` returns the source, lazily or not.
+    2. `apply_lookup_filter(context, query, records)` narrows it. Override it to filter in the
+       backend and mark the stage applied (`query.mark_applied("filter")`); the default filters in
+       memory: by the declaration of a filter model built with `make_filter_model`, otherwise
+       through `filter_lookup`.
+    3. `to_lookup_item(raw)` converts each remaining row to TLookupItem.
 
-    When the filter is active (any field is non-None), the following two-phase pipeline runs:
+    The filter travels in `query.fltr`, never on the viewset instance, which serves concurrent
+    requests under the default `singleton` lifecycle.
 
-    1. Pre-filter: setup_lookup_filter is called before perform_lookup.
-       Override to apply server-side filtering (e.g., narrow a DB query).
-    2. Post-filter: filter_lookup is called after perform_lookup.
-       The default implementation filters by fltr.q (case-insensitive title match).
-       Override to customise in-memory filtering.
+    The endpoint answers in the order of the source; filtering and conversion keep it. The source
+    orders the items by group, then by their text, in its own collation - `order_by` in the
+    database - because a select shows each group's items together and only the source knows which
+    field the text comes from and how its language orders it.
     """
 
     __router = APIRouter()
 
     @abstractmethod
-    async def perform_lookup(self, context: Context) -> list[LookupItem]:
+    async def perform_lookup(self, context: Context) -> ListRecords:
         """
-        Subclasses should implement this method to return lookup items.
-        This method is intentionally NOT in ImplMixin because it's expected to be a simple
-        transformation of perform_list.
+        Subclasses implement this to return the lookup source, in the order the endpoint answers
+        in: by group, then by text.
+
+        A lazy source - a generator, an unevaluated QuerySet - is what an overridden
+        `apply_lookup_filter` pushes the filter into. Rows are TLookupItem once `to_lookup_item` has
+        run over them.
         """
         raise NotImplementedError("Method 'perform_lookup' must be implemented.")
 
-    async def setup_lookup_filter(self, fltr: TLookupFilter) -> None:
+    async def get_lookup(self, context: Context, query: ListQuery) -> list[TLookupItem]:
+        """The lookup pipeline: source, filter, conversion. Overridable as a whole."""
+        records = await self.perform_lookup(context)
+        records = await self.apply_lookup_filter(context, query, records)
+        return await self.land_lookup(query, records)
+
+    async def apply_lookup_filter(
+        self,
+        context: Context,  # noqa: ARG002 - part of the hook signature, for overrides to use
+        query: ListQuery,
+        records: ListRecords,
+    ) -> ListRecords:
         """
-        Optional pre-filter hook called before perform_lookup when the filter is active.
-        Subclasses can override to set up server-side filtering (e.g., build a DB query).
+        Narrows `records` to those the filter accepts. Override to filter in the backend; mark the
+        stage applied so this default does not redo the work:
+
+            async def apply_lookup_filter(self, context, query, records):
+                if query.has_filter:
+                    records = records.filter(pk__in=query.fltr.ids)
+                    query.mark_applied("filter")
+                return await super().apply_lookup_filter(context, query, records)
+
+        The default filters TLookupItem records in memory: by the declaration of a filter model built
+        with `make_filter_model`, otherwise through the `filter_lookup` hook.
         """
+        if not query.has_filter or not query.needs("filter"):
+            return records
 
-    async def filter_lookup(self, fltr: TLookupFilter, items: list[LookupItem]) -> list[LookupItem]:
+        items = await self.land_lookup(query, records)
+        declared = filters_from(query.fltr)
+        if declared is not None:
+            return declared.apply(items)
+        filtered = await self.filter_lookup(query.fltr, items)
+        return items if filtered is None else filtered
+
+    async def filter_lookup(self, fltr: TLookupFilter, items: list[TLookupItem]) -> list[TLookupItem]:
         """
-        Post-filter hook called after perform_lookup when the filter is active.
-        Default implementation filters by fltr.q (case-insensitive substring of title).
-        Subclasses can override to change the filtering behaviour.
+        In-memory filter hook of a hand-written filter model, called with the converted items.
+        The default filters by `fltr.q`: a case-insensitive substring of the item's `title`.
         """
         q = getattr(fltr, "q", None)
         if q is None:
             return items
-        return [item for item in items if q.lower() in item.title.lower()]
+        needle = q.lower()
+        return [item for item in items if needle in str(getattr(item, "title", "")).lower()]
+
+    def to_lookup_item(self, raw: Any) -> TLookupItem:
+        """
+        Converts one row of the source into TLookupItem. The default is identity, for a source that
+        already yields TLookupItem.
+        """
+        return raw
+
+    async def land_lookup(self, query: ListQuery, records: ListRecords) -> list[TLookupItem]:
+        """
+        Materialises the source and converts it with `to_lookup_item`. Idempotent: the conversion
+        runs once per request, whichever stage lands the source first.
+        """
+        materialized = await materialize(records)
+        if query.needs("conversion"):
+            query.mark_applied("conversion")
+            if type(self).to_lookup_item is not LookupMixin.to_lookup_item:
+                return [self.to_lookup_item(row) for row in materialized]
+        return materialized
 
     @final
     @__router.get("lookup")
     async def lookup(
-        self: "ImplMixin[Any, LookupItem] | LookupMixin",
+        self: "LookupMixin",
         context: Context,
         fltr: Annotated[TLookupFilter, Query()] = None,
-    ) -> list[LookupItem]:
-        has_filter = (
-            fltr is not None and hasattr(fltr, "model_dump") and any(v is not None for v in fltr.model_dump().values())
-        )
-        if has_filter:
-            await self.setup_lookup_filter(fltr)
-        res = await self.perform_lookup(context)
-        if has_filter:
-            res = await self.filter_lookup(fltr, res)
-        return res
+    ) -> list[TLookupItem]:
+        return await self.get_lookup(context, build_list_query(fltr, None))
 
 
 ###################################################################################################