Release v0.3.2: compose multiple FastPayloads in one Response

FastJSONRenderer now handles dict responses whose values mix FastPayload
markers with arbitrary Python. Each FastPayload encodes via pydantic-core
(Rust), each plain value via DRF's stock JSONEncoder. Walks data in
insertion order so output key order matches input. Keys are escaped
via json.dumps so quotes and backslashes in user-supplied keys still
produce valid JSON.

Unblocks bundle-style endpoints (e.g. a single worksheet response
returning header + transactions + balances + summary, four separate
FastSerializer schemas) without manual byte splicing, slot-level
access to FastPayload internals, or model_dump mode juggling that
loses the Rust render path entirely.

Pagination envelopes flow through the same composed path; the dedicated
_render_paginated helper is gone, behavior is unchanged, regression
test added.

Indented output (indent= in renderer_context, or non-compact JSON
setting) falls back to materializing every FastPayload and routing
through super().render() since pydantic-core's dump_json is compact-only
and join bytes wouldn't have indentation structure. Debug-mode only;
hot paths stay on the fast path.

Known limit: only top-level dict values are inspected. A FastPayload
nested inside a list or sub-dict still falls through to stock and
raises. Lift the inner payload up a level, or encode manually.

Author: ankitksr

CHANGELOG.md

@@ -7,6 +7,35 @@ versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-05-25
+
+### Added
+- `FastJSONRenderer` now composes dict responses whose values are a mix
+  of `FastPayload` markers and arbitrary Python. Each `FastPayload` is
+  encoded via pydantic-core (Rust); each plain value is encoded with
+  DRF's stock `JSONEncoder`. Keys are emitted in input insertion order
+  and escaped via `json.dumps`. Unlocks bundle-style endpoints
+  (multiple `Schema.drf(...).data` values in one `Response({...})`)
+  without manual byte splicing or mode-juggling on `model_dump`.
+- Pagination envelopes (`{"results": FastPayload, "count": int, ...}`)
+  flow through the same composed path. The dedicated
+  `_render_paginated` helper is gone; pagination behavior is unchanged
+  and covered by both `test_pagination.py` and a new explicit
+  regression in `test_renderer.py`.
+
+### Changed
+- Composed responses fall back to materialize-via-`super().render()`
+  when `renderer_context` requests indented output or DRF is set to
+  non-compact JSON, since the Rust `dump_json` path can't pretty-print.
+  Pretty output is debug-only and rarely on the hot path.
+
+### Known limitation
+- Only top-level `FastPayload` values in a dict are picked up.
+  `FastPayload` nested inside a list or sub-dict still falls through to
+  stock encoding and raises (no in-place encoder for sub-trees). If
+  this comes up in practice, lift the inner payload to a `Schema.drf`
+  one level up, or encode it manually.
+
 ## [0.3.1] - 2026-05-25
 
 ### Added

README.md

@@ -135,6 +135,33 @@ encoding for error responses, hand-rolled dicts, the browsable API, and
 anything else it doesn't recognize. Safe as a project-wide default. Set
 `renderer_classes` per view if you want to roll it out gradually.
 
+### Composed responses
+
+Bundle-style endpoints often return multiple serialized payloads under
+one dict. The renderer handles that natively — every value that is a
+`FastPayload` goes through pydantic-core (Rust), everything else
+through DRF's stock `JSONEncoder`. Key order is preserved.
+
+```python
+class WorksheetBundleView(APIView):
+    renderer_classes = [FastJSONRenderer]
+
+    def get(self, request, uid):
+        ws = Worksheet.objects.get(uid=uid)
+        return Response({
+            "worksheet":    FastWorksheetHeader.drf(instance=ws).data,
+            "transactions": BundleTxnRow.drf(instance=ws.transactions.all(), many=True).data,
+            "balances":     BundleBalanceRow.drf(instance=ws.balances.all(), many=True).data,
+            "summary_rows": BundleSummaryRow.drf(instance=ws.summary_rows.all(), many=True).data,
+            "meta":         {"as_of": now()},   # plain value: stock JSON encoder
+        })
+```
+
+Pagination envelopes flow through the same path with no special
+configuration. Indented output (`?format=json&indent=2`) falls back to
+a materialized render — the Rust encoder is compact-only — so leaving
+`COMPACT_JSON` at its default is what unlocks the speedup.
+
 ### SerializerMethodField
 
 Auto-translated. The bound `get_*` method runs once per row at validate

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "drf-fastserializers"
-version = "0.3.1"
+version = "0.3.2"
 description = "Drop-in pydantic-powered serializers for Django REST Framework. 2-3x faster on large payloads."
 readme = "README.md"
 license = "MIT"

src/drf_fastserializers/__init__.py

@@ -79,4 +79,4 @@ class TxnListView(ListAPIView):
     "PYD_V3",
 ]
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"

src/drf_fastserializers/renderer.py

@@ -6,11 +6,19 @@ class MyView(ListAPIView):
         renderer_classes = [FastJSONRenderer]
         serializer_class = TxnOut.drf
 
-Falls back to the stock `JSONRenderer` for any non-`FastPayload` payload
-(error responses, browsable API previews, hand-rolled dicts, etc.), so
-it is safe as a global default renderer in `REST_FRAMEWORK` settings.
+Three input shapes are handled directly:
+
+- A bare `FastPayload` (most views) → `adapter.dump_json` (Rust).
+- A dict with any `FastPayload` values (composed bundles, pagination
+  envelopes, etc.) → per-value walk; FastPayloads encode via Rust,
+  everything else via DRF's stock `JSONEncoder`.
+- Anything else (error responses, hand-rolled dicts, the browsable API,
+  ...) → super().render(), unchanged.
+
+The renderer is safe as a project-wide default.
 """
 
+import json
 from typing import Any
 
 from rest_framework.renderers import JSONRenderer
@@ -30,32 +38,56 @@ def render(
         if isinstance(data, FastPayload):
             return data.adapter.dump_json(data.instances)
 
-        if isinstance(data, dict) and isinstance(data.get("results"), FastPayload):
-            return self._render_paginated(data, accepted_media_type, renderer_context)
+        if isinstance(data, dict) and any(isinstance(v, FastPayload) for v in data.values()):
+            return self._render_composed(data, accepted_media_type, renderer_context)
 
         return super().render(data, accepted_media_type, renderer_context)
 
-    # DRF pagination wraps payloads as {"results": <FastPayload>, "next": ...}.
-    # Encode the inner payload with Rust, encode the wrapper with stock JSON,
-    # then splice the bytes. Cheap and correct: pagination metadata is small,
-    # results are the bulk.
-    def _render_paginated(
+    # Compose dict responses whose values are a mix of `FastPayload` markers
+    # (Rust-encoded) and arbitrary Python (encoded via DRF's JSONEncoder).
+    # Walks `data` in insertion order so output key order matches input.
+    # Pagination envelopes (`{"results": FastPayload, "count": int, ...}`)
+    # are a subset of this case — no separate pagination path.
+    def _render_composed(
         self,
         data: dict[str, Any],
         accepted_media_type: str | None,
         renderer_context: dict[str, Any] | None,
     ) -> bytes:
-        marker: FastPayload = data["results"]
-        inner = marker.adapter.dump_json(marker.instances)
-        wrapper = {k: v for k, v in data.items() if k != "results"}
-        wrapper_bytes = super().render(wrapper, accepted_media_type, renderer_context)
-        if not wrapper_bytes.endswith(b"}"):
-            # super().render may emit indented form; fall back to full materialize
-            return super().render(
-                {**wrapper, "results": marker._materialize()},
-                accepted_media_type,
-                renderer_context,
-            )
-        head = wrapper_bytes[:-1]
-        sep = b"," if wrapper else b""
-        return head + sep + b'"results":' + inner + b"}"
+        ctx = renderer_context or {}
+        indent = self.get_indent(accepted_media_type, ctx)
+        # Indented or non-compact output can't be assembled cleanly by
+        # byte-splicing — pydantic-core's dump_json output is compact,
+        # and join bytes would have no indentation. Materialize every
+        # `FastPayload` and route through super() for a consistent
+        # pretty-printed response. The fast path is the common case
+        # (default DRF settings: compact=True, indent=None).
+        if indent is not None or not self.compact:
+            materialized = {
+                k: v._materialize() if isinstance(v, FastPayload) else v
+                for k, v in data.items()
+            }
+            return super().render(materialized, accepted_media_type, renderer_context)
+
+        parts: list[bytes] = [b"{"]
+        for i, (k, v) in enumerate(data.items()):
+            if i > 0:
+                parts.append(b",")
+            # json.dumps handles quote/backslash/control-char escaping in keys
+            # so a user dict with `{'a"b': ...}` still produces valid JSON.
+            parts.append(json.dumps(k, ensure_ascii=self.ensure_ascii).encode("utf-8"))
+            parts.append(b":")
+            if isinstance(v, FastPayload):
+                parts.append(v.adapter.dump_json(v.instances))
+            else:
+                parts.append(
+                    json.dumps(
+                        v,
+                        cls=self.encoder_class,
+                        ensure_ascii=self.ensure_ascii,
+                        allow_nan=not self.strict,
+                        separators=(",", ":"),
+                    ).encode("utf-8")
+                )
+        parts.append(b"}")
+        return b"".join(parts)

tests/test_renderer.py

@@ -42,3 +42,100 @@ def test_renderer_single_instance(txn_dict: dict):
     parsed = json.loads(raw)
     assert parsed["id"] == 1
     assert parsed["flags"]["is_refund"] is True
+
+
+# Composed envelope tests --------------------------------------------------
+
+
+def test_renderer_composes_mixed_dict(txn_dict: dict):
+    """Bundle-style response: multiple FastPayloads + plain values in one dict."""
+    payload = {
+        "header": TxnOut.drf(instance=txn_dict).data,
+        "items": TxnOut.drf(instance=[txn_dict, {**txn_dict, "id": 2}], many=True).data,
+        "meta": {"page": 1, "total": 2},
+    }
+    raw = FastJSONRenderer().render(payload)
+    parsed = json.loads(raw)
+    assert parsed["header"]["id"] == 1
+    assert [r["id"] for r in parsed["items"]] == [1, 2]
+    assert parsed["meta"] == {"page": 1, "total": 2}
+
+
+def test_renderer_composed_all_fastpayloads(txn_dict: dict):
+    """Envelope with no plain values: every key is a FastPayload."""
+    payload = {
+        "a": TxnOut.drf(instance=txn_dict).data,
+        "b": TxnOut.drf(instance={**txn_dict, "id": 99}).data,
+    }
+    raw = FastJSONRenderer().render(payload)
+    parsed = json.loads(raw)
+    assert parsed["a"]["id"] == 1
+    assert parsed["b"]["id"] == 99
+
+
+def test_renderer_composed_preserves_key_order(txn_dict: dict):
+    """Output key order matches input insertion order."""
+    payload = {
+        "z": {"plain": 1},
+        "a": TxnOut.drf(instance=txn_dict).data,
+        "m": {"plain": 2},
+        "b": TxnOut.drf(instance={**txn_dict, "id": 9}).data,
+    }
+    raw = FastJSONRenderer().render(payload)
+    # Walk the bytes for ordering; json.loads on a plain dict would
+    # preserve order in 3.7+ but checking the raw stream is unambiguous.
+    assert raw.index(b'"z"') < raw.index(b'"a"') < raw.index(b'"m"') < raw.index(b'"b"')
+
+
+def test_renderer_composed_handles_special_chars_in_keys(txn_dict: dict):
+    """Keys containing `"` or `\\` must still produce valid JSON."""
+    payload = {
+        'has"quote': TxnOut.drf(instance=txn_dict).data,
+        "back\\slash": {"ok": True},
+    }
+    raw = FastJSONRenderer().render(payload)
+    parsed = json.loads(raw)
+    assert parsed['has"quote']["id"] == 1
+    assert parsed["back\\slash"] == {"ok": True}
+
+
+def test_renderer_composed_pagination_envelope(txn_dicts: list[dict]):
+    """Pagination shape ({count, next, previous, results: FastPayload}) is
+    handled by the composed path — no special-case code needed."""
+    payload = {
+        "count": 100,
+        "next": "http://example.com/?page=2",
+        "previous": None,
+        "results": TxnOut.drf(instance=txn_dicts, many=True).data,
+    }
+    raw = FastJSONRenderer().render(payload)
+    parsed = json.loads(raw)
+    assert parsed["count"] == 100
+    assert parsed["next"] == "http://example.com/?page=2"
+    assert parsed["previous"] is None
+    assert [r["id"] for r in parsed["results"]] == [d["id"] for d in txn_dicts]
+
+
+def test_renderer_composed_indented_falls_back_to_materialization(txn_dict: dict):
+    """indent=2 → Rust dump_json can't pretty-print; materialize all FastPayloads."""
+    payload = {
+        "header": TxnOut.drf(instance=txn_dict).data,
+        "meta": {"page": 1},
+    }
+    raw = FastJSONRenderer().render(
+        payload,
+        accepted_media_type="application/json",
+        renderer_context={"indent": 2},
+    )
+    parsed = json.loads(raw)
+    assert parsed["header"]["id"] == 1
+    assert parsed["meta"] == {"page": 1}
+    # Indented output has newlines and spaces; the compact-path splice does not.
+    assert b"\n" in raw or b": " in raw
+
+
+def test_renderer_error_envelope_passes_through():
+    """A plain error dict (no FastPayload values) should not trigger composed path."""
+    raw = FastJSONRenderer().render({"detail": "not found", "code": 404})
+    parsed = json.loads(raw)
+    assert parsed == {"detail": "not found", "code": 404}