aiohttp

aiohttp is a dual-purpose HTTP library for Python’s asyncio ecosystem, providing both an async HTTP client (ClientSession) for calling external APIs and a full web server framework (aiohttp.web) for building your own HTTP and WebSocket services. Its core parsing paths are implemented in Cython against a vendored llhttp C parser for speed, and it has underpinned the async Python HTTP stack for over a decade.

The client side handles connection pooling, DNS caching via Happy Eyeballs, retries, timeouts, and streaming request/response bodies without extra dependencies. The server side offers an Application object with a pluggable UrlDispatcher, a middleware chain, and startup/cleanup lifecycle hooks, giving teams direct control over routing and request handling as a lighter alternative to heavier frameworks.

What You Get

• ClientSession-based async HTTP client with connection pooling, DNS caching, and automatic retries
• aiohttp.web application framework with UrlDispatcher routing, a middleware chain, and startup/cleanup lifecycle hooks
• Native WebSocket client and server support with no additional dependencies
• Cython-accelerated HTTP parsing (via vendored llhttp) and streaming multipart/body handling
• Pluggable connectors (TCP, Unix socket, named pipe) and built-in basic/digest auth middleware

Common Use Cases

• Calling third-party APIs concurrently from backend services without blocking the event loop
• Building lightweight REST or WebSocket API servers with direct control over routing and middleware
• Proxying and relaying HTTP traffic by combining the client and server sides in one asyncio process
• Powering real-time backends (chat, live dashboards) with native WebSocketResponse support

Under The Hood

Architecture

aiohttp splits cleanly into a client layer (client.py’s ClientSession orchestrating connector.py’s BaseConnector/TCPConnector connection pooling, client_reqrep.py’s ClientRequest/ClientResponse, and client_proto.py’s protocol handling) and a server layer (web_app.py’s Application composing web_urldispatcher.py’s UrlDispatcher, web_middlewares.py’s middleware chain, and web_protocol.py’s RequestHandler), with both sides sharing streams.py’s StreamReader/StreamWriter and the Cython-based HTTP parser/writer for message parsing. This layered separation lets the low-level protocol/parsing layer evolve independently of the public ClientSession/Application APIs, though a change to the streaming primitives would ripple through nearly every module since both client and server bodies flow through them.

Tech Stack

aiohttp targets Python 3.10+ and depends on aiohappyeyeballs for parallel DNS/connect racing, aiosignal for its extensible signal hooks, frozenlist and multidict for immutable/multi-value collections, propcache for cached properties, and yarl for URL parsing; an optional speedups extra pulls in aiodns, Brotli/brotlicffi, and a backported zstd decoder. The build system compiles Cython extensions against a vendored llhttp C parser, with CI producing prebuilt wheels across platforms; the project itself targets no specific deployment platform, functioning as a foundational asyncio library other services deploy on top of.

Code Quality

Testing lives in a large pytest suite using pytest-asyncio, covering unit tests and parity checks between the Cython and pure-Python parsers; CI runs the suite across multiple Python versions alongside mypy strict type checking (the package ships a py.typed marker) and pre-commit lint hooks. Error handling is explicit and typed, with a deep exception hierarchy rather than swallowed exceptions, and naming follows consistent Client*/Web* prefixes throughout — the combination of full type coverage, an extensive test suite, and codecov-tracked coverage in CI places this well above typical open-source hygiene.

API Design aiohttp’s public surface centers on two entry points — ClientSession for the client and Application for the server — each with a consistent async context-manager style, which keeps the getting-started path small even though the full connector/middleware/signal system underneath is considerably deeper. Documentation is extensive (a full Sphinx docs/ tree, quickstart guides, and a large examples/ directory covering middleware, auth, background tasks, and WebSockets), though newcomers coming from synchronous libraries like requests face a real conceptual jump to session lifecycles, connectors, and asyncio itself before they’re productive.