<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)

Attached patch fixes this up.

Or perhaps we should remove the function to wrap_socket(), which is just an implementation detail?

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.

"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.

starttls() does accept a ssl_context argument for a while.