From c3685dac9726a18421a2fe59a716973e9878fb1b Mon Sep 17 00:00:00 2001 From: enioxt Date: Thu, 16 Oct 2025 14:09:41 -0300 Subject: [PATCH] docs: clarify that request() middlewares replace session middlewares (#11674) --- docs/client_middleware_cookbook.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/client_middleware_cookbook.rst b/docs/client_middleware_cookbook.rst index 33994160fba..e890b02a4bf 100644 --- a/docs/client_middleware_cookbook.rst +++ b/docs/client_middleware_cookbook.rst @@ -98,6 +98,29 @@ Using both of these together in a session should provide full SSRF protection. Best Practices -------------- +.. important:: + + **Request-level middlewares replace session middlewares**: When you pass ``middlewares`` + to ``request()`` or its convenience methods (``get()``, ``post()``, etc.), it completely + replaces the session-level middlewares, rather than extending them. This differs from + other parameters like ``headers``, which are merged. + + .. code-block:: python + + session = ClientSession(middlewares=[middleware_session]) + + # Session middleware is used + await session.get("http://example.com") + + # Session middleware is NOT used, only request middleware + await session.get("http://example.com", middlewares=[middleware_request]) + + # To use both, explicitly pass both + await session.get( + "http://example.com", + middlewares=[middleware_session, middleware_request] + ) + 1. **Keep middleware focused**: Each middleware should have a single responsibility. 2. **Order matters**: Middlewares execute in the order they're listed. Place logging first,