aiohttp

aiohttp is an asyncio-based HTTP client/server framework for Python. It is divided into three main functional areas:

1. Server (aiohttp.web)

Provides an HTTP/1.1 server including routing, middleware, WebSocket support, static-file serving, and a Gunicorn worker. Key APIs:

• aiohttp.web.Application
• web.RouteTableDef
• web.run_app
• web.AppRunner
• web.WebSocketResponse
• web.FileResponse

2. Client (aiohttp.ClientSession)

Provides an HTTP/1.1 client including connection pooling, TLS, proxy support, redirects, cookie handling, and WebSockets. Key APIs:

• aiohttp.ClientSession
• aiohttp.TCPConnector
• aiohttp.ClientResponse
• aiohttp.WSMessage
• aiohttp.BasicAuth

3. Shared Wire-Protocol Code

Core logic used by both client and server for protocol handling. Key APIs:

• aiohttp.MultipartReader / MultipartWriter
• aiohttp.CookieJar
• aiohttp.TraceConfig
• aiohttp.resolver.AsyncResolver

In aiohttp, routing is decoupled into two distinct concepts: Resources and Routes.

1. Resource: Represents a URI/location (a path). A resource has a path (which can be constant or dynamic, e.g., /path/{to}) and an optional unique name. A resource acts as a container for one or more routes.
2. Route: Represents a specific HTTP method applied to a resource. A route binds an HTTP method (like GET or POST) and a web-handler to a resource.

This decoupling allows you to define a single location (Resource) and then attach multiple handlers for different HTTP methods to that same location.

When you access a named entity via app.router['name'], you receive an AbstractResource instance rather than a specific route.

# 1. Define a resource with a path and a unique name
resource = router.add_resource('/path/{to}', name='name')

# 2. Add specific routes (methods + handlers) to that resource
route = resource.add_route('GET', handler)

Middlewares are ideal for managing authentication lifecycles. You can implement several strategies:

1. Reactive Refresh: Check for a 401 Unauthorized response, refresh the token, and retry the request.
2. Expiry-based Refresh: Check the token's expiry time before making the request and refresh if it is near expiration.
3. Preemptive Refresh: Refresh the token in a background task to avoid latency during the request flow (often better implemented outside of middleware).

These middlewares can also be adapted to handle proxy authentication by modifying ClientRequest.proxy_headers.

# Example: Reactive 401 Refresh
class TokenRefresh401Middleware:
    async def __call__(self, session, method, url, **kwargs):
        response = await session.request(method, url, **kwargs)
        if response.status == 401:
            # Logic to refresh token
            new_token = await refresh_token()
            kwargs['headers']['Authorization'] = f'Bearer {new_token}'
            return await session.request(method, url, **kwargs)
        return response

It is critical to understand how middlewares are applied. Request-level middlewares replace session-level middlewares; they do not merge with them. This is different from headers, which are merged.

• If you define middlewares in ClientSession(middlewares=[...]), they apply to all requests.
• If you pass middlewares=[...] to a specific request method (like get() or post()), the session-level middlewares are ignored for that request.
• To use both, you must explicitly pass both lists in the request call.

# Session middleware is used
session = ClientSession(middlewares=[middleware_session])
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]
)

Connectors are the transport layer for the aiohttp client API. They manage the underlying connections used to send requests.

There are two standard types of connectors:

1. TCPConnector: The most common transport, used for regular HTTP and HTTPS requests via TCP sockets. If you are unsure which connector to use, use TCPConnector.
2. UnixConnector: Used for connecting via UNIX sockets, primarily useful for testing or high-speed inter-process communication on the same host.

All connectors support keep-alive connections by default, which allows reusing connections for multiple requests to improve performance. This behavior is controlled by the force_close parameter.

# Example of using a UnixConnector
from aiohttp import ClientSession, UnixConnector

async def main():
    conn = UnixConnector(path='/path/to/socket')
    session = ClientSession(connector=conn)
    async with session.get('http://python.org') as resp:
        ... 
    await session.close()