PyPI - dynamicforms-fastapi-viewsets - Versions diffs - 0.13.0__tar.gz → 0.13.1__tar.gz - Mend

@@ -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
@@ -797,6 +842,11 @@ class LookupMixin(Generic[TLookupFilter, TLookupItem], ABC):
     The filter travels in `query.fltr`, never on the viewset instance, which serves concurrent
     requests under the default `singleton` lifecycle.
+    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()
@@ -804,7 +854,8 @@ class LookupMixin(Generic[TLookupFilter, TLookupItem], ABC):
     @abstractmethod
     async def perform_lookup(self, context: Context) -> ListRecords:
         """
-        Subclasses implement this to return the lookup source.
+        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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dynamicforms-fastapi-viewsets
-Version: 0.13.0
+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

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

@@ -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))

@@ -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.13.0__tar.gz → 0.13.1__tar.gz

dynamicforms-fastapi-viewsets 0.13.0tar.gz → 0.13.1tar.gz