Abstract the public-facing API away from ClientResponse by Moist-Cat · Pull Request #13152 · aio-libs/aiohttp

Moist-Cat · 2026-07-16T03:52:10Z

It's important to notice that the __init__ method varies between implementations and there are some extra fields (e.g, the _in_context field) that are required by some methods used outside the class.
The base class is basically an interface that implements the public API. Fields can't be stored in the base class because they may or may not be available during __init__ so I'm thinking of removing the constructor altogether.

Related issues

#11743

Related PR

#13039

It's important to notice that the __init__ method varies between implementations and there are some leftovers (e.g, the _in_context field). The base class is basically an interface.

for more information, see https://pre-commit.ci

codspeed-hq · 2026-07-16T04:04:21Z

Merging this PR will not alter performance

✅ 84 untouched benchmarks
⏩ 83 skipped benchmarks¹

_{Comparing Moist-Cat:response-refactor (6511797) with master (d5d068c)²}

83 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
No successful run was found on master (c0ef574) during the generation of this report, so d5d068c was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

The CI complained but unit tests did not fail.

codecov · 2026-07-16T05:13:33Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.95%. Comparing base (d5d068c) to head (6511797).
⚠️ Report is 3 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #13152      +/-   ##
==========================================
- Coverage   98.98%   98.95%   -0.04%     
==========================================
  Files         132      133       +1     
  Lines       49073    49113      +40     
  Branches     2553     2552       -1     
==========================================
+ Hits        48576    48598      +22     
- Misses        373      391      +18     
  Partials      124      124

Flag	Coverage Δ
Autobahn	`22.18% <57.01%> (+0.05%)`	⬆️
CI-GHA	`98.86% <100.00%> (-0.04%)`	⬇️
OS-Linux	`98.64% <100.00%> (-0.04%)`	⬇️
OS-Windows	`96.99% <100.00%> (-0.04%)`	⬇️
OS-macOS	`97.89% <100.00%> (-0.04%)`	⬇️
Py-3.10	`98.08% <100.00%> (-0.04%)`	⬇️
Py-3.11	`98.34% <100.00%> (-0.03%)`	⬇️
Py-3.12	`98.43% <100.00%> (-0.04%)`	⬇️
Py-3.13	`98.41% <100.00%> (-0.04%)`	⬇️
Py-3.14	`98.43% <100.00%> (-0.04%)`	⬇️
Py-3.14t	`97.52% <100.00%> (-0.04%)`	⬇️
Py-pypy-3.11	`97.36% <100.00%> (-0.04%)`	⬇️
VM-macos	`97.89% <100.00%> (-0.04%)`	⬇️
VM-ubuntu	`98.64% <100.00%> (-0.04%)`	⬇️
VM-windows	`96.99% <100.00%> (-0.04%)`	⬇️
cython-coverage	`37.97% <80.99%> (+0.01%)`	⬆️

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

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

Dreamsorcerer · 2026-07-18T23:18:07Z

+import contextlib
+import json
+from http.cookies import SimpleCookie
+from typing import Any, Callable, Optional, Tuple


Callable, Optional, and Tuple are all deprecated.

Optional doesn't seem deprecated. Still, I will use [type] | None to be consistent with the rest of the code.

Dreamsorcerer · 2026-07-18T23:20:52Z

+        self._in_context = False
+        self._released: bool = False
+        self._resolve_charset: Callable[[Any, bytes], str] = lambda *_: "utf-8"


The subclass doesn't call this. These could just be class defaults anyway, so don't need the init to define them.

Dreamsorcerer · 2026-07-18T23:22:33Z

+        self._resolve_charset: Callable[[Any, bytes], str] = lambda *_: "utf-8"
+
+    # ----------------------------------------------------------------
+    # Abstract / overridable protocol methods


We probably want to ensure these are defined, right? In which case this should probably be an abstract class and these methods can all be defined as abstract.

This requires multiple inheritance (HeadersMixin, ABC), but alright.

Dreamsorcerer · 2026-07-18T23:23:36Z

+    def headers(self) -> Any:
+        return self._headers
+
+    @property
+    def history(self) -> Tuple[Any, ...]:


Seem to have lost typing information that we had before?

Changing it to tuple["BaseResponse", ...] breaks static analysis for functions that expect tuple["ClientResponse", ...]. In particular, ClientResponseError. I would rather be conservative and use Any than to change too many files and risk conflicts/rollbacks.
I ended up updating all references, in any case.

Dreamsorcerer · 2026-07-18T23:30:50Z



-class ClientResponse(HeadersMixin):
+class ClientResponse(BaseResponse):


So this is the HTTP/1 class, right?

I still think, atleast in master/v4, that we probably want to rename this and have the base class be called ClientResponse. That means that middlewares etc. which reference ClientResponse shouldn't need any changes to work in future with the HTTP/2 class.

With these current changes, we'd need to changes lots of references from ClientResponse -> BaseResponse, both in our code and in user's code.

I still think, atleast in master/v4, that we probably want to rename this and have the base class be called ClientResponse

This causes type errors as well because we are reducing the capabilities of the ClientResponse class. All the methods that use the response as a connector object via start, read, etc, stop working. Though, reviewing the type errors, it seems that most come from the tests. I'm not sure if any users or middlewares use these methods.
That said, I'm okay with switching the child class with the new parent class if you believe it's better for backwards compatibility.

Yeah, but that's the HTTP/1 specific methods, right? Any code that currently requires them is going to break regardless, as anything that currently receives ClientResponse, will in future need to handle receiving both HTTP1 and HTTP2 classes.

Code which doesn't depend on those methods will need no updates to annotations etc. if the base class reuses the existing ClientResponse name. So, yeah, I think it's a much easier migration for users if the parent is ClientResponse.

Yeah, but that's the HTTP/1 specific methods, right? Any code that currently requires them is going to break regardless, as anything that currently receives ClientResponse, will in future need to handle receiving both HTTP1 and HTTP2 classes.

Yes, that's true.

Code which doesn't depend on those methods will need no updates to annotations etc. if the base class reuses the existing ClientResponse name. So, yeah, I think it's a much easier migration for users if the parent is ClientResponse.

That makes sense to me.

Moist-Cat · 2026-07-28T02:13:21Z

The main problem is that the code does not differentiate when the request object is used as a data structure and when it's used as a connector object that holds the current state of the connection. After finding more examples of this mixed behaviour it appears to me at the present that it would be difficult to implement HTTP/3 after HTTP/2 without adding a considerable code debt. Refactoring the response class to match the architecture I have in mind will require several small, incremental steps to avoid major breaking changes but it's better than a patchwork.

If you agree, I believe the best course of action would be to try to add HTTP/2 as an experimental feature after we finish with this and keep making small changes until we can support the three major HTTP versions without hacks or unexpected behaviour. The reason of why I think it's better to implement HTTP/2 first is to improve over something that works rather than changing the architecture without having a concrete implementation. Pushing the changes to a temporary developing branch first until the code is refactored is an option too but I'm not sure of how long will it take or if a clean solution is possible without major breaking changes and pushing many complex changes at once is never a good idea.

for more information, see https://pre-commit.ci

Dreamsorcerer · 2026-07-28T13:09:27Z

If you agree, I believe the best course of action would be to try to add HTTP/2 as an experimental feature after we finish with this and keep making small changes until we can support the three major HTTP versions without hacks or unexpected behaviour. The reason of why I think it's better to implement HTTP/2 first is to improve over something that works rather than changing the architecture without having a concrete implementation. Pushing the changes to a temporary developing branch first until the code is refactored is an option too but I'm not sure of how long will it take or if a clean solution is possible without major breaking changes and pushing many complex changes at once is never a good idea.

OK, how about you start preparing these changes as a stacked PR? I'll ask for us to be opted-in to the stacked PRs beta, then you can create it.

That way you can show the full implementation, and we can merge the iterative steps as we go.

Moist-Cat · 2026-07-28T14:56:34Z

OK, how about you start preparing these changes as a stacked PR? I'll ask for us to be opted-in to the stacked PRs beta, then you can create it.

That way you can show the full implementation, and we can merge the iterative steps as we go.

Oh, this is the first time I hear about stacked PRs. Yes, that's perfect.

I will need some time to study the codebase and design an architecture that can accommodate the three protocols and doesn't break the public API so I will be switching between refactoring, and adapting the HTTP/2 and HTTP/1.1 implementations to the unified interface. If everything goes well, I might implement a minimal HTTP/3 connector while I'm at it (disabled, of course).

Dreamsorcerer · 2026-07-28T15:41:42Z

I've just been told they have a lot of requests for the beta already, so not sure if we'll get added or not. Will update you if I hear back.

Dreamsorcerer · 2026-07-30T19:29:18Z

Whether due to my pestering or not, stacked PRs are now in public preview, so we can use them.

So, feel free to create a stacked PR. One thing to include in the full PR would be separate HTTP/2 codspeed benchmarks, so we can compare the performance between the HTTP/1 and HTTP/2 stacks.

HTTPResponse is the old ClientRequest that mixed presentation with connection handling. In the case of the tests, HTTPResponse was aliased to avoid conflicts.

Moist-Cat and others added 2 commits July 15, 2026 23:39

Abstract user-facing public API for ClientResponse

7f3661c

It's important to notice that the __init__ method varies between implementations and there are some leftovers (e.g, the _in_context field). The base class is basically an interface.

[pre-commit.ci] auto fixes from pre-commit.com hooks

0dc257e

for more information, see https://pre-commit.ci

github-advanced-security AI found potential problems Jul 16, 2026

View reviewed changes

Comment thread aiohttp/http_base.py Fixed

Comment thread aiohttp/http_base.py Fixed

Comment thread aiohttp/http_base.py Fixed

Comment thread aiohttp/http_base.py Fixed

Comment thread aiohttp/http_base.py Fixed

Moist-Cat changed the title ~~Abstract user-facing public API for ClientResponse~~ Abstract the public-facing API away from ClientResponse Jul 16, 2026

Moist-Cat added 4 commits July 16, 2026 00:12

Add missing branch

a2e1af5

Fix style issues

c57315d

Remove slots

d7a96d7

Remove mysterious import cycle

b8da07b

The CI complained but unit tests did not fail.

Moist-Cat marked this pull request as ready for review July 16, 2026 04:46

Moist-Cat requested a review from asvetlov as a code owner July 16, 2026 04:46

Merge branch 'aio-libs:master' into response-refactor

423b102

Dreamsorcerer reviewed Jul 18, 2026

View reviewed changes

Merge branch 'master' into response-refactor

340d78b

Moist-Cat and others added 3 commits July 27, 2026 22:26

Fix types

42a9f4b

[pre-commit.ci] auto fixes from pre-commit.com hooks

ce2e5b3

for more information, see https://pre-commit.ci

Merge branch 'aio-libs:master' into response-refactor

89e2294

Moist-Cat and others added 2 commits August 3, 2026 11:48

Merge branch 'aio-libs:master' into response-refactor

8f77097

Replace the new ClientRequest with HTTPResponse

6511797

HTTPResponse is the old ClientRequest that mixed presentation with connection handling. In the case of the tests, HTTPResponse was aliased to avoid conflicts.



		class ClientResponse(HeadersMixin):
		class ClientResponse(BaseResponse):

Uh oh!

Uh oh!

Conversation

Moist-Cat commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issues

Related PR

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codspeed-hq Bot commented Jul 16, 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 Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Moist-Cat Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Moist-Cat Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Moist-Cat Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Moist-Cat commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Dreamsorcerer commented Jul 28, 2026

Uh oh!

Moist-Cat commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Dreamsorcerer commented Jul 28, 2026

Uh oh!

Dreamsorcerer commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Moist-Cat commented Jul 16, 2026 •

edited

Loading

codspeed-hq Bot commented Jul 16, 2026 •

edited

Loading

codecov Bot commented Jul 16, 2026 •

edited

Loading

Moist-Cat Jul 28, 2026 •

edited

Loading

Moist-Cat Jul 28, 2026 •

edited

Loading

Moist-Cat Jul 28, 2026 •

edited

Loading

Moist-Cat commented Jul 28, 2026 •

edited

Loading

Moist-Cat commented Jul 28, 2026 •

edited

Loading

Dreamsorcerer commented Jul 30, 2026 •

edited

Loading