elastic-transport-python

elastic-transport is the low-level HTTP transport library that Elastic extracted from elasticsearch-py so every Elastic Python client (Elasticsearch, Enterprise Search, and others) can share one connection-pooling, retry, and node-selection implementation. It wraps urllib3 (and optionally httpx/aiohttp for async) behind a Transport/AsyncTransport class that handles node discovery, round-robin/randomized load balancing across cluster nodes, automatic retries with backoff, and pluggable serialization.

What You Get

• Transport/AsyncTransport classes handling request dispatch, retries, and timeouts across a pool of cluster nodes
• A NodePool abstraction with pluggable node-selection strategies (round-robin, randomized) and dead-node handling
• Sync (urllib3) and async (aiohttp/httpx) node implementations behind a common interface
• Pluggable Serializer classes for JSON and other content types negotiated via HTTP headers
• Built-in OpenTelemetry span instrumentation for outgoing requests

Common Use Cases

• Providing the transport layer underneath elasticsearch-py and other official Elastic Python clients
• Building custom clients for Elastic Stack services that need multi-node failover without reinventing connection pooling
• Adding OpenTelemetry tracing to HTTP calls made against an Elastic cluster
• Swapping between sync and async HTTP backends while keeping the same retry/node-pool semantics

Under The Hood

Architecture: _transport.py/_async_transport.py implement the request lifecycle — pick a node from _node_pool.py’s NodePool, dispatch through a node implementation in _node/, retry on configured failure conditions, and mark nodes dead/alive based on response outcomes; _models.py defines the request/response value objects and _serializer.py handles content-type-based (de)serialization. Tech Stack: pure Python 3.8+, built on urllib3 for sync HTTP with optional aiohttp/httpx extras for async, versioned in lockstep with the Elastic Stack’s major.minor release cadence. Code Quality: a dedicated tests/ tree covers both sync and async_ code paths plus node-pool selection logic, with noxfile.py-driven CI across Python versions and full type coverage (py.typed). API Design: the sync/async class pairing keeps the public API symmetric, and the library deliberately stays low-level (no query DSL or resource-specific methods) so it can be reused as the transport foundation under multiple, unrelated Elastic product clients rather than being tied to Elasticsearch’s API shape.