[docs] [issue20903] smtplib.SMTP raises socket.timeout

[R. David Murray]

R. David Murray added the comment:

In general we don't document what gets raised unless it is unique to a module or has non-obvious implications.  In this case, getting socket exceptions out of a network library should be "obvious" in some sense :).  In particular, both SMTPConnectError and socket.error are subclasses of OSError, so if you want to catch them all, catch OSError.

Now, that said, I have some sympathy to the idea that something triggered by a parameter to the call should perhaps result in an SMTPConnectError.  However, the argument *against* it is that it makes it difficult to differentiate the timeout error from other connection errors, which one might well want to do.  We've moved toward making it easier to tell classes of errors apart (see PEP 3151), so this would be a regression in that approach.

Given that the timeout is part of the signature, I think it does make sense to mention that the timeout will raise a socket.timeout error.

----------
assignee:  -> docs at python
components: +Documentation -Library (Lib)
keywords: +easy
nosy: +docs at python, r.david.murray
stage:  -> needs patch
versions: +Python 3.4, Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue20903>
_______________________________________