classification
Title: smtplib.SMTP.starttls' documentation is just confusing
Type: Stage: patch review
Components: Documentation, email, Library (Lib) Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: alex, barry, christian.heimes, docs@python, maker, pitrou, r.david.murray
Priority: normal Keywords: needs review, patch

Created on 2014-08-29 20:33 by maker, last changed 2016-09-08 15:02 by christian.heimes. This issue is now closed.

Files
File name Uploaded Description Edit
t22301.diff alex, 2014-08-29 20:35 review
Messages (6)
msg226074 - (view) Author: Michele Orrù (maker) * Date: 2014-08-29 20:33
<maker> hello! In <https://docs.python.org/2/library/smtplib.html#smtplib.SMTP.starttls> I read::
<maker> "If keyfile and certfile are provided, these are passed to the socket module’s ssl() function."
<maker> socket.ssl() exists, though it is not documented (not even in /dev/library/socket)
<maker> and furthermore, the link on ssl() points to the ssl module, which is just confusing.
<bitdancer> maker: open an issue.

(I'm noising ap and chris because afaik they were working on the latest ssl security stuff)
msg226075 - (view) Author: Alex Gaynor (alex) * (Python committer) Date: 2014-08-29 20:35
Attached patch fixes this up.
msg226080 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-08-29 20:50
Or perhaps we should remove the function to wrap_socket(), which is just an implementation detail?
msg226083 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-08-29 20:56
Remove the reference, you mean?  As in just delete the confusing line?  Since we want to encourage people to use the context, that sounds reasonable for 3.x at least.
msg226242 - (view) Author: Michele Orrù (maker) * Date: 2014-09-01 19:57
"R. David Murray" <report@bugs.python.org> writes:

> Since we want to encourage people to use the context, that sounds
> reasonable for 3.x at least. 
Concerning this specific proposition, I really don't see the point in
having .starttls() not simply accepting a SSLContext as argument, as
imaplib.IMAP4.starttls is already doing, for example.
msg275035 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2016-09-08 15:02
starttls() does accept a ssl_context argument for a while.
History
Date User Action Args
2016-09-08 15:02:04christian.heimessetstatus: open -> closed
resolution: fixed
messages: + msg275035
2014-09-01 19:57:54makersetmessages: + msg226242
2014-08-29 20:56:52r.david.murraysetmessages: + msg226083
2014-08-29 20:50:19pitrousetmessages: + msg226080
2014-08-29 20:36:50terry.reedysetstage: patch review
versions: - Python 3.1, Python 3.2, Python 3.3
2014-08-29 20:35:55alexsetfiles: + t22301.diff

nosy: + alex
messages: + msg226075

keywords: + patch, needs review
2014-08-29 20:33:03makercreate