httpx-aiohttp

httpx-aiohttp is a small Python library that lets httpx delegate its low-level socket/HTTP messaging work to aiohttp instead of httpx’s own default transport. Developers keep writing code against httpx’s familiar high-level API — authentication, retries, cookies, and the async client interface — while aiohttp handles the actual connection pooling and wire-level HTTP work underneath.

This is useful in codebases that already depend on aiohttp for other reasons (e.g. an existing aiohttp-based server or worker) but prefer httpx’s ergonomics for making outbound requests, letting them avoid running two separate connection-pooling stacks side by side.

What You Get

• An httpx-compatible transport class backed by aiohttp’s connection pooling and socket handling
• Retains httpx’s high-level features (auth flows, retries, cookie jars, request/response models) unchanged
• Async-only design matching aiohttp’s and httpx’s async client models
• Benchmark suite comparing httpx-aiohttp against plain httpx and other client stacks
• Small, dependency-light package (just aiohttp and httpx as runtime deps)

Common Use Cases

• Standardizing on a single HTTP connection stack (aiohttp) in a codebase that also wants httpx’s ergonomic client API
• Migrating an existing aiohttp-based service to httpx’s API surface without also migrating the underlying transport behavior
• Reusing aiohttp-specific connector configuration (proxies, SSL contexts, connection limits) from httpx application code
• Avoiding duplicate connection pools when a process already runs aiohttp for other I/O and adds httpx for outbound calls

Under The Hood

Architecture — The package is small and centers on two modules: src/httpx_aiohttp/transport.py, which implements httpx’s BaseTransport/AsyncBaseTransport interface by translating httpx requests into aiohttp ClientSession calls and translating aiohttp responses back into httpx Response objects, and src/httpx_aiohttp/client.py, which offers a preconfigured httpx.AsyncClient subclass wired to use that transport out of the box. Tech Stack — Python 3.8+, built with Hatchling and hatch-fancy-pypi-readme. Only two runtime dependencies: aiohttp>=3.10.0,<4 and httpx>=0.27.0. Dev tooling uses uv for dependency locking (uv.lock), ruff for linting, mypy/pyright for type checking, and mkdocs-material for documentation — a modern, fairly rigorous Python tooling setup for a small library. Code Quality — Tests are split into tests/local (direct transport behavior tests, e.g. test_aiohttp_client.py) and tests/httpx (likely reused httpx compliance/conformance tests run against the aiohttp-backed transport), plus a tests/models/whatwg.json fixture suggesting URL-parsing spec compliance testing. A benchmarks/ directory with multiple client/server backends (blacksheep, uvicorn) shows the maintainer actively measures transport overhead rather than just asserting correctness. API Design — The library’s entire value proposition is a drop-in replacement: swap in httpx_aiohttp’s transport or client class and existing httpx-based code keeps working unchanged, which is about as low-friction an API surface as a transport shim can offer.