In light of the recv() and recv_into() implementation change (issue3890), I think we should enable SSL_MODE_AUTO_RETRY for SSL sockets. It prevents blocking read() calls from getting SSL_ERROR_WANT_READ at all.
(previously, we would loop manually in recv() and recv_into(); letting
the C OpenSSL runtime do it for us is certainly more efficient)

See description in
http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html:

« SSL_MODE_AUTO_RETRY

        Never bother the application with retries if the transport is
        blocking. If a renegotiation take place during normal operation,
        a SSL_read(3) or SSL_write(3) would return with -1 and indicate
        the need to retry with SSL_ERROR_WANT_READ. In a non-blocking
        environment applications must be prepared to handle incomplete
        read/write operations. In a blocking environment, applications
        are not always prepared to deal with read/write operations
        returning without success report. The flag SSL_MODE_AUTO_RETRY
        will cause read/write operations to only return after the
        handshake and successful completion. »

By reading the doc it is not clear if we should activate this option only when dealing with blocking sockets.
What's the behavior with non blocking ones?
Does it result in a no-op or does it hang the applcation?

To me it looks clearly like a no-op ("Never bother the application with retries *if the transport is blocking*").

Mmm you're right. Sorry.
I'm clearly too tired. =)

Looks like a good idea.

See also issue #8240 about SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER (ssl.SSLSocket.write may fail on non-blocking sockets).

> letting the C OpenSSL runtime do it for us is certainly more efficient

+1 if it's more efficient ;-)

Would it be possible to add an option to disable SSL_MODE_AUTO_RETRY for a specific socket? Existing applications may rely on / prefer the current behaviour.

> Would it be possible to add an option to disable SSL_MODE_AUTO_RETRY
> for a specific socket? Existing applications may rely on / prefer the
> current behaviour.

I don't think so, since recv() used to emulate that behaviour anyway.

Fixed in r79448 (trunk), r79449 (py3k), r79451 (2.6), r79453 (3.1).