httpx.Timeout must include a default

[lovelydinosaur]

For consideration, wrt. 1.0 API tightening.

Ensures that httpx.Timeout(...) must strictly include an explicit default.

Usages like httpx.Timeout() and httpx.Timeout(read_timeout=5.0) are no longer valid. The default value must be explicitly included. Eg. httpx.Timeout(None) and httpx.Timeout(None, read_timeout=5.0).

Docstring on the class is:

Timeout configuration.

Usage:

httpx.Timeout(None)No timeouts.
httpx.Timeout(5.0)5s timeout on all operations.
httpx.Timeout(None, connect_timeout=5.0)5s timeout on connect, no other timeouts.
httpx.Timeout(5.0, connect_timeout=10.0)10s timeout on connect. 5s timeout elsewhere.
httpx.Timeout(5.0, pool_timeout=None)No timeout on acquiring connection from pool. 5s timeout elsewhere.

[lovelydinosaur]

Related to this... we could feasible want to prefer naming like Timeout(read=5.0) for the 1.0 cut, but we'd probably want a gentle "rename + warnings" approach if we decided to do that?

[jcugat]

The only thing that makes me go a bit 🤔 is that there's no way to modify a single timeout (the connect one for example) without either removing the other timeouts (with None) or setting an explicit default (but maybe I don't know which one httpx is currently using and I don't want to change it).

Why not allow something like this:

httpx.Timeout(read_timeout=10.0) # Everything else keeps the default

[lovelydinosaur]

but maybe I don't know which one httpx is currently using and I don't want to change it

Right, which is actually part of the point here. The default timeout for httpx.Client is httpx.Timeout(5.0).
However httpx.Timeout(read_timeout=10.0) means you'll be switching to httpx.Timeout(None, read_timeout=10.0).

Forcing the default value to be explicit makes this all more clear. The user needs to explicit use either httpx.Timeout(5.0, read_timeout=10.0) or httpx.Timeout(None, read_timeout=10.0) depending on what they actually intended.

[jcugat]

My worry is that the discoverability of the current default timeout is not obvious. It's only set in DEFAULT_TIMEOUT_CONFIG = Timeout(timeout=5.0) but I'm not sure if that is documented somewhere or considered public API.

Would you be open to having something like:

classTimeout:
DEFAULT: Final=5.0

So then the use-case I proposed could be achieved with:

httpx.Timeout(httpx.Timeout.DEFAULT, read_timeout=10.0)

[florimondmanca]

I agree that the current state of not enforcing a default to lead to a "gotcha" situation - where people might not expect the no-explicit-default usage to actually mean "no timeouts by default".

So +1 from me on this. Not certain if we should expose the default of 5s in code, but it looks likes this can be added incrementally from this PR.

Also +1 on reducing the verbosity caused by the _timeout suffixes. :)