Timeout info.

[lovelydinosaur]

We'll want to carefully document the four different values in the timeout configuration.

If we could push the timeouts any further out of the stack then that'd be a good thing to do, but I don't think that's possible, since eg. there's no visibility onto "acquire the connection pool semaphore" vs. "wait for a new connection" but both require individually configurable timeout settings.

Our four values are:

• read - Timeouts on read operations.
• write - Timeouts on write operations, ie. failing to flush the buffer.
• connect - Timeouts on new TCP connections.
• pool acquiry - Timeout when waiting to not overload the connection pool.

(All optional floats.)

[florimondmanca]

Same idea than in #5 — could we benefit from using TypedDict to define timeout values?

import typing

class Timeouts(typing.TypedDict):
    read: typing.Optional[float]
    write: typing.Optional[float]
    connect: typing.Optional[float]
    pool_acquiry: typing.Optional[float]

timeouts: Timeouts = {"read": 5.0, "write": 3.0, "connect": None, "pool_acquiry": 10}

[lovelydinosaur]

Yup, not a bad idea.
We might also be okay with underspecifying things a little here, eg. just typing.Dict[str, float].