dynamicforms-fastapi-viewsets 0.6.4__tar.gz → 0.7.1__tar.gz

{dynamicforms_fastapi_viewsets-0.6.4 → dynamicforms_fastapi_viewsets-0.7.1}/PKG-INFO

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

dynamicforms_fastapi_viewsets-0.7.1/fastapi_viewsets/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.7.1"

{dynamicforms_fastapi_viewsets-0.6.4 → dynamicforms_fastapi_viewsets-0.7.1}/fastapi_viewsets/context/__init__.py

@@ -6,6 +6,8 @@ import json
 from abc import ABC, abstractmethod
 from typing import Any, TYPE_CHECKING
 
+from pydantic import BaseModel
+
 from ..conf import settings
 
 if TYPE_CHECKING:
@@ -300,6 +302,44 @@ def _resolve_class(dotted_path: str) -> type[SerializableObject]:
     return cls
 
 
+def serialize_value(value: Any) -> Any:
+    """
+    Tag a single SerializableObject for JSON transport, the same convention serialize_context()
+    applies per context key (see _TYPE_KEY/_VALUE_KEY above); anything else passes through
+    unchanged. For a value crossing the Celery/Redis boundary outside a Context dict - e.g. a
+    command-middleware ViewSetResult returned by a celery_viewset-dispatched action (see
+    fastapi_viewsets.middleware.ViewSetResult).
+    """
+    if isinstance(value, SerializableObject):
+        return {_TYPE_KEY: _class_tag(type(value)), _VALUE_KEY: value.__serialize__()}
+    return value
+
+
+def to_jsonable(value: Any) -> Any:
+    """
+    Recursively convert a value into a JSON-safe structure: a SerializableObject is tagged (see
+    serialize_value()), a Pydantic model is dumped, a list/tuple is recursed into element-wise -
+    anything else passes through unchanged. The one shared implementation of a conversion several
+    call sites need on their own single (non-Context, non-dict) return/body value - ViewSetResult's
+    own (de)serialization, and a celery_viewset worker's task result - rather than each keeping a
+    slightly different copy that drifts out of sync with what the others handle.
+    """
+    if isinstance(value, SerializableObject):
+        return serialize_value(value)
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, (list, tuple)):
+        return [to_jsonable(v) for v in value]
+    return value
+
+
+def deserialize_value(value: Any) -> Any:
+    """Inverse of serialize_value() - passes through anything that isn't a tagged payload."""
+    if isinstance(value, dict) and _TYPE_KEY in value and _VALUE_KEY in value:
+        return _resolve_class(value[_TYPE_KEY]).__deserialize__(value[_VALUE_KEY])
+    return value
+
+
 async def serialize_context(data: dict[str, Any]) -> dict[str, Any]:
     """
     Returns a JSON-safe dict: SerializableObject values are swapped for a tagged payload (see

{dynamicforms_fastapi_viewsets-0.6.4 → dynamicforms_fastapi_viewsets-0.7.1}/fastapi_viewsets/decorators/build_schema.py

@@ -6,6 +6,7 @@ from fastapi import APIRouter, FastAPI
 from fastapi.routing import APIRoute
 
 from ..endpoint_docs import docs_for, viewset_tags
+from ..middleware import unwrap_viewset_result_type
 
 
 def _generic_args(annotation) -> tuple:
@@ -94,12 +95,15 @@ def build_schema(cls, base_path: str = "", default_tags=None, get_wrapper=None,
     and attaches them to the class. Idempotent: if already called, returns immediately.
     If get_wrapper is None, only __router is built (no FastAPI app, no endpoint wrapping).
 
-    disable_response_model: pass True when command middleware is configured (see
-    fastapi_viewsets/middleware.py and route_viewset.py) - middleware can change the shape of what's
-    actually served (e.g. strip an internal-only field via ViewSetResult.body), so FastAPI must not
-    coerce/re-validate the endpoint's return value against the ORIGINAL method's declared return
-    type, which would silently undo those changes (missing fields reappear with their model
-    defaults).
+    disable_response_model: pass True when a configured command middleware declares
+    modifies_response_shape=True (see Middleware.modifies_response_shape and
+    any_modifies_response_shape() in fastapi_viewsets/middleware/__init__.py, and route_viewset.py) -
+    such a middleware can change the shape of what's actually served (e.g. strip an internal-only
+    field via ViewSetResult.body), so FastAPI must not coerce/re-validate the endpoint's return value
+    against the ORIGINAL method's declared return type, which would silently undo those changes
+    (missing fields reappear with their model defaults). Middleware that doesn't declare this (the
+    default) leaves the endpoint's declared return type in place, both in the OpenAPI docs and for
+    FastAPI's own response validation.
     """
     if hasattr(cls, "__router") and (get_wrapper is None or getattr(cls, "__router_full", False)):
         return
@@ -163,6 +167,11 @@ def build_schema(cls, base_path: str = "", default_tags=None, get_wrapper=None,
                 # answer: only route_viewset knows what this viewset bound it to.
                 use_resolved = route.response_model is None or has_typevars(route.response_model)
                 response_model = resolved_response_model if use_resolved else route.response_model
+                # route.response_model is FastAPI's own inference from the ORIGINAL declared return
+                # type (e.g. -> ViewSetResult[Item]), untouched by get_wrapper's own unwrap - must be
+                # unwrapped here too, or an endpoint declared this way would document/validate as the
+                # wrapper instead of the wire body whenever use_resolved is False.
+                response_model = unwrap_viewset_result_type(response_model)
 
             # Per-viewset wording, applied here because this is where the schema-serving app is
             # built; patching the caller's router afterwards would leave /schema showing the

{dynamicforms_fastapi_viewsets-0.6.4 → dynamicforms_fastapi_viewsets-0.7.1}/fastapi_viewsets/decorators/celery_viewset/client.py

@@ -6,9 +6,7 @@ from collections.abc import Awaitable, Callable
 from functools import wraps
 from typing import TYPE_CHECKING, TypeVar
 
-from pydantic import BaseModel
-
-from ...context import Context, serialize_context
+from ...context import Context, serialize_context, to_jsonable
 from ..build_schema import build_schema
 from . import result_reader
 from .result_reader import get_result_queue_key
@@ -84,16 +82,17 @@ def celery_viewset_client(
 
 
 async def _serialize_value(value):
-    """Convert a Context, BaseModel, list, or dict value into a JSON-safe structure for Celery/Kombu transport."""
+    """Convert a Context, dict, or list/tuple value into a JSON-safe structure for Celery/Kombu
+    transport, recursing async since Context serialization needs to await context values. Anything
+    else - a Pydantic model, a SerializableObject, or an already JSON-native value - is handled by
+    the shared, synchronous fastapi_viewsets.context.to_jsonable()."""
     if isinstance(value, Context):
         return await serialize_context(value.raw())
-    if isinstance(value, BaseModel):
-        return value.model_dump(mode="json")
     if isinstance(value, dict):
         return {k: await _serialize_value(v) for k, v in value.items()}
     if isinstance(value, (list, tuple)):
         return [await _serialize_value(v) for v in value]
-    return value
+    return to_jsonable(value)
 
 
 def _patch_method(cls: type, original_endpoint, task_name: str, celery_app, queue_key: str):

{dynamicforms_fastapi_viewsets-0.6.4 → dynamicforms_fastapi_viewsets-0.7.1}/fastapi_viewsets/decorators/celery_viewset/result_reader.py

@@ -6,6 +6,8 @@ from typing import TYPE_CHECKING
 
 from fastapi import HTTPException
 
+from ...context import deserialize_value
+
 if TYPE_CHECKING:
     import redis
 
@@ -59,7 +61,9 @@ async def result_reader_loop(redis_client: "redis.Redis", queue_key: str, poll_i
                     else:
                         future.set_exception(Exception(error))
                 else:
-                    future.set_result(result)
+                    # Undoes _to_jsonable's SerializableObject tagging (see server.py) - a plain
+                    # domain result has no _TYPE_KEY/_VALUE_KEY pair and passes through unchanged.
+                    future.set_result(deserialize_value(result))
 
         except asyncio.CancelledError:
             break

{dynamicforms_fastapi_viewsets-0.6.4 → dynamicforms_fastapi_viewsets-0.7.1}/fastapi_viewsets/decorators/celery_viewset/server.py

@@ -11,7 +11,7 @@ from typing import get_args, get_origin, get_type_hints, TYPE_CHECKING, TypeVar,
 from fastapi import HTTPException
 from pydantic import BaseModel
 
-from ...context import Context, deserialize_context
+from ...context import Context, deserialize_context, to_jsonable
 from ..build_schema import build_schema
 from ..lifecycle_runner import lifecycle_runner, LifecycleType
 from ..route_viewset import build_type_map, resolve_typevars
@@ -50,13 +50,12 @@ def _unwrap_optional(hint):
     return hint
 
 
-def _to_jsonable(value):
-    """Recursively convert Pydantic models and lists to JSON-serializable structures."""
-    if isinstance(value, BaseModel):
-        return value.model_dump(mode="json")
-    if isinstance(value, list):
-        return [_to_jsonable(v) for v in value]
-    return value
+# Alias, not a re-implementation: the actual conversion (Pydantic models, lists/tuples,
+# SerializableObject values - e.g. a ViewSetResult a worker-side action returned directly, see
+# fastapi_viewsets.middleware) lives in fastapi_viewsets.context.to_jsonable, shared with
+# ViewSetResult's own (de)serialization. Kept under this name since call sites/tests here already
+# import it as `_to_jsonable`.
+_to_jsonable = to_jsonable
 
 
 def _reconstruct_value(hint, value):

{dynamicforms_fastapi_viewsets-0.6.4 → dynamicforms_fastapi_viewsets-0.7.1}/fastapi_viewsets/decorators/lifecycle_runner.py

@@ -68,7 +68,11 @@ async def lifecycle_runner(
             return await call_bound(req_instance)
 
         async def final_handler() -> ViewSetResult:
-            return ViewSetResult(body=await call_bound(req_instance))
+            raw = await call_bound(req_instance)
+            # An endpoint may return a ViewSetResult directly (see ViewSetResult in
+            # fastapi_viewsets/middleware) to reach status_code/headers/cookies itself - passed
+            # through as-is.
+            return raw if isinstance(raw, ViewSetResult) else ViewSetResult(body=raw)
 
         effective_middlewares = settings.viewsets_command_middleware + extra_middlewares_for(
             action_configuration, settings.viewsets_command_middleware

{dynamicforms_fastapi_viewsets-0.6.4 → dynamicforms_fastapi_viewsets-0.7.1}/fastapi_viewsets/decorators/route_viewset.py

@@ -21,7 +21,7 @@ from fastapi_viewsets.endpoint_docs import (
     register_tag,
     viewset_description,
 )
-from fastapi_viewsets.middleware import Middleware
+from fastapi_viewsets.middleware import any_modifies_response_shape, Middleware, unwrap_viewset_result_type
 from fastapi_viewsets.mixins import FilterParam
 from fastapi_viewsets.mux_ws import register_viewset, resolve_register_muxws, resolve_register_rest
 
@@ -298,7 +298,8 @@ def route_viewset(
                 # right before the endpoint runs - never forwarded to the endpoint itself.
                 new_params.append(inspect.Parameter("request", inspect.Parameter.KEYWORD_ONLY, annotation=Request))
 
-            new_return_annotation = resolve_typevars(type_map, sig.return_annotation)
+            # -> ViewSetResult[X] documents/validates as X - see unwrap_viewset_result_type.
+            new_return_annotation = unwrap_viewset_result_type(resolve_typevars(type_map, sig.return_annotation))
             new_sig = sig.replace(parameters=new_params, return_annotation=new_return_annotation)
 
             @wraps(original_endpoint)
@@ -342,14 +343,16 @@ def route_viewset(
             return wrapper, new_return_annotation
 
         # Command middleware (see fastapi_viewsets/middleware.py) can reshape the response body via
-        # ViewSetResult - if any is configured, the endpoint's declared return type can no longer
-        # be trusted as the actual response_model, same reasoning as the old finalize_response hook.
+        # ViewSetResult - only middleware that actually declares modifies_response_shape=True
+        # untrusts the endpoint's declared return type as the response_model (same reasoning as the
+        # old finalize_response hook); typical middleware (auth, rate limiting, sessions) only adds
+        # headers/cookies and leaves the declared model - and therefore the OpenAPI docs - in place.
         build_schema(
             cls,
             base_path,
             default_tags,
             get_wrapper,
-            disable_response_model=bool(settings.viewsets_command_middleware),
+            disable_response_model=any_modifies_response_shape(settings.viewsets_command_middleware),
         )
 
         muxws_routes = []

{dynamicforms_fastapi_viewsets-0.6.4 → dynamicforms_fastapi_viewsets-0.7.1}/fastapi_viewsets/middleware/__init__.py

@@ -1,16 +1,18 @@
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
-from typing import Any, TYPE_CHECKING
+from typing import Any, Generic, get_args, get_origin, TYPE_CHECKING, TypeVar
 
-from ..context import Context
+from ..context import Context, SerializableObject, to_jsonable
 
 if TYPE_CHECKING:
     from fastapi import Request
 
+T = TypeVar("T")
+
 
 @dataclass
-class ViewSetResult:
+class ViewSetResult(SerializableObject, Generic[T]):
     """
     Transport-agnostic result of running the command middleware chain (see run_command_chain()
     below). `body` is the actual domain value (whatever perform_* returned); `headers`/`cookies`
@@ -22,13 +24,44 @@ class ViewSetResult:
     onto real Set-Cookie, and `status_code` onto the real Response's status code; a future WS
     adapter would fold all three into the outgoing message payload as plain JSON keys instead (no
     real headers/cookies/status line exist over WS).
+
+    A registered route endpoint (a mixin-provided one, or a custom `__router` method - never a
+    `perform_*` hook, which is called by the actual route method and never registered as a route
+    itself) may also return a `ViewSetResult` directly instead of a plain body, getting the same
+    `status_code`/`headers`/`cookies` access normally reserved for command middleware (e.g. a
+    redirect: `ViewSetResult(body=None, status_code=302, headers={"Location": url})`) -
+    `lifecycle_runner.final_handler` passes it through unchanged. Declare the return type as
+    `ViewSetResult[X]` (X being whatever the wire body actually is) rather than bare `X` -
+    `route_viewset`/`build_schema` unwrap this to `X` for the OpenAPI response_model and FastAPI's
+    own response validation (see unwrap_viewset_result_type below), so the two forms
+    document/validate identically.
+
+    Inherits `SerializableObject` so it survives the Celery/Redis boundary: a
+    `celery_viewset`-dispatched action's worker-side return value is passed through
+    `serialize_value()`/`deserialize_value()` (see fastapi_viewsets.context) exactly like any other
+    `SerializableObject`, the same mechanism `LazyObject`/`Context` values already rely on. Only
+    `__serialize__`/`__deserialize__` are overridden here - a `ViewSetResult` is never itself placed
+    in a `Context` and never awaited, so `SerializableObject`'s `value`/`__await__`/`__init__` go
+    unused, the same way `LazyObject` replaces those with its own.
     """
 
-    body: Any
+    body: T
     headers: dict[str, Any] = field(default_factory=dict)
     cookies: dict[str, Any] = field(default_factory=dict)
     status_code: int | None = None
 
+    def __serialize__(self) -> Any:
+        return {
+            "body": to_jsonable(self.body),
+            "headers": self.headers,
+            "cookies": self.cookies,
+            "status_code": self.status_code,
+        }
+
+    @classmethod
+    def __deserialize__(cls, data: Any) -> "ViewSetResult":
+        return cls(body=data["body"], headers=data["headers"], cookies=data["cookies"], status_code=data["status_code"])
+
 
 CommandMiddleware = Callable[
     ["Request | None", Any, Context, Callable[[], Awaitable[ViewSetResult]]],
@@ -57,6 +90,20 @@ class Middleware(ABC):
     concrete example) - a bare function would need extra indirection (closures, partials) for that.
     """
 
+    modifies_response_shape: bool = False
+    """
+    Whether this middleware can change the shape of ViewSetResult.body (strip/rename/restructure
+    fields, not just add side-channel headers/cookies or a status code) - see
+    `any_modifies_response_shape()` below. False by default: typical middleware (auth, rate
+    limiting, sessions) only inspects the result or attaches headers/cookies, so the endpoint's
+    declared return type stays a trustworthy response_model. Override to True on a middleware whose
+    __call__ actually reassigns `result.body` to something that no longer matches the original
+    return annotation - otherwise FastAPI's response_model validation will coerce the reshaped body
+    back towards the original model (e.g. reintroducing a stripped field with its default value).
+    A plain function middleware declares this the same way, by setting the attribute on the
+    function object: `my_middleware.modifies_response_shape = True`.
+    """
+
     def config_from(self, context: Context) -> Any:
         """
         This middleware's own @action_configuration value for the current call (see
@@ -104,6 +151,33 @@ class Middleware(ABC):
         raise NotImplementedError
 
 
+def any_modifies_response_shape(middlewares: list) -> bool:
+    """
+    Whether any entry in `middlewares` (a mix of Middleware instances and/or plain functions, as
+    settings.viewsets_command_middleware holds) declares modifies_response_shape=True. A bare
+    function that never set the attribute is treated as False, same default as the Middleware
+    class - see Middleware.modifies_response_shape above. Used by route_viewset/build_schema to
+    decide whether an endpoint's declared response_model can still be trusted for OpenAPI docs and
+    FastAPI's own response validation.
+    """
+    return any(getattr(middleware, "modifies_response_shape", False) for middleware in middlewares)
+
+
+def unwrap_viewset_result_type(annotation: Any) -> Any:
+    """
+    An endpoint declared `-> ViewSetResult[X]` (see ViewSetResult above) documents/validates as
+    `X` - the wire body a client actually receives, not the side-channel wrapper the endpoint
+    returns internally to reach `status_code`/`headers`/`cookies`. `route_viewset`/`build_schema`
+    call this wherever a return annotation becomes an OpenAPI response_model, so `-> ViewSetResult[X]`
+    and plain `-> X` document/validate identically. Anything that isn't `ViewSetResult[...]` passes
+    through unchanged.
+    """
+    if get_origin(annotation) is ViewSetResult:
+        args = get_args(annotation)
+        return args[0] if args else None
+    return annotation
+
+
 async def run_command_chain(
     middlewares: list[CommandMiddleware],
     request: "Request | None",

dynamicforms_fastapi_viewsets-0.6.4/fastapi_viewsets/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.6.4"