This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: smtplib.SMTP raises socket.timeout
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Chris.Clark, Vyacheslav.Rafalskiy, docs@python, jesstess, python-dev, r.david.murray, zvyn
Priority: normal Keywords: easy, patch

Created on 2014-03-12 22:52 by Chris.Clark, last changed 2022-04-11 14:57 by admin. This issue is now closed.

File name Uploaded Description Edit
doc_socket_timeout.patch zvyn, 2014-03-19 13:18 Add a sentence about socket.timeout besides the discription of the timeout parameter. review
Messages (8)
msg213321 - (view) Author: Chris Clark (Chris.Clark) Date: 2014-03-12 22:52
The documentation for smtplib.SMTP says "If the connect() call returns anything other than a success code, an SMTPConnectError is raised." It doesn't explicitly specify what happens when connect() raises instead of returns, but I think either the documentation should mention "socket.timeout" or it should raise SMTPConnectError.

Python 3.3.4 (default, Feb 11 2014, 15:56:08) 
[GCC 4.8.2 20140206 (prerelease)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from smtplib import SMTP
>>> SMTP('', timeout=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python3.3/", line 241, in __init__
    (code, msg) = self.connect(host, port)
  File "/usr/lib/python3.3/", line 320, in connect
    self.sock = self._get_socket(host, port, self.timeout)
  File "/usr/lib/python3.3/", line 291, in _get_socket
  File "/usr/lib/python3.3/", line 435, in create_connection
    raise err
  File "/usr/lib/python3.3/", line 426, in create_connection
socket.timeout: timed out
msg213330 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-12 23:30
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.
msg213334 - (view) Author: Chris Clark (Chris.Clark) Date: 2014-03-12 23:42
I am concerned about the policy of not documenting all exceptions that are raised. It sounds like there is no straightforward way to write a comprehensive except statement without using a bare except or catching some base exception. I consider it dangerous to catch broad exception classes because it can hide some nasty bugs. And while I may be able to use OSError here, how can I be sure that you aren't forgetting about some other unexpected exception? Furthermore, I don't want to catch all OSErrors, only those relating to the SMTP server connection failing.

I definitely agree that it is preferable to be able to differentiate different types of exceptions. It seems to me that the best solution would be to make subclasses of SMTPConnectError so that I can catch SMTPConnectError if I don't care about the type or SMTPConnectTimeoutError if I do care about the type.
msg214092 - (view) Author: Milan Oberkirch (zvyn) * Date: 2014-03-19 13:18
The attached patch mentions the exception besides the description of the timeout parameter. It doesn't hurt and makes programmers aware of this common exception.
msg214913 - (view) Author: Vyacheslav Rafalskiy (Vyacheslav.Rafalskiy) Date: 2014-03-26 20:51
Take look at this one too:
It is supposed to be fixed.
msg220092 - (view) Author: Milan Oberkirch (zvyn) * Date: 2014-06-09 14:02
Should this task get closed? (see comment above)
msg220117 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-06-09 20:41
New changeset 6cd64ef6fc95 by R David Murray in branch '2.7':
#20903: clarify what happens when an smtp connection timeout occurs.

New changeset ca88bcfa5c15 by R David Murray in branch '3.4':
#20903: clarify what happens when an smtp connection timeout occurs.

New changeset 20225460ae0f by R David Murray in branch 'default':
Merge: #20903: clarify what happens when an smtp connection timeout occurs.
msg220118 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-06-09 20:42
Well, now that I applied your patch it can be :)  Thanks.
Date User Action Args
2022-04-11 14:57:59adminsetgithub: 65102
2014-06-09 20:42:44r.david.murraysetstatus: open -> closed
versions: - Python 3.3
messages: + msg220118

resolution: fixed
stage: needs patch -> resolved
2014-06-09 20:41:44python-devsetnosy: + python-dev
messages: + msg220117
2014-06-09 14:02:51zvynsetnosy: + jesstess
messages: + msg220092
2014-03-26 20:51:21Vyacheslav.Rafalskiysetnosy: + Vyacheslav.Rafalskiy
messages: + msg214913
2014-03-19 13:18:45zvynsetfiles: + doc_socket_timeout.patch

nosy: + zvyn
messages: + msg214092

keywords: + patch
2014-03-12 23:42:55Chris.Clarksetmessages: + msg213334
2014-03-12 23:30:43r.david.murraysetassignee: docs@python
components: + Documentation, - Library (Lib)
versions: + Python 3.4, Python 3.5
keywords: + easy
nosy: + docs@python, r.david.murray

messages: + msg213330
stage: needs patch
2014-03-12 22:52:34Chris.Clarkcreate