kennethreitz/requests — pull request #999 by pasha-r (2012-12-12 12:52:04+00:00)
Title: Add "connection timeout" feature in addition to regular timeout.

Hi!

I'd like to suggest a new feature - two types of timeouts.
Regular one - happens when we wait for response from server on existing connection.
And a new one - connection timeout. Happens only when we try to create a new socket connection.
I added new request parameter connect_timeout and two new exceptions ConnectionTimeout and OperationTimeout.

But why anybody would need such a thing?

It can be useful when a call to some HTTP API takes a long time to answer the query (for ex. reading lots of data), but not so much to connect to the server.
With this new feature we can set bigger timeout and smaller connect_timeout, so network failures, dead API servers or DNS problems could be detected fast.

Other use case is - write request gone bad.
We connected to the server, called PUT to create some new record and caught timeout while waiting for response. Some async APIs work so that your request was actually processed despite broken connection.
And with two separate exceptions we can react differently in such a case - on ConnectionTimeout we know for sure nothing've been done so we can repeat the call. On OperationTimeout we may (or may not) poll the server for some indication that something is already going on and if not repeat the call.

On implementation:

I've implemented this feature in a way that does not break expected behavior for an existing code using the library.
New exceptions - ConnectionTimeout and OperationTimeout are subclasses of existing Timeout class.
Same goes for urllib3 TimeoutError and it's new subclasses.

New parameter connect_timeout is optional and when not given, value of the timeout parameter is used for both timeouts.
New HTTPConnectionTwo class (lame name, any suggestions?) takes one timeout in __init__ method and then checks whether it's a single value or a pair, so it also can be initialized exactly like HTTPConnection.

And thank you so much for the great library!

--
Pasha Kirichenko