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

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

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

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

@@ -15,7 +15,7 @@ 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
@@ -157,14 +157,24 @@ 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)
+
     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.1}/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.1}/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,11 +21,15 @@ 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.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.routing import MUXWS, openapi_endpoint, REST, transport_route_class
@@ -172,6 +177,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 +323,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 +341,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 +378,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 +414,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))
 
@@ -461,7 +542,7 @@ def _route(
             route, dependencies=dependencies, responses=with_error_responses(route.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 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.1}/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.1}/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.1}/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,
@@ -44,12 +45,17 @@ 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."""
 
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
     rev: int
     """The topic's current rev, 0 for a topic without events."""
     scope: str | None = None
@@ -68,7 +74,10 @@ 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."""
 
+    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."""
@@ -77,13 +86,17 @@ class PollRequest(BaseModel):
 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):
@@ -93,9 +106,14 @@ class TopicAnswer(BaseModel):
     and `status` set. `error`, `status` and `scope` are left out when None.
     """
 
+    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
@@ -114,6 +132,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

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

@@ -8,7 +8,7 @@ from collections.abc import AsyncIterable, AsyncIterator, Iterable
 from dataclasses import dataclass, field
 from typing import Any, Generic, TypeVar
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 
 TItem = TypeVar("TItem")
 """
@@ -61,12 +61,20 @@ class ListQuery:
 class PaginatedList(BaseModel, Generic[TItem]):
     """One page of results; `count` is None when the source cannot be counted without draining it."""
 
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
     results: list[TItem]
+    """The records of the page."""
     offset: int
+    """Number of records before the page."""
     limit: int | None
+    """Page size the page was read with."""
     count: int | None = None
+    """Number of records in the whole list; null when the source cannot be counted."""
     has_more: bool = False
+    """Whether records follow the page."""
     has_previous: bool = False
+    """Whether records precede the page."""
 
 
 def build_list_query(fltr: Any, sort: str | None, offset: int = 0, limit: int | None = None) -> ListQuery:

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

@@ -6,7 +6,7 @@ from typing import Annotated, Any, final, Generic, get_args, get_origin, Union
 
 from fastapi import APIRouter, Header, Query
 from fastapi.exceptions import RequestValidationError
-from pydantic import BaseModel, ConfigDict, create_model
+from pydantic import BaseModel, ConfigDict, create_model, Field
 from pydantic.alias_generators import to_camel
 from starlette.exceptions import HTTPException
 from typing_extensions import TypeVar
@@ -200,13 +200,22 @@ class SortStateColumn(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
 
-    column_name: str
-    direction: SortDirection = SortDirection.asc
+    column_name: str = Field(description="Name of the field to order by.")
+    direction: SortDirection = Field(SortDirection.asc, description="`asc` or `desc`.")
 
 
 SortState = list[SortStateColumn]
 
 
+OFFSET_DESCRIPTION = "Number of records to skip before the page."
+"""The `offset` parameter's description on every paginated list endpoint."""
+
+CURSOR_DESCRIPTION = (
+    "Position to read from: `next`, `previous`, `first` or `last` of a page returned by the same ordering and"
+    " filter. Omit for the first page."
+)
+"""The `cursor` parameter's description on every cursor list endpoint."""
+
 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"
@@ -318,9 +327,9 @@ class ListMixin(Generic[T, TFilter], ABC):
         context: Context,
         fltr: Annotated[TFilter, Query()] = 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,
+        offset: Annotated[int, Query(ge=0, description=OFFSET_DESCRIPTION)] = 0,
+        limit: Annotated[int | None, Query(ge=1, description="Page size.")] = None,
+        cursor: Annotated[str | None, Query(description=CURSOR_DESCRIPTION)] = None,
         x_list_shape: Annotated[str | None, Header()] = None,
     ) -> Union[list[T], PaginatedList[T], CursorPage[T]]:  # noqa: UP007 - see list_shapes.response_model
         """List the collection."""
@@ -705,16 +714,18 @@ class BulkDestroyMixin(DestroyMixin[K, T], BulkOnlyDestroyMixin[K, T]):
 # LOOKUP
 ###################################################################################################
 class LookupItem(BaseModel):
-    group: Any = None
-    pk: object
-    title: str
-    icon: str | None = None
+    """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.")
+    title: str = Field(description="Text shown for the choice.")
+    icon: str | None = Field(None, description="Icon shown with the choice; null for none.")
 
 
 class LookupFilter(BaseModel):
     """Default filter model for LookupMixin. Provides case-insensitive title search via q."""
 
-    q: str | None = None
+    q: str | None = Field(None, description="Text the choice's title contains, case-insensitive. Omit for all choices.")
 
 
 TLookupFilter = TypeVar("TLookupFilter", default=LookupFilter)

{dynamicforms_fastapi_viewsets-0.15.0 → dynamicforms_fastapi_viewsets-0.15.1}/fastapi_viewsets/routing.py

@@ -9,6 +9,7 @@ from typing import Any
 
 from fastapi import FastAPI
 from fastapi.routing import APIRoute
+from pydantic import BaseModel, ConfigDict, Field
 from starlette.exceptions import HTTPException
 from starlette.routing import Match
 from starlette.types import Message, Receive, Scope, Send
@@ -78,6 +79,30 @@ def transport_route_class(base: type[APIRoute], transports: frozenset[str]) -> t
     return type(name, (TransportRoute, base), {"transports": transports})
 
 
+class OpenAPIDocument(BaseModel):
+    """An OpenAPI 3.1 document (https://spec.openapis.org/oas/v3.1.0); members not listed here are kept."""
+
+    model_config = ConfigDict(extra="allow")
+
+    openapi: str = Field(description="Version of the OpenAPI specification the document follows.")
+    info: dict[str, Any] = Field(description="Title and version of the API.")
+    paths: dict[str, Any] = Field(description="The endpoints, by path and HTTP method.")
+    components: dict[str, Any] | None = Field(None, description="Schemas the endpoints refer to.")
+    tags: list[dict[str, Any]] | None = Field(None, description="Names and descriptions of the endpoint groups.")
+
+
+SCHEMA_ENDPOINT_DOCS: dict[str, Any] = {
+    "description": (
+        "OpenAPI document of this viewset's endpoints on the transport it is requested over (REST or muxws),"
+        " this endpoint included."
+    ),
+    "response_description": "The OpenAPI document.",
+    "responses": {200: {"model": OpenAPIDocument}},
+    "response_model": None,
+}
+"""`add_api_route` keyword arguments of every viewset's `/schema` endpoint; `@endpoint_docs` key `schema`."""
+
+
 def openapi_endpoint(route_kwargs: list[dict[str, Any]]) -> Callable[[], dict[str, Any]]:
     """
     A `/schema` endpoint with the OpenAPI document of `route_kwargs` (`add_api_route` form), built on

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "dynamicforms-fastapi-viewsets"
-version = "0.15.0"
+version = "0.15.1"
 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.0 → dynamicforms_fastapi_viewsets-0.15.1}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "dynamicforms-fastapi-viewsets"
-version = "0.15.0"
+version = "0.15.1"
 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"