Better document request() middlewares override session middlewares

[yamplum]

Describe the bug

Perhaps not strictly a bug, but a counterintuitive behavior that doesn't match how other parts are handled (like headers).

If I define a ClientSession with middlewares and use request() with another set of middlewares, I expect the request-level middleware list to extend the session-level list, similar to how request headers are merged with session headers. Instead, request middleware replaces session middleware completely.

To Reproduce

import asyncio

import aiohttp


def middleware_session(
    req: aiohttp.ClientRequest, handle: aiohttp.ClientHandlerType
) -> aiohttp.ClientResponse:
    print("session middleware")
    print(req.headers)

    return handle(req)


def middleware_request(
    req: aiohttp.ClientRequest, handle: aiohttp.ClientHandlerType
) -> aiohttp.ClientResponse:
    print("request middleware")
    print(req.headers)

    return handle(req)


async def main_():
    session = aiohttp.ClientSession(
        middlewares=[middleware_session], headers={"User-Agent": "test"}
    )

    await session.get(
        "http://google.com",
        middlewares=[middleware_request],
        headers={"X-My-Header": "blah"},
    )


if __name__ == "__main__":
    asyncio.get_event_loop().run_until_complete(main_())

Expected behavior

In logs:

request middleware
session middleware
<CIMultiDict('Host': 'google.com', 'User-Agent': 'test', 'X-My-Header': 'blah', 'Accept': '*/*', 'Accept-Encoding': 'gzip, deflate, br')>

Logs/tracebacks

request middleware
<CIMultiDict('Host': 'google.com', 'User-Agent': 'test', 'X-My-Header': 'blah', 'Accept': '*/*', 'Accept-Encoding': 'gzip, deflate, br')>

Python Version

Python 3.13.3

aiohttp Version

3.12.11

multidict Version

6.4.4

propcache Version

0.3.1

yarl Version

1.20.0

OS

Mac OS 15.5

Related component

Client

Additional context

No response

Code of Conduct

• I agree to follow the aio-libs Code of Conduct

[bdraco]

This is an intentional design choice to be able to override middleware which may be undesirable for a specific request.

[Dreamsorcerer]

This is a particularly important behaviour for middlewares themselves: https://docs.aiohttp.org/en/stable/client_middleware_cookbook.html#logging-to-an-external-service

So, we won't be changing this. If there's enough demand, maybe we can add an extend_middlewares parameter.

[yamplum]

Forgive me, but this seems backwards? I understand the need to override the middleware set in certain situations, but it seems like a more niche case compared to simple layering, and replacing the entire set rather than bypassing specific middleware seems like the nuclear solution. As it stands, I can either use session middleware or request middleware but not both, and if I want to layer them then I have to handroll my own composition pipeline.

In either case, I would appreciate if such details were reflected in the documentation so that I didn't have to bother you with open tickets.

[bdraco]

Appreciate you pointing this out. You're right, it would be good to have this kind of detail in the docs. If you feel it's worth updating, feel free to open a PR. Thanks again for flagging it.

[Dreamsorcerer]

I understand the need to override the middleware set in certain situations, but it seems like a more niche case compared to simple layering

Frankly, the more I think about it, the more this feels rather complex to me anyway and we shouldn't allow it at all. Headers are simple, you have a default set and you override them with the headers you specify.

For middlewares, why is the expected behaviour that we append them to the end? That feels like a niche case to me. It's just as likely that a user would need to prepend them or insert one in the middle, or replace a specific middleware etc. It's incredibly order-dependent and simply appending is not a general-purpose solution, and is not going to fit the majority of cases.

For your specific usecase, I don't think it's too much to have:

MIDDLEWARES = (m1, m2)

async with ClientSession(middlewares=MIDDLEWARES) as sess:
    async with sess.get(middlewares=MIDDLEWARES + (m3,)) as resp:
        ...

This leaves it to the user to decide how middlewares are "merged". If we followed your approach and just appended all the time, then the majority of usecases would be impossible.