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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamicforms-fastapi-viewsets
-Version: 0.15.1
+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.1 → 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.1 → 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.1 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/cursor.py

@@ -20,6 +20,7 @@ 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,7 +158,8 @@ class CursorPage(BaseModel, Generic[TItem]):
     are the same anchors read inclusively, present whenever the page is non-empty, for polling an edge.
     """
 
-    model_config = ConfigDict(use_attribute_docstrings=True)
+    # 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."""

{dynamicforms_fastapi_viewsets-0.15.1 → 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.1 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/decorators/route_viewset.py

@@ -25,13 +25,18 @@ from fastapi_viewsets.endpoint_docs import (
     register_tag,
     viewset_description,
 )
-from fastapi_viewsets.middleware import any_modifies_response_shape, Middleware, unwrap_viewset_result_type
+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
@@ -121,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:
@@ -524,6 +530,7 @@ def _route(
             ),
         )
 
+    middleware_parameters = middleware_openapi_parameters(settings.viewsets_command_middleware)
     rest_routes = []
     muxws_routes = []
     documented = set()
@@ -538,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(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.1 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/events/viewset.py

@@ -26,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
@@ -52,14 +53,14 @@ class TopicRequest(BaseModel):
 
 
 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:
@@ -72,7 +73,7 @@ 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)
 
@@ -80,7 +81,7 @@ class PollRequest(BaseModel):
     """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):
@@ -101,9 +102,9 @@ class PolledEvent(BaseModel):
 
 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)
@@ -117,7 +118,7 @@ class TopicAnswer(BaseModel):
     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:
@@ -168,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
@@ -176,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.
         """
@@ -205,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.1 → 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)

{dynamicforms_fastapi_viewsets-0.15.1 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/list_query.py

@@ -4,6 +4,8 @@ The list request (`ListQuery`) and answer types. `perform_list` returns `ListRec
 query down by overriding one of them. See docs/guide/list-pipeline.md.
 """
 
+import inspect
+
 from collections.abc import AsyncIterable, AsyncIterator, Iterable
 from dataclasses import dataclass, field
 from typing import Any, Generic, TypeVar
@@ -16,6 +18,17 @@ Not the mixins' TypeVar: Pydantic returns the bare class for `M[X]` when X is M'
 would strip the item type from `PaginatedList[T]`.
 """
 
+
+def _with_description(doc: str | None):
+    """A `json_schema_extra` that gives a schema without a description the cleaned `doc`."""
+    description = inspect.cleandoc(doc or "")
+
+    def extra(schema: dict[str, Any]) -> None:
+        schema.setdefault("description", description)
+
+    return extra
+
+
 ListRecords = Iterable[TItem] | AsyncIterable[TItem]
 """Any sync or async iterable flowing through the list pipeline; `to_record` converts its items."""
 
@@ -28,11 +41,17 @@ class ListQuery:
     """
 
     fltr: Any = None
+    """The filter model instance; None when the request filters nothing."""
     sort: list = field(default_factory=list)
+    """The requested order (`SortState`); empty for no order."""
     offset: int = 0
+    """Number of records to skip."""
     limit: int | None = None
+    """Page size; None for the plain shape, which is not paged."""
     applied: set[str] = field(default_factory=set)
+    """Stages a backend performed in its store: `filter`, `sort`, `pagination`, `conversion`."""
     cursor: str | None = None
+    """The cursor the request sent, for the cursor shape."""
     shape: str | None = None
     """The answer envelope; when unset, `get_list` uses the viewset's default shape."""
     extra_filters: list = field(default_factory=list)
@@ -40,10 +59,12 @@ class ListQuery:
 
     @property
     def has_filter(self) -> bool:
+        """Whether the request filters: a filter model or a pipeline filter."""
         return self.fltr is not None or bool(self.extra_filters)
 
     @property
     def has_sort(self) -> bool:
+        """Whether the request sets an order."""
         return bool(self.sort)
 
     @property
@@ -52,16 +73,24 @@ class ListQuery:
         return self.limit is not None
 
     def mark_applied(self, *stages: str) -> None:
+        """Records `stages` as performed, so their in-memory steps are skipped."""
         self.applied.update(stages)
 
     def needs(self, stage: str) -> bool:
+        """Whether the in-memory step of `stage` still has to run."""
         return stage not in self.applied
 
 
+_PAGINATED_LIST_DESCRIPTION = (
+    "One page of results; `count` is null when the source cannot be counted without draining it."
+)
+
+
 class PaginatedList(BaseModel, Generic[TItem]):
-    """One page of results; `count` is None when the source cannot be counted without draining it."""
+    """One page of results; `count` is null when the source cannot be counted without draining it."""
 
-    model_config = ConfigDict(use_attribute_docstrings=True)
+    # A parametrised model (`PaginatedList[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."""

{dynamicforms_fastapi_viewsets-0.15.1 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/list_shapes.py

@@ -54,6 +54,7 @@ class ListOf(RootModel[list[TItem]], Generic[TItem]):
     @classmethod
     def __get_pydantic_json_schema__(cls, core_schema, handler):
         schema = handler(core_schema)
+        schema.setdefault("description", "Every record of the list, as an array.")
         if "example" not in schema:
             item = cls.__pydantic_generic_metadata__.get("args", (None,))[0]
             if item is not None and hasattr(item, "model_json_schema"):

{dynamicforms_fastapi_viewsets-0.15.1 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/middleware/__init__.py

@@ -185,6 +185,13 @@ class Middleware(ABC):
     `route_viewset` reads it from `settings.viewsets_command_middleware` only, per class.
     """
 
+    openapi_parameters: tuple[dict[str, Any], ...] = ()
+    """
+    OpenAPI parameter objects of the request values this middleware reads itself, such as a header.
+    `route_viewset` adds them to every operation of a viewset it routes, reading them from
+    `settings.viewsets_command_middleware` at that time. A function middleware sets it as an attribute.
+    """
+
     def config_from(self, context: Context) -> Any:
         """This middleware's `@action_configuration` value for the current call, or None."""
         return context.configuration_for(type(self))
@@ -245,6 +252,19 @@ def any_modifies_response_shape(middlewares: list) -> bool:
     return any(getattr(middleware, "modifies_response_shape", False) for middleware in middlewares)
 
 
+def middleware_openapi_parameters(middlewares: list) -> list[dict[str, Any]]:
+    """The `openapi_parameters` of `middlewares` in order, each name and location once."""
+    seen: set[tuple[str, str]] = set()
+    parameters: list[dict[str, Any]] = []
+    for middleware in middlewares:
+        for parameter in getattr(middleware, "openapi_parameters", ()):
+            identity = (parameter["name"].lower(), parameter["in"])
+            if identity not in seen:
+                seen.add(identity)
+                parameters.append(parameter)
+    return parameters
+
+
 def unwrap_viewset_result_type(annotation: Any) -> Any:
     """`ViewSetResult[X]` to `X`, so it documents and validates like `-> X`; anything else unchanged."""
     if get_origin(annotation) is ViewSetResult:

{dynamicforms_fastapi_viewsets-0.15.1 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/middleware/idempotency.py

@@ -300,6 +300,22 @@ class Idempotency(Middleware):
     process. The storage and replay rules are on the Idempotency guide page.
     """
 
+    openapi_parameters = (
+        {
+            "name": IDEMPOTENCY_KEY_HEADER,
+            "in": "header",
+            "required": False,
+            "description": (
+                "Makes the call repeatable: a repeat with the same key answers the first call's outcome. A "
+                "Structured Field string (RFC 8941), the key in double quotes. An invalid value answers 400 "
+                "`fastapi-viewsets.idempotency_key_invalid`; a key recorded for a different request answers "
+                "422 `fastapi-viewsets.idempotency_key_reused`."
+            ),
+            "schema": {"type": "string"},
+            "example": '"8e03978e-40d5-43e8-bc93-6894a57f9324"',
+        },
+    )
+
     def __init__(self, redis_client: "Redis | None" = None, key_prefix: str = "idempotency:"):
         self.redis_client = redis_client
         self.key_prefix = key_prefix

{dynamicforms_fastapi_viewsets-0.15.1 → dynamicforms_fastapi_viewsets-0.15.2}/fastapi_viewsets/mixins.py

@@ -37,10 +37,18 @@ from fastapi_viewsets.list_query import (
     take_page,
 )
 from fastapi_viewsets.list_shapes import resolve_shapes
-from fastapi_viewsets.response_classes import NOT_FOUND_RESPONSE
+from fastapi_viewsets.response_classes import BULK_NOT_FOUND_RESPONSE, CURSOR_ERROR_RESPONSES, NOT_FOUND_RESPONSE
 
 T = TypeVar("T")
 K = TypeVar("K")
+
+
+def _body_description(description: str) -> dict:
+    """`openapi_extra` describing an endpoint's request body."""
+    return {"requestBody": {"description": description}}
+
+
+BULK_UPDATE_BODY = _body_description('An object mapping each primary key to its record: `{"<pk>": {...}, ...}`.')
 TFilter = TypeVar("TFilter", default=None)
 
 
@@ -134,8 +142,9 @@ class CreateMixin(Generic[K, T], ABC):
     __router = APIRouter()
 
     @final
-    @__router.post("")
+    @__router.post("", response_description="The created record.")
     async def create(self: "ImplMixin[K, T] | CreateMixin[K ,T]", context: Context, data: T) -> T:
+        """Create one record from the body. Answers the record as stored."""
         return await self.perform_create(context, data)
 
 
@@ -147,10 +156,15 @@ class BulkOnlyCreateMixin(Generic[K, T], ABC):
     __router = APIRouter()
 
     @final
-    @__router.post("bulk")
+    @__router.post(
+        "bulk", response_description="The created records.", openapi_extra=_body_description("The records to create.")
+    )
     async def bulk_create(
-        self: "ImplMixin[K, T] | BulkOnlyCreateMixin[K ,T]", context: Context, data: list[T]
+        self: "ImplMixin[K, T] | BulkOnlyCreateMixin[K ,T]",
+        context: Context,
+        data: list[T],
     ) -> list[T]:
+        """Create the records of the body, a list. Answers the records as stored."""
         return await self.perform_bulk_create(context, data)
 
 
@@ -321,7 +335,11 @@ class ListMixin(Generic[T, TFilter], ABC):
         return resolve_shapes(cls.list_shape, cls.list_shapes, settings.default_list_shape)
 
     @final
-    @__router.get("")
+    @__router.get(
+        "",
+        responses=CURSOR_ERROR_RESPONSES,
+        response_description="The records, in the list shape the request asked for.",
+    )
     async def list_items(
         self: "ImplMixin[Any, T] | ListMixin[T]",
         context: Context,
@@ -542,7 +560,7 @@ class ListMixin(Generic[T, TFilter], ABC):
     async def count_records(
         self: "ImplMixin[Any, T] | ListMixin[T]",
         context: Context,  # noqa: ARG002 - part of the hook signature, for overrides to use
-        query: ListQuery,  # noqa: ARG002 - part of the hook signature, for overrides to use
+        query: ListQuery,
         records: ListRecords,
     ) -> int | None:
         """
@@ -613,8 +631,9 @@ class RetrieveMixin(Generic[K, T], ABC):
     __router = APIRouter()
 
     @final
-    @__router.get("/{pk}", responses=NOT_FOUND_RESPONSE)
+    @__router.get("/{pk}", responses=NOT_FOUND_RESPONSE, response_description="The record.")
     async def retrieve(self: "ImplMixin[K, T] | RetrieveMixin[K, T]", context: Context, pk: K) -> T:
+        """Read one record. 404 `fastapi-viewsets.not_found` for a missing record."""
         return await self.perform_retrieve(context, pk)
 
 
@@ -629,13 +648,23 @@ class UpdateMixin(Generic[K, T], ABC):
     __router = APIRouter()
 
     @final
-    @__router.put("/{pk}", responses=NOT_FOUND_RESPONSE)
+    @__router.put("/{pk}", responses=NOT_FOUND_RESPONSE, response_description="The updated record.")
     async def update(self: "ImplMixin[K, T] | UpdateMixin[K, T]", context: Context, pk: K, data: T) -> T:
+        """
+        Replace every field of one record with the body. Answers the record as stored; 404
+        `fastapi-viewsets.not_found` for a missing record.
+        """
         return await self.perform_update(context, pk, data, partial=False)
 
     @final
-    @__router.patch("/{pk}", name="partial_update", responses=NOT_FOUND_RESPONSE)
+    @__router.patch(
+        "/{pk}", name="partial_update", responses=NOT_FOUND_RESPONSE, response_description="The updated record."
+    )
     async def partial_update(self: "ImplMixin[K, T] | UpdateMixin[K, T]", context: Context, pk: K, data: T) -> T:
+        """
+        Write the fields the body states to one record; the other fields keep their values. Answers the
+        record as stored; 404 `fastapi-viewsets.not_found` for a missing record.
+        """
         return await self.perform_update(context, pk, data, partial=True)
 
 
@@ -647,17 +676,40 @@ class BulkOnlyUpdateMixin(Generic[K, T], ABC):
     __router = APIRouter()
 
     @final
-    @__router.put("bulk")
+    @__router.put(
+        "bulk",
+        responses=BULK_NOT_FOUND_RESPONSE,
+        response_description="The updated records.",
+        openapi_extra=BULK_UPDATE_BODY,
+    )
     async def bulk_update(
-        self: "ImplMixin[K, T] | BulkOnlyUpdateMixin[K, T]", context: Context, records: dict[K, T]
+        self: "ImplMixin[K, T] | BulkOnlyUpdateMixin[K, T]",
+        context: Context,
+        records: dict[K, T],
     ) -> list[T]:
+        """
+        Replace every field of the records of the keys in the body. Answers the records as stored; 404
+        `fastapi-viewsets.not_found` when a key has no record.
+        """
         return await self.perform_bulk_update(context, records, partial=False)
 
     @final
-    @__router.patch("bulk", name="bulk_partial_update")
+    @__router.patch(
+        "bulk",
+        name="bulk_partial_update",
+        responses=BULK_NOT_FOUND_RESPONSE,
+        response_description="The updated records.",
+        openapi_extra=BULK_UPDATE_BODY,
+    )
     async def bulk_partial_update(
-        self: "ImplMixin[K, T] | BulkOnlyUpdateMixin[K, T]", context: Context, records: dict[K, T]
+        self: "ImplMixin[K, T] | BulkOnlyUpdateMixin[K, T]",
+        context: Context,
+        records: dict[K, T],
     ) -> list[T]:
+        """
+        Write the fields the body states to the records of its keys; the other fields keep their values.
+        Answers the records as stored; 404 `fastapi-viewsets.not_found` when a key has no record.
+        """
         return await self.perform_bulk_update(context, records, partial=True)
 
 
@@ -678,7 +730,7 @@ class DestroyMixin(Generic[K, T], ABC):
     __router = APIRouter()
 
     @final
-    @__router.delete("/{pk}", responses=NOT_FOUND_RESPONSE)
+    @__router.delete("/{pk}", responses=NOT_FOUND_RESPONSE, response_description="The primary key, mapped to null.")
     async def destroy(self: "ImplMixin[K, T] | DestroyMixin[K, T]", context: Context, pk: K) -> dict[K, None]:
         """Destroy one record. Answers `{pk: null}`; 404 `fastapi-viewsets.not_found` for a missing record."""
         return await self.perform_destroy(context, pk)
@@ -692,9 +744,15 @@ class BulkOnlyDestroyMixin(Generic[K, T], ABC):
     __router = APIRouter()
 
     @final
-    @__router.delete("bulk")
+    @__router.delete(
+        "bulk",
+        response_description="Each primary key, mapped to null when destroyed or to the error otherwise.",
+        openapi_extra=_body_description("The primary keys of the records to destroy."),
+    )
     async def bulk_destroy(
-        self: "ImplMixin[K, T] | BulkOnlyDestroyMixin[K, T]", context: Context, pk: list[K]
+        self: "ImplMixin[K, T] | BulkOnlyDestroyMixin[K, T]",
+        context: Context,
+        pk: list[K],
     ) -> dict[K, ApiErrorBody | None]:
         """
         Destroy the records of the keys in the body, each independently of the others. Answers 200 with an
@@ -716,8 +774,15 @@ class BulkDestroyMixin(DestroyMixin[K, T], BulkOnlyDestroyMixin[K, T]):
 class LookupItem(BaseModel):
     """One choice of a lookup."""
 
-    group: Any = Field(None, description="Group the choice is listed under; null for an ungrouped choice.")
-    pk: object = Field(description="Primary key of the record.")
+    group: Any = Field(
+        None,
+        description="Group the choice is listed under; null for an ungrouped choice.",
+        json_schema_extra={"anyOf": [{"type": "string"}, {"type": "integer"}, {"type": "null"}]},
+    )
+    pk: object = Field(
+        description="Primary key of the record.",
+        json_schema_extra={"anyOf": [{"type": "integer"}, {"type": "string"}]},
+    )
     title: str = Field(description="Text shown for the choice.")
     icon: str | None = Field(None, description="Icon shown with the choice; null for none.")
 
@@ -800,12 +865,13 @@ class LookupMixin(Generic[TLookupFilter, TLookupItem], ABC):
         return materialized
 
     @final
-    @__router.get("lookup")
+    @__router.get("lookup", response_description="The choices.")
     async def lookup(
         self: "LookupMixin",
         context: Context,
         fltr: Annotated[TLookupFilter, Query()] = None,
     ) -> list[TLookupItem]:
+        """Choices for a select or autocomplete input, filtered by the query parameters, in the source's order."""
         return await self.get_lookup(context, build_list_query(fltr, None))
 
 

dynamicforms_fastapi_viewsets-0.15.2/fastapi_viewsets/response_classes.py

@@ -0,0 +1,191 @@
+"""
+The OpenAPI `responses` entries of the error responses of a viewset's endpoints. Every entry
+documents the body as `ApiErrorBody` (`fastapi_viewsets.error_responses`).
+"""
+
+from typing import Any
+
+from .error_namespace import _namespaced
+from .error_responses import ApiErrorBody, VALIDATION_FAILED_DETAIL
+
+
+def _example(detail: str, code: str, params: dict[str, Any] | None = None, fields: dict | None = None) -> dict:
+    return {"detail": detail, "detail_code": code, "detail_params": params or {}, "field_errors": fields or {}}
+
+
+def _entry(description: str, examples: dict[str, tuple[str, dict]]) -> dict[str, Any]:
+    return {
+        "model": ApiErrorBody,
+        "description": description,
+        "content": {
+            "application/json": {
+                "examples": {name: {"summary": summary, "value": value} for name, (summary, value) in examples.items()}
+            }
+        },
+    }
+
+
+NOT_FOUND_RESPONSE = {
+    "404": _entry(
+        "No item has the primary key `pk`: `fastapi-viewsets.not_found`.",
+        {
+            "not_found": (
+                "No item with this primary key",
+                _example("Item with pk 42 not found", _namespaced("not_found"), {"pk": 42}),
+            )
+        },
+    )
+}
+"""The `responses` entry of the endpoints that address one item by `pk`."""
+
+BULK_NOT_FOUND_RESPONSE = {
+    "404": _entry(
+        "A primary key of the body has no item: `fastapi-viewsets.not_found`.",
+        {
+            "not_found": (
+                "No item with this primary key",
+                _example("Item with pk 42 not found", _namespaced("not_found"), {"pk": 42}),
+            )
+        },
+    )
+}
+"""The `responses` entry of the bulk endpoints that address items by the primary keys of the body."""
+
+_VALIDATION_FAILED_EXAMPLE = (
+    "A value of the request failed validation",
+    _example(
+        VALIDATION_FAILED_DETAIL,
+        _namespaced("validation_failed"),
+        fields={
+            "name": [
+                {
+                    "code": "pydantic.string_too_short",
+                    "params": {"min_length": 3},
+                    "detail": "String should have at least 3 characters",
+                }
+            ],
+            "": [{"code": "pydantic.missing", "params": {}, "detail": "Field required"}],
+        },
+    ),
+)
+
+_IDEMPOTENCY_KEY_REUSED_EXAMPLE = (
+    "With the Idempotency middleware: the Idempotency-Key was recorded for a different request",
+    _example(
+        "Idempotency key k1 was used for a different request", _namespaced("idempotency_key_reused"), {"key": "k1"}
+    ),
+)
+
+_422_DESCRIPTION = (
+    "The request failed validation: `fastapi-viewsets.validation_failed`, with each failure in `field_errors` "
+    "under the name of its field. With the `Idempotency` middleware, an `Idempotency-Key` recorded for a "
+    "different request: `fastapi-viewsets.idempotency_key_reused`."
+)
+
+_DEFAULT_DESCRIPTION = (
+    "Any other error, with the same body. The package's own errors carry their codes (see the error codes "
+    "guide): 400 `fastapi-viewsets.idempotency_key_invalid` (with the `Idempotency` middleware), 401 "
+    "`fastapi-viewsets.session_expired` (with the `Session` middleware), 403 `fastapi-viewsets.not_authorized` "
+    "(with the `Authorization` middleware), 405 `fastapi-viewsets.read_only` (a read-only collection), 429 "
+    "`fastapi-viewsets.rate_limited` (with the `RateLimiter` middleware), 503 and 504 of a deferred action. "
+    "An `HTTPException` of the application, or of a dependency, without a code of its own answers "
+    "`fastapi-viewsets.http_error` with its status in `detail_params.status`."
+)
+
+_HTTP_ERROR_EXAMPLE = (
+    "An HTTPException without a code",
+    _example("Not your item", _namespaced("http_error"), {"status": 403}),
+)
+
+_RATE_LIMITED_EXAMPLE = (
+    "With the RateLimiter middleware: the call was refused",
+    _example("Rate limit exceeded", _namespaced("rate_limited")),
+)
+
+VIEWSET_ERROR_RESPONSES = {
+    "422": _entry(
+        _422_DESCRIPTION,
+        {"validation_failed": _VALIDATION_FAILED_EXAMPLE, "idempotency_key_reused": _IDEMPOTENCY_KEY_REUSED_EXAMPLE},
+    ),
+    "500": _entry(
+        "The endpoint raised an exception without a handler: `fastapi-viewsets.unhandled_error`. The body "
+        "names no part of the exception; the server logs it. A deferred action that failed in its executor "
+        "answers `fastapi-viewsets.action_failed`.",
+        {
+            "unhandled_error": (
+                "An exception without a handler",
+                _example("Internal Server Error", _namespaced("unhandled_error")),
+            )
+        },
+    ),
+    "default": _entry(_DEFAULT_DESCRIPTION, {"http_error": _HTTP_ERROR_EXAMPLE, "rate_limited": _RATE_LIMITED_EXAMPLE}),
+}
+"""The `responses` entries every endpoint of a viewset carries, under the endpoint's own entries."""
+
+CURSOR_ERROR_RESPONSES = {
+    "default": _entry(
+        _DEFAULT_DESCRIPTION + " A `cursor` the list cannot continue from answers 400: "
+        "`fastapi-viewsets.cursor_unreadable`, `fastapi-viewsets.cursor_missing_position`, "
+        "`fastapi-viewsets.cursor_stale`, `fastapi-viewsets.cursor_missing_keys`, "
+        "`fastapi-viewsets.cursor_value_mismatch`.",
+        {
+            "http_error": _HTTP_ERROR_EXAMPLE,
+            "cursor_stale": (
+                "The cursor belongs to another query",
+                _example(
+                    "this cursor was issued for a different ordering or filter - start from the first page",
+                    _namespaced("cursor_stale"),
+                ),
+            ),
+            "rate_limited": _RATE_LIMITED_EXAMPLE,
+        },
+    ),
+}
+"""The `responses` entry of the list endpoint; `route_viewset` keeps it on a viewset serving the cursor shape."""
+
+SUBSCRIBE_ERROR_RESPONSES = {
+    "422": _entry(
+        _422_DESCRIPTION + " A malformed topic: `fastapi-viewsets.event_topic_invalid`.",
+        {
+            "validation_failed": _VALIDATION_FAILED_EXAMPLE,
+            "event_topic_invalid": (
+                "A malformed topic",
+                _example(
+                    "Topic @x is neither a path starting with / nor a source name with an optional key",
+                    _namespaced("event_topic_invalid"),
+                    {"topic": "@x"},
+                ),
+            ),
+            "idempotency_key_reused": _IDEMPOTENCY_KEY_REUSED_EXAMPLE,
+        },
+    ),
+}
+"""The `responses` entry of the events `subscribe` endpoint."""
+
+POLL_ERROR_RESPONSES = {
+    "422": _entry(
+        _422_DESCRIPTION + " More cursors than `settings.viewsets_event_max_subscriptions`: "
+        "`fastapi-viewsets.event_cursors_exceeded`.",
+        {
+            "validation_failed": _VALIDATION_FAILED_EXAMPLE,
+            "event_cursors_exceeded": (
+                "More cursors than the server accepts in one poll",
+                _example(
+                    "A poll carries at most 256 cursors, this one carries 300",
+                    _namespaced("event_cursors_exceeded"),
+                    {"count": 300, "limit": 256},
+                ),
+            ),
+            "idempotency_key_reused": _IDEMPOTENCY_KEY_REUSED_EXAMPLE,
+        },
+    ),
+}
+"""The `responses` entry of the events `poll` endpoint."""
+
+
+def with_error_responses(responses: dict | None) -> dict:
+    """`responses` over `VIEWSET_ERROR_RESPONSES`: an entry of `responses` replaces the entry of
+    the same status."""
+    merged = dict(VIEWSET_ERROR_RESPONSES)
+    merged.update({str(status): entry for status, entry in (responses or {}).items()})
+    return merged

{dynamicforms_fastapi_viewsets-0.15.1 → dynamicforms_fastapi_viewsets-0.15.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "dynamicforms-fastapi-viewsets"
-version = "0.15.1"
+version = "0.15.2"
 description = "Django REST Framework-style viewsets for FastAPI, with optional Celery-backed async execution and a Vue/TypeScript client counterpart."
 readme = "README.md"
 license = "MIT"

{dynamicforms_fastapi_viewsets-0.15.1 → dynamicforms_fastapi_viewsets-0.15.2}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "dynamicforms-fastapi-viewsets"
-version = "0.15.1"
+version = "0.15.2"
 description = "Django REST Framework-style viewsets for FastAPI, with optional Celery-backed async execution and a Vue/TypeScript client counterpart."
 readme = "README.md"
 license = "MIT"

dynamicforms_fastapi_viewsets-0.15.1/fastapi_viewsets/response_classes.py

@@ -1,113 +0,0 @@
-"""
-The OpenAPI `responses` entries of the error responses of a viewset's endpoints. Every entry
-documents the body as `ApiErrorBody` (`fastapi_viewsets.error_responses`).
-"""
-
-from typing import Any
-
-from .error_namespace import _namespaced
-from .error_responses import ApiErrorBody, VALIDATION_FAILED_DETAIL
-
-
-def _example(detail: str, code: str, params: dict[str, Any] | None = None, fields: dict | None = None) -> dict:
-    return {"detail": detail, "detail_code": code, "detail_params": params or {}, "field_errors": fields or {}}
-
-
-def _entry(description: str, examples: dict[str, tuple[str, dict]]) -> dict[str, Any]:
-    return {
-        "model": ApiErrorBody,
-        "description": description,
-        "content": {
-            "application/json": {
-                "examples": {name: {"summary": summary, "value": value} for name, (summary, value) in examples.items()}
-            }
-        },
-    }
-
-
-NOT_FOUND_RESPONSE = {
-    "404": _entry(
-        "No item has the primary key `pk`: `fastapi-viewsets.not_found`.",
-        {
-            "not_found": (
-                "No item with this primary key",
-                _example("Item with pk 42 not found", _namespaced("not_found"), {"pk": 42}),
-            )
-        },
-    )
-}
-"""The `responses` entry of the endpoints that address one item by `pk`."""
-
-VIEWSET_ERROR_RESPONSES = {
-    "422": _entry(
-        "The request failed validation: `fastapi-viewsets.validation_failed`, with each failure in "
-        "`field_errors` under the name of its field. A check the package makes of a valid request "
-        "answers 422 too: `fastapi-viewsets.idempotency_key_reused`, `fastapi-viewsets.unsupported_list_shape`, "
-        "`fastapi-viewsets.event_topic_invalid`, `fastapi-viewsets.event_cursors_exceeded`.",
-        {
-            "validation_failed": (
-                "A value of the request failed validation",
-                _example(
-                    VALIDATION_FAILED_DETAIL,
-                    _namespaced("validation_failed"),
-                    fields={
-                        "name": [
-                            {
-                                "code": "pydantic.string_too_short",
-                                "params": {"min_length": 3},
-                                "detail": "String should have at least 3 characters",
-                            }
-                        ],
-                        "": [{"code": "pydantic.missing", "params": {}, "detail": "Field required"}],
-                    },
-                ),
-            ),
-            "idempotency_key_reused": (
-                "The Idempotency-Key was recorded for a different request",
-                _example(
-                    "Idempotency key k1 was used for a different request",
-                    _namespaced("idempotency_key_reused"),
-                    {"key": "k1"},
-                ),
-            ),
-        },
-    ),
-    "500": _entry(
-        "The endpoint raised an exception without a handler: `fastapi-viewsets.unhandled_error`. The body "
-        "names no part of the exception; the server logs it. A deferred action that failed in its executor "
-        "answers `fastapi-viewsets.action_failed`.",
-        {
-            "unhandled_error": (
-                "An exception without a handler",
-                _example("Internal Server Error", _namespaced("unhandled_error")),
-            )
-        },
-    ),
-    "default": _entry(
-        "Any other error, with the same body. The package's own errors carry their codes (see the error "
-        "codes guide): 400 `fastapi-viewsets.idempotency_key_invalid` and the cursor codes, 401 "
-        "`fastapi-viewsets.session_expired`, 403 `fastapi-viewsets.not_authorized`, 405 "
-        "`fastapi-viewsets.read_only`, 429 `fastapi-viewsets.rate_limited`, 503 and 504 of a deferred "
-        "action. An `HTTPException` of the application, or of a dependency, without a code of its own "
-        "answers `fastapi-viewsets.http_error` with its status in `detail_params.status`.",
-        {
-            "http_error": (
-                "An HTTPException without a code",
-                _example("Not your item", _namespaced("http_error"), {"status": 403}),
-            ),
-            "rate_limited": (
-                "Command middleware refused the call",
-                _example("Rate limit exceeded", _namespaced("rate_limited")),
-            ),
-        },
-    ),
-}
-"""The `responses` entries every endpoint of a viewset carries, under the endpoint's own entries."""
-
-
-def with_error_responses(responses: dict | None) -> dict:
-    """`responses` over `VIEWSET_ERROR_RESPONSES`: an entry of `responses` replaces the entry of
-    the same status."""
-    merged = dict(VIEWSET_ERROR_RESPONSES)
-    merged.update({str(status): entry for status, entry in (responses or {}).items()})
-    return merged