dynamicforms-fastapi-viewsets 0.15.0__tar.gz → 0.15.2__tar.gz

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamicforms-fastapi-viewsets
-Version: 0.15.0
+Version: 0.15.2
 Summary: Django REST Framework-style viewsets for FastAPI, with optional Celery-backed async execution and a Vue/TypeScript client counterpart.
 Keywords: fastapi,viewsets,rest,dynamicforms,celery,django-rest-framework
 Author: Jure Erznožnik
@@ -130,8 +130,9 @@ list pipeline and pagination, the muxws transport, events, and the Vue client.
 ## Demo
 
 ```bash
-python demo.py                       # backend on :8000, frontend on :5173
-python demo.py --celery              # ... with every viewset call routed through a Celery worker
+uv sync && npm ci
+uv run python demo.py                # backend on :8000, frontend on :5173
+uv run python demo.py --celery       # ... with every viewset call routed through a Celery worker
 npm run test:e2e                     # drives the demo in a browser
 ```
 

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/README.md

@@ -91,8 +91,9 @@ list pipeline and pagination, the muxws transport, events, and the Vue client.
 ## Demo
 
 ```bash
-python demo.py                       # backend on :8000, frontend on :5173
-python demo.py --celery              # ... with every viewset call routed through a Celery worker
+uv sync && npm ci
+uv run python demo.py                # backend on :8000, frontend on :5173
+uv run python demo.py --celery       # ... with every viewset call routed through a Celery worker
 npm run test:e2e                     # drives the demo in a browser
 ```
 

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/conf.py

@@ -21,9 +21,16 @@ class Settings:
 
     def __init__(self):
         self.viewsets_context_processors: list[ContextProcessor] = []
+        """Builds each request's context, in order."""
         self.viewsets_context_json_encoder: type[json.JSONEncoder] | None = None
+        """Encodes context values that cross to a Celery worker; None is the standard encoder."""
         self.viewsets_context_json_decoder: type[json.JSONDecoder] | None = None
+        """Decodes context values on the Celery worker; None is the standard decoder."""
         self.viewsets_command_middleware: list[CommandMiddleware] = []
+        """
+        Wraps every request-facing execution. The list is read on every call; the `modifies_response_shape`
+        and `openapi_parameters` of its entries when a viewset is decorated.
+        """
         self.viewsets_idempotency_ttl: float = 86400
         """Seconds an `Idempotency` outcome is kept; a later repeat runs the action again."""
         self.viewsets_idempotency_lock_ttl: float = 600
@@ -32,7 +39,12 @@ class Settings:
         it); once expired, a repeat runs the action again.
         """
         self.viewsets_auth_processors: list[AuthBackend] = []
+        """
+        Tried in order by `auth_context_processor` to resolve `context.user`; the first backend that claims
+        the request decides.
+        """
         self.default_action_configuration: dict[Any, Any] = {}
+        """The configuration every action starts from."""
         self.default_list_shape: str = "plain"
         """List shape of a viewset that sets none: "plain", "paginated" or "cursor"."""
         self.viewsets_register_muxws: bool = True
@@ -43,7 +55,7 @@ class Settings:
         self.viewsets_security_scheme: SecurityBase | None = None
         """
         Security scheme added to every route for the OpenAPI "Authorize" flow only. Read at decoration
-        time, as is `viewsets_command_middleware`.
+        time.
         """
         self.viewsets_event_store: EventStore | None = None
         """

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/cursor.py

@@ -15,11 +15,12 @@ import json
 from dataclasses import dataclass
 from typing import Any, ClassVar, Generic, TYPE_CHECKING
 
-from pydantic import BaseModel, TypeAdapter
+from pydantic import BaseModel, ConfigDict, TypeAdapter
 from typing_extensions import TypeVar
 
 from .error_namespace import _namespaced
 from .filters import Filter
+from .list_query import _with_description
 
 if TYPE_CHECKING:
     from .mixins import SortState
@@ -157,14 +158,25 @@ class CursorPage(BaseModel, Generic[TItem]):
     are the same anchors read inclusively, present whenever the page is non-empty, for polling an edge.
     """
 
+    # A parametrised model (`CursorPage[Track]`) has no docstring of its own; a subclass keeps its own.
+    model_config = ConfigDict(use_attribute_docstrings=True, json_schema_extra=_with_description(__doc__))
+
     results: list[TItem]
+    """The records of the page."""
     limit: int
+    """Page size the page was read with."""
     has_more: bool = False
+    """Whether records follow the page."""
     has_previous: bool = False
+    """Whether records precede the page."""
     next: str | None = None
+    """Cursor of the records after the page; null when there are none."""
     previous: str | None = None
+    """Cursor of the records before the page; null when there are none."""
     first: str | None = None
+    """Cursor of the page's first record onwards (that record included); null for an empty page."""
     last: str | None = None
+    """Cursor of the page's last record backwards (that record included); null for an empty page."""
 
 
 @dataclass(frozen=True)

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/decorators/build_schema.py

@@ -7,8 +7,9 @@ from fastapi import APIRouter, FastAPI
 from fastapi.routing import APIRoute
 from starlette.responses import Response
 
-from ..endpoint_docs import docs_for, viewset_tags
+from ..endpoint_docs import operation_docs_for, viewset_tags
 from ..middleware import unwrap_viewset_result_type
+from ..routing import SCHEMA_ENDPOINT_DOCS
 
 
 def _generic_args(annotation) -> tuple:
@@ -144,7 +145,7 @@ def build_schema(cls, base_path: str = "", default_tags=None, get_wrapper=None,
             endpoint=schema,
             tags=default_tags,
             methods=["GET"],
-            description="Returns OpenAPI schema for the ViewSet",
+            **SCHEMA_ENDPOINT_DOCS,
         )
         class_router.add_api_route(**schema_route_kwargs)
 
@@ -179,7 +180,7 @@ def build_schema(cls, base_path: str = "", default_tags=None, get_wrapper=None,
                         route.endpoint.__name__,
                         getattr(endpoint_wrapper, "__shape_openapi_extra__", None) or route.openapi_extra,
                     ),
-                    **docs_for(cls, route.endpoint.__name__),
+                    **operation_docs_for(cls, route.endpoint.__name__),
                 )
             )
 

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/decorators/celery_viewset/transport.py

@@ -328,6 +328,7 @@ def encode_value(hint: Any, value: Any, what: str = "the value") -> tuple[Any, b
 
 
 def decode_value(adapter: TypeAdapter | None, data: Any, typed: bool) -> Any:
+    """`data` validated by `adapter` when `typed`, else rebuilt with `from_jsonable`; inverse of `encode_value`."""
     if typed and adapter is not None:
         return _decode_typed(adapter, data)
     return from_jsonable(data)
@@ -354,6 +355,8 @@ def is_model_hint(hint: Any) -> bool:
 
 @dataclass(frozen=True)
 class ParamCodec:
+    """How one parameter of an action is encoded for the worker."""
+
     name: str
     hint: Any
     kind: str
@@ -424,6 +427,7 @@ class ActionCodec:
             raise TypeError(f"{self.task_name}: {error}") from error
 
     def decode_argument(self, name: str, data: Any, typed: bool) -> Any:
+        """The value of parameter `name` from its encoded form; inverse of `encode_argument`."""
         codec = self.params.get(name)
         return decode_value(adapter_for(codec.hint) if codec is not None else None, data, typed)
 
@@ -435,6 +439,7 @@ class ActionCodec:
             raise TypeError(f"{self.task_name}: {error}") from error
 
     def decode_result(self, result: EncodedResult) -> Any:
+        """The result from its `EncodedResult`; inverse of `encode_result`."""
         return _decode_result(result.data, result.encoding, self.result_hint)
 
 

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/decorators/route_viewset.py

@@ -1,3 +1,4 @@
+import copy
 import inspect
 import re
 
@@ -5,8 +6,8 @@ from dataclasses import dataclass
 from functools import wraps
 from typing import Annotated, get_args, get_origin, Literal, TypeVar
 
-from fastapi import APIRouter, Depends, Header, Request, Response
-from fastapi.params import FieldInfo
+from fastapi import APIRouter, Depends, Header, Path, Request, Response
+from fastapi.params import FieldInfo, Header as HeaderParam, Param
 from pydantic import BaseModel
 
 try:
@@ -20,13 +21,22 @@ from fastapi_viewsets.context import build_context, Context, get_shared_context
 from fastapi_viewsets.endpoint_docs import (
     DOCS_ATTRIBUTE,
     docs_for,
+    operation_docs_for,
     register_tag,
     viewset_description,
 )
-from fastapi_viewsets.middleware import any_modifies_response_shape, Middleware, unwrap_viewset_result_type
-from fastapi_viewsets.mixins import FilterParam
+from fastapi_viewsets.middleware import (
+    any_modifies_response_shape,
+    Middleware,
+    middleware_openapi_parameters,
+    unwrap_viewset_result_type,
+)
+from fastapi_viewsets.mixins import (
+    FilterParam,
+    T as ITEM_TYPE_VAR,  # noqa: N811
+)
 from fastapi_viewsets.mux_ws import register_viewset, resolve_register_muxws, resolve_register_rest
-from fastapi_viewsets.response_classes import with_error_responses
+from fastapi_viewsets.response_classes import CURSOR_ERROR_RESPONSES, with_error_responses
 from fastapi_viewsets.routing import MUXWS, openapi_endpoint, REST, transport_route_class
 
 from .build_schema import _pydantic_generic_args, build_schema, route_to_add_api_route_kwargs
@@ -116,7 +126,8 @@ def resolve_typevars(type_map, annotation):
 def _make_middleware_depends(cls: type, action_name: str):
     """
     A per-route FastAPI dependency running `Middleware.depends()` before the body is parsed.
-    `@action_configuration` and settings are resolved per request.
+    `@action_configuration`, the context processors and the command middleware are resolved per request,
+    `viewsets_security_scheme` when the route is built.
     """
 
     async def _run(request: Request) -> None:
@@ -172,6 +183,48 @@ def _with_security_scheme(run):
     return dependency
 
 
+PK_DESCRIPTION = "Primary key of the record."
+"""The `pk` path parameter's description when the model's primary key field has none."""
+
+
+def _pk_description(model, pk_field_name: str | None) -> str:
+    """The description of the `pk` path parameter: that of the model's primary key field, else `PK_DESCRIPTION`."""
+    fields = getattr(model, "model_fields", None) or {}
+    field = fields.get(pk_field_name) if pk_field_name else None
+    return field.description if field is not None and field.description else PK_DESCRIPTION
+
+
+def _published_name(name: str, annotation) -> str | None:
+    """The schema name of a path, query, header or cookie parameter; None for any other parameter."""
+    for metadata in getattr(annotation, "__metadata__", ()):
+        if isinstance(metadata, Param):
+            if metadata.alias:
+                return metadata.alias
+            if isinstance(metadata, HeaderParam) and metadata.convert_underscores:
+                return name.replace("_", "-")
+            return name
+    return None
+
+
+def _with_description(annotation, description: str):
+    """`annotation` (`Annotated[X, Param]`) with the parameter's description replaced."""
+    metadata = []
+    for item in annotation.__metadata__:
+        if isinstance(item, Param):
+            item = copy.copy(item)
+            item.description = description
+            item._attributes_set = {**getattr(item, "_attributes_set", {}), "description": description}
+        metadata.append(item)
+    return Annotated[(annotation.__origin__, *metadata)]
+
+
+def _is_absent_model_param(annotation) -> bool:
+    """Whether `annotation` is `Annotated[None, Query()]`: a filter parameter of a viewset declaring no filter."""
+    args = getattr(annotation, "__args__", None)
+    metadata = getattr(annotation, "__metadata__", None)
+    return bool(args and metadata) and args[0] in (None, type(None)) and any(isinstance(m, FieldInfo) for m in metadata)
+
+
 def route_viewset(
     router: APIRouter,
     base_path: str,
@@ -276,6 +329,14 @@ def _route(
                         ),
                     ]
                 )
+            if name == "limit":
+                parameter = parameter.replace(
+                    annotation=_with_description(
+                        parameter.annotation,
+                        f"Page size. Omit for {cls.default_page_size}; a larger value than {cls.max_page_size}"
+                        f" returns {cls.max_page_size}.",
+                    )
+                )
             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)
@@ -286,6 +347,26 @@ def _route(
         return sig.replace(parameters=params, return_annotation=response_model(allowed, item_type))
 
     shape_openapi_extra = None
+    item_model = type_map.get(ITEM_TYPE_VAR)
+
+    def _describe_parameters(params: list[inspect.Parameter], descriptions: dict[str, str]) -> None:
+        """Replaces the descriptions of `params` named in `descriptions` (`@endpoint_docs` `parameters`)."""
+        if not descriptions:
+            return
+        published = {}
+        for index, parameter in enumerate(params):
+            name = _published_name(parameter.name, parameter.annotation)
+            if name is not None:
+                published[name] = index
+        unknown = set(descriptions) - set(published)
+        if unknown:
+            raise ValueError(
+                f"@endpoint_docs on {cls.__name__} describes parameter(s) its endpoint does not have: "
+                f"{', '.join(sorted(unknown))}; it has {', '.join(sorted(published)) or 'none'}"
+            )
+        for name, description in descriptions.items():
+            index = published[name]
+            params[index] = params[index].replace(annotation=_with_description(params[index].annotation, description))
 
     def get_wrapper(original_endpoint, route_path, route_methods):
         nonlocal shape_openapi_extra
@@ -303,6 +384,10 @@ def _route(
                 continue
 
             annotation = resolve_typevars(type_map, p.annotation)
+            if _is_absent_model_param(annotation):
+                continue
+            if name == "pk" and "{pk}" in route_path and _published_name(name, annotation) is None:
+                annotation = Annotated[annotation, Path(description=_pk_description(item_model, pk_field_name))]
             new_p = p.replace(annotation=annotation)
 
             # `context` (detected by name) never reaches FastAPI; lifecycle_runner builds and injects it.
@@ -335,6 +420,8 @@ def _route(
 
             new_params.append(new_p)
 
+        _describe_parameters(new_params, docs_for(cls, original_endpoint.__name__).get("parameters", {}))
+
         # Reserved: FastAPI injects the real Response, onto which lifecycle_runner applies headers/cookies.
         new_params.append(inspect.Parameter("response", inspect.Parameter.KEYWORD_ONLY, annotation=Response))
 
@@ -443,6 +530,7 @@ def _route(
             ),
         )
 
+    middleware_parameters = middleware_openapi_parameters(settings.viewsets_command_middleware)
     rest_routes = []
     muxws_routes = []
     documented = set()
@@ -457,11 +545,20 @@ def _route(
             *gates,
             Depends(_make_middleware_depends(cls, action_name)),
         ]
+        responses = route.responses
+        if getattr(route.endpoint, "__list_shape_aware__", False) and "cursor" not in cls.resolve_shapes()[1]:
+            responses = {
+                status: entry for status, entry in responses.items() if CURSOR_ERROR_RESPONSES.get(status) is not entry
+            }
         route_kwargs = route_to_add_api_route_kwargs(
-            route, dependencies=dependencies, responses=with_error_responses(route.responses)
+            route, dependencies=dependencies, responses=with_error_responses(responses)
         )
         # Per-viewset wording from @endpoint_docs.
-        route_kwargs.update(docs_for(cls, action_name))
+        route_kwargs.update(operation_docs_for(cls, action_name))
+        if middleware_parameters and not is_schema_route(route):
+            extra = dict(route_kwargs.get("openapi_extra") or {})
+            extra["parameters"] = [*extra.get("parameters", []), *middleware_parameters]
+            route_kwargs["openapi_extra"] = extra
         if parent is not None and not route_kwargs.get("summary"):
             # Prefix the mount, telling a sub-viewset's `List Items` apart from the parent's in its group.
             default_summary = (route_kwargs.get("name") or action_name).replace("_", " ").title()

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/endpoint_docs.py

@@ -19,6 +19,8 @@ class EndpointDoc(TypedDict, total=False):
     response_description: str
     deprecated: bool
     tags: list[str]
+    parameters: dict[str, str]
+    """Descriptions of the endpoint's path, query and header parameters, by their name in the schema."""
 
 
 def endpoint_docs(docs: dict[str, EndpointDoc]):
@@ -40,15 +42,26 @@ def endpoint_docs(docs: dict[str, EndpointDoc]):
 
 
 def docs_for(cls: type, action: str) -> dict[str, Any]:
-    """The documentation of one action, merged along the MRO (subclass entries override)."""
+    """
+    The documentation of one action, merged along the MRO (subclass entries override; `parameters` merges
+    per parameter).
+    """
     merged: dict[str, Any] = {}
     for base in reversed(cls.__mro__):
         entry = base.__dict__.get(DOCS_ATTRIBUTE, {}).get(action)
         if entry:
+            parameters = {**merged.get("parameters", {}), **entry.get("parameters", {})}
             merged.update(entry)
+            if parameters:
+                merged["parameters"] = parameters
     return merged
 
 
+def operation_docs_for(cls: type, action: str) -> dict[str, Any]:
+    """`docs_for` without `parameters`: the keyword arguments of `add_api_route`."""
+    return {key: value for key, value in docs_for(cls, action).items() if key != "parameters"}
+
+
 # ---------------------------------------------------------------------------
 # Viewset-level description
 # ---------------------------------------------------------------------------

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/events/changes.py

@@ -10,7 +10,7 @@ import logging
 from collections.abc import Awaitable, Callable, Mapping
 from typing import Any, Literal, TYPE_CHECKING
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 
 from ..action_configuration import resolve_action_configuration
 from ..context import _Deferred, Context
@@ -48,7 +48,10 @@ _OPTIONS = frozenset({"topic"})
 class Change(BaseModel):
     """One record an action touched, by its pk; a frontend reads the record through the viewset's retrieve."""
 
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
     pk: Any
+    """Primary key of the record."""
 
 
 class RecordsChanged(Event):
@@ -56,8 +59,12 @@ class RecordsChanged(Event):
 
     event_name = "records_changed"
 
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
     op: Literal["created", "updated", "deleted"]
+    """What the action did to the records."""
     changes: list[Change]
+    """The records the action touched."""
 
 
 def routed_base_path(request: "Request") -> str | None:

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/events/viewset.py

@@ -9,6 +9,7 @@ from typing import Any
 from fastapi import APIRouter, Request
 from pydantic import (
     BaseModel,
+    ConfigDict,
     Field,
     GetJsonSchemaHandler,
     model_serializer,
@@ -25,6 +26,7 @@ from ..decorators.route_viewset import route_viewset
 from ..error_responses import ApiErrorBody, error_body
 from ..exceptions import EventCursorsExceededError, EventTopicInvalidError
 from ..mux_ws.transports import transports
+from ..response_classes import POLL_ERROR_RESPONSES, SUBSCRIBE_ERROR_RESPONSES
 from ..routing import PEER_SCOPE_KEY
 from . import delivery
 from .authorizers import authorize_topic
@@ -44,16 +46,21 @@ def _leave_out_none(data: Any, names: tuple[str, ...]) -> Any:
 class TopicRequest(BaseModel):
     """The body of `subscribe` and `unsubscribe`."""
 
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
     topic: str
+    """The topic: a viewset's routed base path or a declared source's `name[:key]`."""
 
 
 class SubscribeAnswer(BaseModel):
-    """The answer of `subscribe`. `scope` is left out of the serialized answer when it is None."""
+    """The answer of `subscribe`. `scope` is absent for an unscoped topic."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
 
     rev: int
     """The topic's current rev, 0 for a topic without events."""
     scope: str | None = None
-    """The scope key of a scoped viewset topic; None for an unscoped topic."""
+    """The scope key of a scoped viewset topic; absent for an unscoped topic."""
 
     @model_serializer(mode="wrap")
     def _leave_out_no_scope(self, handler: SerializerFunctionWrapHandler, _info: SerializationInfo) -> Any:
@@ -66,40 +73,52 @@ class SubscribeAnswer(BaseModel):
 
 
 class PollRequest(BaseModel):
-    """The body of `poll`: each topic mapped to the rev the caller holds, or None to start from now."""
+    """The body of `poll`: each topic mapped to the rev the caller holds, or null to start from now."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
 
     cursors: dict[str, int | None]
+    """The rev the caller holds per topic; null to start from the topic's current rev."""
     scopes: dict[str, str] | None = None
     """The scope key the caller holds per topic; a cursor whose scope key differs from the server's answers
-    `events: null`. None trusts every cursor."""
+    `events: null`. Absent or null trusts every cursor."""
 
 
 class PolledEvent(BaseModel):
     """One event of a poll answer."""
 
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
     rev: int
+    """The event's rev in its topic."""
     prev: int
     """The rev of the event before it in the answer; for the first event, the cursor."""
     event: str
     """The event's `event_name`."""
     version: int = Field(ge=1, description="The event's `event_version`: the version of the payload's shape.")
     payload: Any = None
+    """The event's fields."""
 
 
 class TopicAnswer(BaseModel):
     """
-    The answer of `poll` for one topic. `events` is None when the log cannot answer the cursor; the
-    caller then re-reads its state. A refused or invalid topic has `rev` and `events` None and `error`
-    and `status` set. `error`, `status` and `scope` are left out when None.
+    The answer of `poll` for one topic. `events` is null when the log cannot answer the cursor; the
+    caller then re-reads its state. A refused or invalid topic has `rev` and `events` null and `error`
+    and `status` set. `error`, `status` and `scope` are absent when they have no value.
     """
 
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
     rev: int | None
+    """The topic's current rev; null for a refused or invalid topic."""
     events: list[PolledEvent] | None
+    """The events after the cursor, oldest first; null when the log cannot answer the cursor or the topic is refused."""
     error: ApiErrorBody | None = None
+    """Why the topic is refused or invalid."""
     status: int | None = None
     """The HTTP status of the refusal; set on every answer with `error`."""
     scope: str | None = None
-    """The scope key of a scoped viewset topic; None for an unscoped topic."""
+    """The scope key of a scoped viewset topic; absent for an unscoped topic."""
 
     @model_serializer(mode="wrap")
     def _leave_out_absent(self, handler: SerializerFunctionWrapHandler, _info: SerializationInfo) -> Any:
@@ -114,6 +133,8 @@ class TopicAnswer(BaseModel):
 class PollAnswer(BaseModel):
     """The answer of `poll`."""
 
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
     topics: dict[str, TopicAnswer]
     """One answer per cursor of the request, in the request's order."""
     poll_after_ms: int
@@ -148,7 +169,7 @@ class EventsViewSet:
     __router = APIRouter()
 
     @transports(rest=False, muxws=True)
-    @__router.post("/subscribe")
+    @__router.post("/subscribe", responses=SUBSCRIBE_ERROR_RESPONSES)
     async def subscribe(self, request: Request, context: Context, body: TopicRequest) -> SubscribeAnswer:
         """
         Subscribes the socket to `topic` until it closes or unsubscribes, and answers the topic's current
@@ -156,7 +177,7 @@ class EventsViewSet:
 
         Errors: 422 `fastapi-viewsets.event_topic_invalid` (malformed topic); 403
         `fastapi-viewsets.event_topic_refused` or the authorizer's `HTTPException`; 403
-        `fastapi-viewsets.event_scope_missing` (scope resolver answers None); 409
+        `fastapi-viewsets.event_scope_missing` (the topic has no scope key for the caller); 409
         `fastapi-viewsets.event_subscriptions_exceeded` (`settings.viewsets_event_max_subscriptions`
         reached). A 4xx refusal other than 429 also drops an existing subscription to the topic.
         """
@@ -185,10 +206,12 @@ class EventsViewSet:
         await delivery.unsubscribe(_peer_of(request, "unsubscribe"), body.topic)
 
     @transports(rest=True, muxws=True)
-    @__router.post("/poll")
+    @__router.post(
+        "/poll", responses=POLL_ERROR_RESPONSES, response_description="The answer of each topic of the body."
+    )
     async def poll(self, request: Request, context: Context, body: PollRequest) -> PollAnswer:
         """
-        Answers every cursor: a None cursor gets the current rev and no events, any other the events
+        Answers every cursor: a null cursor gets the current rev and no events, any other the events
         since it, or `events: null` when the log cannot answer it (or its `scopes` entry differs from
         the server's scope key). Events refused by a delivery filter are left out; `prev` chains the
         events returned and `rev` covers all of them.

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/filters/declaration.py

@@ -22,6 +22,30 @@ _LIST_LOOKUPS = frozenset({"in", "overlaps"})
 
 _LIST_DESCRIPTION = "One or more values; the parameter repeats for each (`?{parameter}=a&{parameter}=b`)."
 
+_OPERATOR_DESCRIPTIONS = {
+    "exact": "Records whose `{field}` equals the value.",
+    "iexact": "Records whose `{field}` equals the value, case-insensitive.",
+    "contains": "Records whose `{field}` contains the value.",
+    "icontains": "Records whose `{field}` contains the value, case-insensitive.",
+    "startswith": "Records whose `{field}` starts with the value.",
+    "gt": "Records whose `{field}` is greater than the value.",
+    "gte": "Records whose `{field}` is greater than or equal to the value.",
+    "lt": "Records whose `{field}` is less than the value.",
+    "lte": "Records whose `{field}` is less than or equal to the value.",
+    "in": "Records whose `{field}` is one of the values.",
+    "isnull": "`true`: records whose `{field}` is null; `false`: records whose `{field}` is set.",
+    "overlaps": "Records whose `{field}` shares at least one member with the values.",
+}
+"""The description of a filter query parameter by operator; another operator gets a generic one."""
+
+
+def _parameter_description(field_name: str, lookup: str, parameter: str) -> str:
+    text = _OPERATOR_DESCRIPTIONS.get(lookup, "Records `{field}` matches with the `" + lookup + "` operator.")
+    text = text.format(field=field_name)
+    if lookup in _LIST_LOOKUPS:
+        text += " " + _LIST_DESCRIPTION.format(parameter=parameter)
+    return text + " Omit to not filter."
+
 
 def _optional(annotation: Any) -> Any:
     if get_origin(annotation) is Union and type(None) in get_args(annotation):
@@ -69,12 +93,10 @@ def make_filter_model(model: type[BaseModel], declaration: FilterDeclaration) ->
                 )
             parameter = field_name if lookup == "exact" else f"{field_name}__{lookup}"
             annotation = _parameter_annotation(field_annotation, lookup)
-            default = (
-                Field(None, description=_LIST_DESCRIPTION.format(parameter=parameter))
-                if lookup in _LIST_LOOKUPS
-                else None
+            fields[parameter] = (
+                annotation,
+                Field(None, description=_parameter_description(field_name, lookup, parameter)),
             )
-            fields[parameter] = (annotation, default)
             spec[parameter] = (field_name, lookup, _item_annotation(field_annotation, lookup))
 
     filter_model = create_model(f"{model.__name__}Filter", **fields)