httpcore

httpcore is the low-level networking engine underneath httpx, doing exactly one thing: sending HTTP requests over pooled, thread- and task-safe connections. It deliberately excludes the conveniences of a full client — no redirects, cookies, or JSON handling — so it can be reused as a clean transport layer by higher-level libraries.

It supports HTTP/1.1 and HTTP/2, HTTP(S) and SOCKS proxying, and both synchronous and asyncio/trio-based asynchronous interfaces generated from a single async codebase. Connection pooling, keep-alive expiry, and retry backoff are all built in, making it a solid foundation for anything that needs precise control over HTTP transport behavior.

What You Get

• Thread-safe and task-safe connection pooling via ConnectionPool with configurable max connections, keep-alive limits, and expiry
• Both synchronous (httpcore.request) and asynchronous (httpcore.AsyncConnectionPool) APIs generated from the same source via an internal async-to-sync unasync step
• HTTP/1.1 and HTTP/2 support, including transparent ALPN-based protocol negotiation over TLS
• HTTP(S) and SOCKS proxy support (HTTPProxy, AsyncSOCKSProxy) alongside direct connections
• Pluggable NetworkBackend/AsyncNetworkBackend interfaces (sync, anyio, trio, and mock backends) so networking can be swapped or stubbed for testing
• Configurable connection retries with exponential backoff and Unix domain socket support

Common Use Cases

• Serving as the transport layer underneath httpx, which builds redirects, cookies, and content decoding on top of httpcore’s raw connection handling
• Implementing a Python-based forward or reverse proxy service that needs direct, low-level control over connection pooling and protocol negotiation
• Building custom HTTP client libraries or SDKs that need a lean, well-tested networking core rather than reimplementing socket and TLS handling from scratch
• Writing test suites for HTTP-dependent code using MockBackend/AsyncMockBackend to simulate network responses without real sockets

Under The Hood

Architecture: httpcore is organized as a request pipeline: ConnectionPool (in httpcore/_sync/connection_pool.py and its async twin httpcore/_async/connection_pool.py) queues PoolRequest objects and hands each to an available HTTPConnection (httpcore/_sync/connection.py), which lazily opens a TCP or Unix socket via a NetworkBackend, negotiates TLS/ALPN, and then delegates to either HTTP11Connection or HTTP2Connection (httpcore/_sync/http11.py, http2.py) based on the negotiated protocol. httpcore/_models.py defines the URL, Origin, Request, and Response value objects that flow through this pipeline, and httpcore/_exceptions.py maps low-level socket/TLS errors onto a small, well-defined exception hierarchy (ConnectError, ReadTimeout, RemoteProtocolError, etc.) via a map_exceptions context manager. Every async module under httpcore/_async/ has a mechanically generated synchronous counterpart under httpcore/_sync/, so the sync and async APIs share identical logic and stay in lockstep.

Tech Stack: Pure Python 3.8+ with a deliberately tiny dependency footprint — certifi for CA bundles and h11>=0.16 for HTTP/1.1 parsing are the only hard requirements; h2 (HTTP/2), socksio (SOCKS proxying), anyio, and trio are all optional extras gated behind pip install httpcore[...]. The package builds with hatchling and hatch-fancy-pypi-readme, and pyproject.toml enables mypy --strict across the codebase.

Code Quality: The tests/ directory mirrors the source layout with tests/_sync/ and tests/_async/ suites covering connection_pool, connection, http11, http2, http_proxy, socks_proxy, plus an integration suite and a tests/benchmark/ client/server pair for throughput testing. Code favors small, single-responsibility classes (PoolRequest, HTTPConnection, HTTP11Connection) with explicit state machines for connection lifecycle (is_available, has_expired, is_idle, is_closed), consistent use of from __future__ import annotations and full type hints throughout, and strict mypy enforcement rather than relying on runtime checks alone.

API Design: The public surface is intentionally narrow — a handful of top-level functions (httpcore.request, httpcore.stream) for one-off calls, and ConnectionPool/AsyncConnectionPool as the primary reusable entry point, both implementing a shared RequestInterface. Docstrings on every public method spell out each parameter, and the sync/async API pairing (ConnectionPool vs AsyncConnectionPool, same method names and signatures) means developers can look up one and immediately use the other. The tradeoff is that consumers must understand HTTP at a lower level than with httpx — there’s no automatic redirect following or JSON decoding — which is by design given httpcore’s role as a transport primitive.