The documentation for urlopen says that it raises URLError on error.
But there exist error conditions such as a socket timeout or a bad HTTP status line under which the exception from the underlying library leaks through urllib, thus breaking the promise in the documentation.

I am attaching a test program that demonstrates this bug.

A patch to fix this issue. Catches exceptions from underlying libraries and reraises them as URLError.

I put the class name of the underlying exception in the reason to make it more descriptive.

I think the general pattern of wrapping exceptions in other exceptions is rather unfortunate. It makes it harder to examine the original problem (for example the errno attribute) for no actual gain.

Antoine, could "raise ... from" be used here? Perhaps also using new subclasses of URLError to allow the exceptions to be caught with finer granularity. That way no information would be lost while at the same time not surprising clients who only catch URLError based on the documentation.

At least one exception which I feel must be wrapped is socket.timeout. Since we allow a timeout argument to urlopen, it doesn't make sense for the fact of the timeout to be announced by an exception from another library.

Antoine, could "raise ... from" be used here?

That's a possible compromise indeed. It's up to Senthil to decide
anyway.

Perhaps also using new subclasses of URLError to allow the exceptions
to be caught with finer granularity. That way no information would be
lost while at the same time not surprising clients who only catch
URLError based on the documentation.

I agree there is a problem with the documentation announcing that all
exceptions will be wrapped. Honestly I would like it better if that
guarantee were dropped. In the meantime I'm not sure what the best
course of action is.

At least one exception which I feel must be wrapped is socket.timeout.
Since we allow a timeout argument to urlopen, it doesn't make sense
for the fact of the timeout to be announced by an exception from
another library.

You still may be interested to know that the request failed because of a
timeout rather than (say) an authentication failure, no?

I have stumbled upon a wrong impression as well by reading the docs, but usually in the code, I tend to catch the specific Exceptions, like timeout instead or URLError when it is known. I saw some libraries following similar pattern too. But that could be changed, if promise in the docs that URLError exception is raised is corrected.

I think, the course of action for this bug could be.

1. raise ... from .. for the appropriate Exception in 3.3 and appropriate doc changes.
2. Doc changes in 2.7,3.2 which say indicate the possibility of other exceptions besides URLError.

Having any important information in the msg part of the Exception is a bad idea, because it is seldom relied upon and can be changed anytime.

Shall come out with a patch.

There is another patch in duplicate bpo-8823, which has simpler exception wrapping code, but does not add wrapping of reply exceptions.

Personally, I wouldn’t endorse any new wrapping HTTP client exceptions, and even if wrapping more socket OS errors would be consistent, it could be a backwards compatibility problem. I think the best way forward is documentation: bpo-25633, bpo-22797.