Allow JSONEncoder to return bytes directly (#11989) (#12115)

Dreamsorcerer · kevinpark1217 · web-flow · commit f82bc8aad2f1 · 2026-02-22T12:53:37.000Z
(cherry picked from commit 67fa1f5) --------- Co-authored-by: Kevin Park <kevin.park1217@gmail.com>
diff --git a/CHANGES/11989.feature.rst b/CHANGES/11989.feature.rst
@@ -0,0 +1,7 @@
+Added explicit APIs for bytes-returning JSON serializer:
+``JSONBytesEncoder`` type, ``JsonBytesPayload``,
+:func:`~aiohttp.web.json_bytes_response`,
+:meth:`~aiohttp.web.WebSocketResponse.send_json_bytes` and
+:meth:`~aiohttp.ClientWebSocketResponse.send_json_bytes` methods, and
+``json_serialize_bytes`` parameter for :class:`~aiohttp.ClientSession`
+-- by :user:`kevinpark1217`.
diff --git a/aiohttp/client.py b/aiohttp/client.py
@@ -104,7 +104,14 @@
 from .http import WS_KEY, HttpVersion, WebSocketReader, WebSocketWriter
 from .http_websocket import WSHandshakeError, ws_ext_gen, ws_ext_parse
 from .tracing import Trace, TraceConfig
-from .typedefs import JSONEncoder, LooseCookies, LooseHeaders, Query, StrOrURL
+from .typedefs import (
+    JSONBytesEncoder,
+    JSONEncoder,
+    LooseCookies,
+    LooseHeaders,
+    Query,
+    StrOrURL,
+)
 
 __all__ = (
     # client_exceptions
@@ -271,6 +278,7 @@ class ClientSession:
             "_default_auth",
             "_version",
             "_json_serialize",
+            "_json_serialize_bytes",
             "_requote_redirect_url",
             "_timeout",
             "_raise_for_status",
@@ -311,6 +319,7 @@ def __init__(
         skip_auto_headers: Iterable[str] | None = None,
         auth: BasicAuth | None = None,
         json_serialize: JSONEncoder = json.dumps,
+        json_serialize_bytes: JSONBytesEncoder | None = None,
         request_class: type[ClientRequest] = ClientRequest,
         response_class: type[ClientResponse] = ClientResponse,
         ws_response_class: type[ClientWebSocketResponse] = ClientWebSocketResponse,
@@ -421,6 +430,7 @@ def __init__(
         self._default_auth = auth
         self._version = version
         self._json_serialize = json_serialize
+        self._json_serialize_bytes = json_serialize_bytes
         self._raise_for_status = raise_for_status
         self._auto_decompress = auto_decompress
         self._trust_env = trust_env
@@ -561,7 +571,10 @@ async def _request(
                 "data and json parameters can not be used at the same time"
             )
         elif json is not None:
-            data = payload.JsonPayload(json, dumps=self._json_serialize)
+            if self._json_serialize_bytes is not None:
+                data = payload.JsonBytesPayload(json, dumps=self._json_serialize_bytes)
+            else:
+                data = payload.JsonPayload(json, dumps=self._json_serialize)
 
         if not isinstance(chunked, bool) and chunked is not None:
             warnings.warn("Chunk size is deprecated #1615", DeprecationWarning)
diff --git a/aiohttp/client_ws.py b/aiohttp/client_ws.py
@@ -27,6 +27,7 @@
 from .typedefs import (
     DEFAULT_JSON_DECODER,
     DEFAULT_JSON_ENCODER,
+    JSONBytesEncoder,
     JSONDecoder,
     JSONEncoder,
 )
@@ -303,6 +304,20 @@ async def send_json(
     ) -> None:
         await self.send_str(dumps(data), compress=compress)
 
+    async def send_json_bytes(
+        self,
+        data: Any,
+        compress: int | None = None,
+        *,
+        dumps: JSONBytesEncoder,
+    ) -> None:
+        """Send JSON data using a bytes-returning encoder as a binary frame.
+
+        Use this when your JSON encoder (like orjson) returns bytes
+        instead of str, avoiding the encode/decode overhead.
+        """
+        await self.send_bytes(dumps(data), compress=compress)
+
     async def close(self, *, code: int = WSCloseCode.OK, message: bytes = b"") -> bool:
         # we need to break `receive()` cycle first,
         # `close()` may be called from different task
diff --git a/aiohttp/payload.py b/aiohttp/payload.py
@@ -23,7 +23,7 @@
     sentinel,
 )
 from .streams import StreamReader
-from .typedefs import JSONEncoder, _CIMultiDict
+from .typedefs import JSONBytesEncoder, JSONEncoder, _CIMultiDict
 
 __all__ = (
     "PAYLOAD_REGISTRY",
@@ -38,6 +38,7 @@
     "TextIOPayload",
     "StringIOPayload",
     "JsonPayload",
+    "JsonBytesPayload",
     "AsyncIterablePayload",
 )
 
@@ -943,6 +944,29 @@ def __init__(
         )
 
 
+class JsonBytesPayload(BytesPayload):
+    """JSON payload for encoders that return bytes directly.
+
+    Use this when your JSON encoder (like orjson) returns bytes
+    instead of str, avoiding the encode/decode overhead.
+    """
+
+    def __init__(
+        self,
+        value: Any,
+        dumps: JSONBytesEncoder,
+        content_type: str = "application/json",
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            dumps(value),
+            content_type=content_type,
+            *args,
+            **kwargs,
+        )
+
+
 if TYPE_CHECKING:
     from collections.abc import AsyncIterable, AsyncIterator
 
diff --git a/aiohttp/typedefs.py b/aiohttp/typedefs.py
@@ -27,6 +27,7 @@
 
 Byteish = Union[bytes, bytearray, memoryview]
 JSONEncoder = Callable[[Any], str]
+JSONBytesEncoder = Callable[[Any], bytes]
 JSONDecoder = Callable[[str], Any]
 LooseHeaders = Union[
     Mapping[str, str],
diff --git a/aiohttp/web.py b/aiohttp/web.py
@@ -96,6 +96,7 @@
     ContentCoding as ContentCoding,
     Response as Response,
     StreamResponse as StreamResponse,
+    json_bytes_response as json_bytes_response,
     json_response as json_response,
 )
 from .web_routedef import (
@@ -228,6 +229,7 @@
     "ContentCoding",
     "Response",
     "StreamResponse",
+    "json_bytes_response",
     "json_response",
     "ResponseKey",
     # web_routedef
diff --git a/aiohttp/web_response.py b/aiohttp/web_response.py
@@ -32,12 +32,18 @@
 )
 from .http import SERVER_SOFTWARE, HttpVersion10, HttpVersion11
 from .payload import Payload
-from .typedefs import JSONEncoder, LooseHeaders
+from .typedefs import JSONBytesEncoder, JSONEncoder, LooseHeaders
 
 REASON_PHRASES = {http_status.value: http_status.phrase for http_status in HTTPStatus}
 LARGE_BODY_SIZE = 1024**2
 
-__all__ = ("ContentCoding", "StreamResponse", "Response", "json_response")
+__all__ = (
+    "ContentCoding",
+    "StreamResponse",
+    "Response",
+    "json_response",
+    "json_bytes_response",
+)
 
 
 if TYPE_CHECKING:
@@ -878,3 +884,32 @@ def json_response(
         headers=headers,
         content_type=content_type,
     )
+
+
+def json_bytes_response(
+    data: Any = sentinel,
+    *,
+    dumps: JSONBytesEncoder,
+    body: bytes | None = None,
+    status: int = 200,
+    reason: str | None = None,
+    headers: LooseHeaders | None = None,
+    content_type: str = "application/json",
+) -> Response:
+    """Create a JSON response using a bytes-returning encoder.
+
+    Use this when your JSON encoder (like orjson) returns bytes
+    instead of str, avoiding the encode/decode overhead.
+    """
+    if data is not sentinel:
+        if body is not None:
+            raise ValueError("only one of data or body should be specified")
+        else:
+            body = dumps(data)
+    return Response(
+        body=body,
+        status=status,
+        reason=reason,
+        headers=headers,
+        content_type=content_type,
+    )
diff --git a/aiohttp/web_ws.py b/aiohttp/web_ws.py
@@ -34,7 +34,7 @@
 from .http_websocket import _INTERNAL_RECEIVE_TYPES
 from .log import ws_logger
 from .streams import EofStream
-from .typedefs import JSONDecoder, JSONEncoder
+from .typedefs import JSONBytesEncoder, JSONDecoder, JSONEncoder
 from .web_exceptions import HTTPBadRequest, HTTPException
 from .web_request import BaseRequest
 from .web_response import StreamResponse
@@ -481,6 +481,20 @@ async def send_json(
     ) -> None:
         await self.send_str(dumps(data), compress=compress)
 
+    async def send_json_bytes(
+        self,
+        data: Any,
+        compress: int | None = None,
+        *,
+        dumps: JSONBytesEncoder,
+    ) -> None:
+        """Send JSON data using a bytes-returning encoder as a binary frame.
+
+        Use this when your JSON encoder (like orjson) returns bytes
+        instead of str, avoiding the encode/decode overhead.
+        """
+        await self.send_bytes(dumps(data), compress=compress)
+
     async def write_eof(self) -> None:  # type: ignore[override]
         if self._eof_sent:
             return
diff --git a/docs/client_reference.rst b/docs/client_reference.rst
@@ -1850,6 +1850,28 @@ manually.
          The method is converted into :term:`coroutine`,
          *compress* parameter added.
 
+   .. method:: send_json_bytes(data, compress=None, *, dumps)
+      :async:
+
+      Send *data* to peer as a JSON binary frame using a bytes-returning encoder.
+
+      :param data: data to send.
+
+      :param int compress: sets specific level of compression for
+                           single message,
+                           ``None`` for not overriding per-socket setting.
+
+      :param collections.abc.Callable dumps: any :term:`callable` that accepts an object and
+                             returns JSON as :class:`bytes`
+                             (e.g. ``orjson.dumps``).
+
+      :raise RuntimeError: if connection is not started or closing
+
+      :raise ValueError: if data is not serializable object
+
+      :raise TypeError: if value returned by ``dumps(data)`` is not
+                        :class:`bytes`
+
    .. method:: send_frame(message, opcode, compress=None)
       :async:
 
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
@@ -227,6 +227,7 @@ nowait
 OAuth
 Online
 optimizations
+orjson
 os
 outcoming
 Overridable
diff --git a/docs/web_reference.rst b/docs/web_reference.rst
@@ -1232,6 +1232,27 @@ and :ref:`aiohttp-web-signals` handlers::
          The method is converted into :term:`coroutine`,
          *compress* parameter added.
 
+   .. method:: send_json_bytes(data, compress=None, *, dumps)
+      :async:
+
+      Send *data* to peer as a JSON binary frame using a bytes-returning encoder.
+
+      :param data: data to send.
+
+      :param int compress: sets specific level of compression for
+                           single message,
+                           ``None`` for not overriding per-socket setting.
+
+      :param collections.abc.Callable dumps: any :term:`callable` that accepts an object and
+                             returns JSON as :class:`bytes`
+                             (e.g. ``orjson.dumps``).
+
+      :raise RuntimeError: if the connection is not started.
+
+      :raise ValueError: if data is not serializable object
+
+      :raise TypeError: if value returned by ``dumps`` param is not :class:`bytes`
+
    .. method:: send_frame(message, opcode, compress=None)
       :async:
 
@@ -1445,6 +1466,18 @@ the handler.
       :class:`Response` initializer.
 
 
+.. function:: json_bytes_response([data], *, dumps, body=None, \
+                                  status=200, reason=None, headers=None, \
+                                  content_type='application/json')
+
+Return :class:`Response` with predefined ``'application/json'``
+content type and *data* encoded by ``dumps`` parameter
+which must return :class:`bytes` directly (e.g. ``orjson.dumps``).
+
+Use this when your JSON encoder returns :class:`bytes` instead of :class:`str`,
+avoiding the :class:`str`-to-:class:`bytes` encoding overhead.
+
+
 .. class:: ResponseKey(name, t)
 
    Keys for use in :class:`Response`.
diff --git a/tests/test_client_functional.py b/tests/test_client_functional.py
@@ -2244,7 +2244,28 @@ def dumps(obj):
         await client.post("/", data="some data", json={"some": "data"})
 
 
-async def test_expect_continue(aiohttp_client) -> None:
+async def test_json_serialize_bytes(aiohttp_client: AiohttpClient) -> None:
+    """Test ClientSession.json_serialize_bytes with bytes-returning encoder."""
+
+    async def handler(request: web.Request) -> web.Response:
+        assert request.content_type == "application/json"
+        data = await request.json()
+        return web.Response(body=aiohttp.JsonPayload(data))
+
+    json_bytes_encoder = mock.Mock(side_effect=lambda x: json.dumps(x).encode("utf-8"))
+
+    app = web.Application()
+    app.router.add_post("/", handler)
+    client = await aiohttp_client(app, json_serialize_bytes=json_bytes_encoder)
+
+    async with client.post("/", json={"some": "data"}) as resp:
+        assert resp.status == 200
+        assert json_bytes_encoder.called
+        content = await resp.json()
+    assert content == {"some": "data"}
+
+
+async def test_expect_continue(aiohttp_client: AiohttpClient) -> None:
     expect_called = False
 
     async def handler(request):
diff --git a/tests/test_client_ws_functional.py b/tests/test_client_ws_functional.py
diff --git a/tests/test_payload.py b/tests/test_payload.py
diff --git a/tests/test_web_response.py b/tests/test_web_response.py
diff --git a/tests/test_web_websocket.py b/tests/test_web_websocket.py
