What is included in the "connect" timeout?

[intgr]

Thanks for a more granular timeout system than requests!

I wish the documentation clarified a few details about the connect timeout: https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration

The connect timeout specifies the maximum amount of time to wait until a socket connection to the requested host is established. If HTTPX is unable to connect within this time frame, a ConnectTimeout exception is raised.

• Does it include DNS resolution? Sounds like no. Maybe resolution should be a separate timeout parameter?
• Does it include the TLS handhsake? Seems to suggest no, but best if it was clarified.

I can submit a documentation PR once these are clarified.

[ryux1]

The TLS handshake is covered by HTTPX’s connect timeout. HTTPX passes the same connect timeout first to the backend’s TCP connection call and then to start_tls; TLS timeout failures are mapped to ConnectTimeout. You can see that sequence in current httpcore: https://github.com/encode/httpcore/blob/10a658221deb38a4c5b16db55ab554b0bf731707/httpcore/_sync/connection.py#L105-L158

There are two nuances worth documenting:

1. It is not one end-to-end deadline. The TCP-connect operation and TLS-handshake operation each receive the configured timeout, so total elapsed setup time can exceed the numeric value. Configured connection retries can extend it further.
2. DNS is backend-dependent. In the default async AnyIO backend, anyio.connect_tcp(host, ...) runs inside anyio.fail_after(timeout), so its resolution/connect operation is bounded: https://github.com/encode/httpcore/blob/10a658221deb38a4c5b16db55ab554b0bf731707/httpcore/_backends/anyio.py#L97-L123. The sync backend delegates to socket.create_connection((host, port), timeout): https://github.com/encode/httpcore/blob/10a658221deb38a4c5b16db55ab554b0bf731707/httpcore/_backends/sync.py#L187-L217. CPython performs name resolution before applying the socket timeout to connection attempts, so the connect setting is not a reliable hard DNS deadline for synchronous clients.

So the short answer is: TLS yes; DNS usually within the async backend’s connect scope, but not universally guaranteed—especially for blocking system DNS in the sync client. A separate DNS timeout is not currently exposed by HTTPX; applications needing a strict overall deadline need an outer cancellation/deadline appropriate to their concurrency backend.

[ryux1]

The short answer is: TLS is included, while DNS has an important backend/platform caveat.

HTTPX passes the connect value to httpcore as the timeout for establishing a connection. In httpcore, _connect() uses that value first for connect_tcp(...), and then—when the origin is HTTPS—passes the same value to stream.start_tls(...). So the TLS handshake is covered by the connect-timeout setting. These are separate timeout scopes, though, rather than one shared end-to-end deadline: TCP establishment may consume up to the configured value and the TLS handshake may then consume up to that value again.

DNS happens inside the backend’s TCP-connect operation. With the async AnyIO backend, the entire anyio.connect_tcp(...) await (including resolution) is wrapped in anyio.fail_after(connect_timeout), so it is part of that timeout scope. The synchronous backend delegates to socket.create_connection(host, port, timeout). CPython resolves via getaddrinfo() before applying the socket timeout to individual connection attempts, so a blocking system resolver is not reliably bounded by that value. Other custom backends may also differ.

So I would document it approximately as: “The connect timeout applies to socket connection establishment and TLS handshakes. DNS resolution occurs as part of connection establishment, but whether a blocking resolver can be interrupted is backend/platform dependent.” A separate DNS timeout would require a distinct resolver/backend abstraction; it cannot be implemented reliably just by splitting the existing HTTPX timeout value.