Inconsistent Timeout Exception

[ChihweiLHBird]

httpx.get("https://www.google.com", timeout=0.0000001) raises:
httpx.ConnectError: [Errno 65] No route to host
(NOT a sub-class of TimeoutException)

httpx.get("https://www.google.com", timeout=0.05) raises:
httpx.ConnectTimeout: _ssl.c:983: The handshake operation timed out
(a sub-class of TimeoutException)

httpx.get("https://www.google.com", timeout=0.015) raises:
httpx.ReadTimeout: The read operation timed out
(a sub-class of TimeoutException)

Your mileage may vary depends on the latency between your location and the Google server.

I think ideally all timeouts of operation should raise a consistent exception (sub-class of TimeoutException) from the httpx client.

[ketpatil77]

ConnectTimeout and ReadTimeout already share TimeoutException. ConnectError represents a different failure, such as the OS immediately reporting that no route exists. A tiny timeout does not turn every earlier network failure into a timeout. Catch the branches according to the policy you need:

import httpx

def fetch(client, url):
    try:
        response = client.get(url, timeout=0.05)
        response.raise_for_status()
        return response
    except httpx.TimeoutException:
        # Connect/read/write/pool timeout.
        raise
    except httpx.RequestError:
        # Other request failures, including ConnectError.
        raise
    except httpx.HTTPStatusError:
        # An HTTP response was received, but its status was unsuccessful.
        raise

Place TimeoutException first because it is a RequestError subclass. If you want all transport/request failures handled identically, one RequestError handler is sufficient. Avoid treating all such failures as retryable; retries can repeat non-idempotent work or consume a one-shot request body.

HTTPX's timeout is also not a total wall-clock deadline: connect/read/write/pool are separate phases, and read timeout applies while waiting for incoming data. Timing against a public host is nondeterministic, so the three observed outcomes alone do not demonstrate inconsistent exception mapping. Validated the class hierarchy and handler dispatch with MockTransport raising ConnectError, ConnectTimeout, and ReadTimeout; no claim is made about the original OS routing failure. Exceptions, timeouts.

Validation version: HTTPX 0.28.1, Python 3.11.9.