bpo-8595: Update urllib, httplib, smtplib docs to warn about global timeout value by akulakov · Pull Request #27087 · python/cpython (original) (raw)

The issue is that the global default timeout is set for sockets, - socket.setdefaulttimeout() - and referencing it would imply a recommendation to use it; but it would not be appropriate for sockets to have the same timeout as for http client. Various ideas like adding a similar default timeout along with get/set functions for httplib were discussed but there wasn't a strong agreement on the best approach, and the last messages were from 12 years ago.

For adding a reference to setdfaulttimeout which notes that default value is to never block, we could potentially also note that it's only for reference, and should not be used for setting the timeout, but it seems a bit awkward to reference something that shouldn't be used.

Another idea is to split off a paragraph in socket.setdefaulttimeout() doc with an anchor so that it only describes the value of timeout, but is not a direct link to the function itself. This is a bit better, but the downside is that function is still right above it; and the current doc works well as a single paragraph, and I think splitting it will make it slightly less readable.

I've removed leading 'Warning: '