Allow `JSONEncoder` to return bytes directly #11989

kevinpark1217 · 2026-01-23T20:50:20Z

Update JSONEncoder type to accept callables that return either str or bytes.
This allows custom JSON serializers that directly produce bytes to be used
without unnecessary decode/encode cycles.

Changes

Updated JSONEncoder type in typedefs.py to Callable[[Any], str | bytes]
Modified JsonPayload to handle both str and bytes from dumps()
Updated json_response to route bytes to body parameter, str to text
Updated WebSocketResponse.send_json to call send_bytes for bytes, send_str for str
Updated ClientWebSocketResponse.send_json with same logic

Testing

All modified files compile successfully
Code formatting validated with black
Import ordering validated with isort
Functional tests verified both str-returning and bytes-returning encoders work correctly

Backward Compatibility

This maintains full backward compatibility with existing code using json.dumps
while enabling more efficient custom serializers.

Fixes #11988

Update JSONEncoder type to accept callables that return either str or bytes. This allows custom JSON serializers that directly produce bytes to be used without unnecessary decode/encode cycles. Changes: - Updated JSONEncoder type in typedefs.py to Callable[[Any], str | bytes] - Modified JsonPayload to handle both str and bytes from dumps() - Updated json_response to route bytes to body parameter, str to text - Updated WebSocketResponse.send_json to call send_bytes for bytes, send_str for str - Updated ClientWebSocketResponse.send_json with same logic This maintains full backward compatibility with existing code using json.dumps while enabling more efficient custom serializers. Fixes aio-libs#11988

codspeed-hq · 2026-01-23T21:03:27Z

Merging this PR will not alter performance

✅ 59 untouched benchmarks

_{Comparing kevinpark1217:allow-jsonencoder-return-bytes (d221fc0) with master (95674df)¹}

No successful run was found on master (7b4db6f) during the generation of this report, so 95674df was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

codecov · 2026-01-23T21:03:55Z

Codecov Report

❌ Patch coverage is 56.25000% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.74%. Comparing base (95674df) to head (d221fc0).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
aiohttp/client_ws.py	50.00%	1 Missing and 1 partial ⚠️
aiohttp/web_response.py	50.00%	1 Missing and 1 partial ⚠️
aiohttp/web_ws.py	50.00%	1 Missing and 1 partial ⚠️
aiohttp/payload.py	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #11989      +/-   ##
==========================================
- Coverage   98.75%   98.74%   -0.01%     
==========================================
  Files         127      127              
  Lines       44655    44667      +12     
  Branches     2367     2371       +4     
==========================================
+ Hits        44098    44106       +8     
  Misses        396      396              
- Partials      161      165       +4

Flag	Coverage Δ
CI-GHA	`98.60% <56.25%> (-0.01%)`	⬇️
OS-Linux	`98.34% <56.25%> (-0.01%)`	⬇️
OS-Windows	`96.69% <56.25%> (-0.02%)`	⬇️
OS-macOS	`97.57% <56.25%> (-0.03%)`	⬇️
Py-3.10.11	`97.12% <56.25%> (-0.02%)`	⬇️
Py-3.10.19	`97.60% <56.25%> (-0.02%)`	⬇️
Py-3.11.14	`97.81% <56.25%> (-0.02%)`	⬇️
Py-3.11.9	`97.33% <56.25%> (-0.02%)`	⬇️
Py-3.12.10	`97.42% <56.25%> (-0.02%)`	⬇️
Py-3.12.12	`97.90% <56.25%> (-0.02%)`	⬇️
Py-3.13.11	`98.15% <56.25%> (-0.02%)`	⬇️
Py-3.14.2	`98.13% <56.25%> (-0.02%)`	⬇️
Py-3.14.2t	`97.22% <56.25%> (-0.01%)`	⬇️
Py-pypy3.11.13-7.3.20	`97.37% <56.25%> (-0.02%)`	⬇️
VM-macos	`97.57% <56.25%> (-0.03%)`	⬇️
VM-ubuntu	`98.34% <56.25%> (-0.01%)`	⬇️
VM-windows	`96.69% <56.25%> (-0.02%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Dreamsorcerer · 2026-01-23T23:02:11Z

@bdraco Do the benchmarks already cover these cases?

webknjaz · 2026-01-23T23:28:06Z

IIRC, there was a similar request years ago, rejected.

webknjaz · 2026-01-23T23:33:13Z

I think it was #4482

webknjaz

No tests? How do we know this keeps working?

webknjaz · 2026-01-23T23:35:19Z

aiohttp/client_ws.py

        dumps: JSONEncoder = DEFAULT_JSON_ENCODER,
    ) -> None:
-        await self.send_str(dumps(data), compress=compress)
+        result = dumps(data)


Can we plz not use meaningless var names?

webknjaz · 2026-01-23T23:42:04Z

CHANGES/11989.feature.rst

@@ -0,0 +1,4 @@
+Updated the ``JSONEncoder`` type to accept callables returning either ``str`` or ``bytes``.


Suggested change

Updated the ``JSONEncoder`` type to accept callables returning either ``str`` or ``bytes``.

Updated the ``JSONEncoder`` type to accept callables returning either :data:`str` or :data:`bytes`.

webknjaz · 2026-01-23T23:42:42Z

CHANGES/11989.feature.rst

@@ -0,0 +1,4 @@
+Updated the ``JSONEncoder`` type to accept callables returning either ``str`` or ``bytes``.
+This allows a custom JSON serializer that directly produces bytes to be used with
+``ClientSession.json_serialize``, ``JsonPayload``, ``json_response``, and websocket


These should probably be properly linked using appropriate RST roles.

Dreamsorcerer · 2026-01-24T01:58:56Z

IIRC, there was a similar request years ago, rejected.

With ujson dead, I think we're ready to change this: #10795 (comment)

My only question is whether the isinstance() calls here are fine, or we should add a new parameter and avoid the isinstance() checks. I suspect this is one of the performance hot paths for some cases (like websockets on homeassistant?).

webknjaz · 2026-01-25T19:34:18Z

Ah, fair. I also had a feeling that I'd prefer having a new API rather than overloading the existing one..

bdraco · 2026-01-25T21:16:00Z

Thanks for working on this! The use case makes sense.

I agree with webknjaz about preferring a new API over isinstance(). A few concerns:

isinstance() in the hot path. Minor, but runtime overhead on every call when the encoder type is fixed for the session lifetime.
WebSocket frame type changes silently. With a bytes encoder, send_json() now calls send_bytes() (binary frame) instead of send_str() (text frame). JSON is text, so this could break clients expectng text frames.
Harder to reason about. Union return types that branch at runtime are messier long-term.

Alternative: Add explicit parallel methods like JsonBytesPayload, json_bytes_response(), send_json_bytes(), and json_serialize_bytes param on ClientSession. No isinstance checks, clear contracts, existing code untouched.

kevinpark1217 requested a review from asvetlov as a code owner January 23, 2026 20:50

Add changelog entry for JSONEncoder bytes support

e5e0370

kevinpark1217 requested a review from webknjaz as a code owner January 23, 2026 20:56

psf-chronographer bot added the bot:chronographer:provided There is a change note present in this PR label Jan 23, 2026

Fix spelling in changelog entry

d221fc0

kevinpark1217 changed the title ~~Allow JSONEncoder to return bytes directly~~ Allow JSONEncoder to return bytes directly Jan 23, 2026

kevinpark1217 mentioned this pull request Jan 23, 2026

ujson library mentioned in the documentation is deprecated #10795

Open

1 task

webknjaz reviewed Jan 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Allow `JSONEncoder` to return bytes directly #11989

Allow `JSONEncoder` to return bytes directly #11989

kevinpark1217 commented Jan 23, 2026

Uh oh!

codspeed-hq bot commented Jan 23, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 23, 2026 •

edited

Loading

Uh oh!

Dreamsorcerer commented Jan 23, 2026

Uh oh!

webknjaz commented Jan 23, 2026

Uh oh!

webknjaz commented Jan 23, 2026

Uh oh!

webknjaz left a comment

Uh oh!

webknjaz Jan 23, 2026

Uh oh!

webknjaz Jan 23, 2026

Uh oh!

webknjaz Jan 23, 2026

Uh oh!

Dreamsorcerer commented Jan 24, 2026

Uh oh!

webknjaz commented Jan 25, 2026 •

edited

Loading

Uh oh!

bdraco commented Jan 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		@@ -0,0 +1,4 @@
		Updated the ``JSONEncoder`` type to accept callables returning either ``str`` or ``bytes``.

Uh oh!

Allow JSONEncoder to return bytes directly #11989

Are you sure you want to change the base?

Allow JSONEncoder to return bytes directly #11989

Conversation

kevinpark1217 commented Jan 23, 2026

Changes

Testing

Backward Compatibility

Uh oh!

codspeed-hq bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

codecov bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Dreamsorcerer commented Jan 23, 2026

Uh oh!

webknjaz commented Jan 23, 2026

Uh oh!

webknjaz commented Jan 23, 2026

Uh oh!

webknjaz left a comment

Choose a reason for hiding this comment

Uh oh!

webknjaz Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

webknjaz Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

webknjaz Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Dreamsorcerer commented Jan 24, 2026

Uh oh!

webknjaz commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bdraco commented Jan 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Allow `JSONEncoder` to return bytes directly #11989

Allow `JSONEncoder` to return bytes directly #11989

codspeed-hq bot commented Jan 23, 2026 •

edited

Loading

codecov bot commented Jan 23, 2026 •

edited

Loading

webknjaz commented Jan 25, 2026 •

edited

Loading