Document connection pool limiting.

[tomchristie]

We're not currently documenting our connection pool limiting, in the "Advanced" section of our docs.

Also we're currently only supporting the explicit configuration style of limits = httpx.PoolLimits(soft_limit=<int>, hard_limit=<int>).

We may well want to support more concise styles too, limits = <int> and limits = (int, int), which would be in line with the allowable styles our other config typing options.

We'll want to include how the pool timeout ties in too.

Behaviour to document is:

• soft_limit - Number of allowable keep-alive connections, or None to always allow. (Default 10)
• hard_limit - Maximum number of allowable connections, or None for no limits. (Default 100)

And in the timeout section:

• pool_timeout - Timeout period for connection acquiry from the pool, or None. (Default 5s)

I think we may also want to make some minor tweaks eg...

• Bump the allowable keep-alives to 50.
• Allow simpler config style as described above, by just setting a single integer.
• When the limit is specified as a single int then set the keep-alive limit to half that number.

[StephenBrown2]

👎 on limits = (int, int) from me. I much prefer to be explicit, and don't want to remember "Is it the soft limit first, or the hard?" (Though I admit that it does logically progress soft->hard in this example).

Tl;DR: kwargs all the way for me if possible.

[tomchristie]

I much prefer to be explicit, and don't want to remember "Is it the soft limit first, or the hard?

Fair comment. How do we feel about a simpler alternative of limits = <int> | limits = <httpx.PoolLimits>?

We should possible also be dropping the tuple-style on timeout = , then?
Which we'd ended up with initially out of deference to the requests API, but which is a pretty opaque four-tuple(!)

Other places where we use this style:

• cert - "Either a path to an SSL certificate file, or two-tuple of (certificate file, key file), or a three-tuple of (certificate file, key file, password)."
• File info, when sending multipart file uploads. https://www.python-httpx.org/quickstart/#sending-multipart-file-uploads.

[StephenBrown2]

We should possible also be dropping the tuple-style on timeout = , then?
Other places where we use this style:

Ah! I hadn't seen that go through. If that's the case, then I suppose a two-tuple isn't the worst... Especially for consistency :-p

[jtrakk]

My preference is for objects over tuples as well.

If for compatibility reasons it's important to use a tuple, there's always collections.namedtuple, but I find the arguments for objects quite convincing otherwise.

I do like that they're immutable though, I can't quite make sense of mutating timeouts dynamically -- @attr.s(frozen=True) is a nice tool for preventing that.

The lexicographic ordering of tuples also seems complicated in this case? There might be a risk of someone doing if limit1 < limit2: and getting wrong behavior when they maybe should've gotten a TypeError (though I haven't thought through all the possibilities) -- @attr.s(order=False) is a nice tool for preventing that.

---

Trio has an interesting conversation going on about soft and hard cancellation.

[yeraydiazdiaz]

Closed via #942