Tune connection and data-transfer budgets
A service has slow or distant endpoints but should still fail promptly when no data arrives.
HTTPX · Class
Timeout
HTTPX Timeout configures maximum waiting periods for connection, reading, writing, and connection-pool acquisition. Set one default value or override individual phases with named arguments.
How it works
Timeout represents HTTPX's limits for waiting during connection setup, response reading, request writing, and connection-pool acquisition. A scalar supplies a general limit, while named values let you tune individual phases; the resulting object can be passed to a client or request.
Syntax
httpx.Timeout(timeout, *, connect=None, read=None, write=None, pool=None)Parameters
| Name | Type | Description |
|---|---|---|
timeout | float | None | Default timeout value, used as the general limit for timeout categories unless overridden. |
connect | float | None | Maximum duration for establishing a connection. |
read | float | None | Maximum duration for receiving response data. |
write | float | None | Maximum duration for sending request data. |
pool | float | None | Maximum duration for acquiring a connection from the pool. |
Returns
A timeout configuration object used by HTTPX request and client APIs.
Key points
- The class supports connect, read, write, and pool phases rather than one undifferentiated network deadline.
- Connect limits cover the wait for establishing a socket to the target host.
- Read limits are evaluated while waiting for each incoming response-data chunk.
- Write limits govern waiting while each request-data chunk is transmitted.
- Pool limits control how long a request waits for an available pooled connection.
- Use a general ten-second value with a sixty-second connection override when connection setup needs more time.
Common mistakes
- Timeouts apply to network inactivity, not necessarily to the total elapsed duration of a request; the default is five seconds.
- Passing
Nonedisables timeouts for an individual request, but this is a request-level setting rather than a Timeout object's configuration.
Example: Custom connection timeout
import httpx
# Allow 60 seconds to establish the connection, but 10 seconds
# for the other timeout categories.
timeout = httpx.Timeout(10.0, connect=60.0)
with httpx.Client(timeout=timeout) as client:
response = client.get("https://example.com")
response.raise_for_status()
print(response.status_code)Creates a reusable timeout policy with a longer connection limit and applies it to a client.
When to use it
Apply reusable client defaults
A client shares a consistent timeout policy across many requests.
Disable a request timeout
A request should intentionally wait without HTTPX's normal inactivity deadline.
Interview questions
QWhat timeout categories does HTTPX distinguish?
HTTPX has four timeout categories: connect, read, write, and pool. They cover establishing the socket, receiving response chunks, sending request chunks, and acquiring a pooled connection, respectively.
Follow-up: Which exception identifies a failed connection deadline? ConnectTimeout; the other phases have corresponding ReadTimeout, WriteTimeout, and PoolTimeout exceptions.
QHow do you configure one general timeout and a different connection timeout?
A scalar such as httpx.Timeout(10.0) establishes a general ten-second limit. Individual categories can then override that value, for example httpx.Timeout(10.0, connect=60.0).
Follow-up: Why might the connection value be larger? Connection establishment can need a different budget from data transfer, so separate values let the policy reflect those operational characteristics.
QHow is a Timeout configuration applied?
A Timeout instance is supplied through the timeout argument, including on a client. This makes the policy reusable across requests made by that client.
Follow-up: How would you remove the timeout entirely for one operation? Pass timeout=None on that individual request, as documented for the top-level API and client methods.
Related
TimeoutExceptionConnectTimeoutReadTimeoutWriteTimeoutPoolTimeoutClienthttpx.request