This contains a number of things:

1) Improve the documentation of the SSL module, with a fuller
   explanation of certificate usage, another reference, proper
   formatting of this and that.

2) Fix Windows bug in ssl.py, and general bug in sslsocket.close().
   Remove some unused code from ssl.py.  Allow accept() to be called on
   sslsocket sockets.

3) Use try-except-else in import of ssl in socket.py.  Deprecate use of
   socket.ssl().

4) Remove use of socket.ssl() in every library module, except for
   test_socket_ssl.py and test_ssl.py.

Lib/poplib.py

@@ -307,89 +307,95 @@ class POP3:
             return self._shortcmd('UIDL %s' % which)
         return self._longcmd('UIDL')
 
-class POP3_SSL(POP3):
-    """POP3 client class over SSL connection
+try:
+    import ssl
+except ImportError:
+    pass
+else:
 
-    Instantiate with: POP3_SSL(hostname, port=995, keyfile=None, certfile=None)
+    class POP3_SSL(POP3):
+        """POP3 client class over SSL connection
 
-           hostname - the hostname of the pop3 over ssl server
-           port - port number
-           keyfile - PEM formatted file that countains your private key
-           certfile - PEM formatted certificate chain file
+        Instantiate with: POP3_SSL(hostname, port=995, keyfile=None, certfile=None)
 
-        See the methods of the parent class POP3 for more documentation.
-    """
+               hostname - the hostname of the pop3 over ssl server
+               port - port number
+               keyfile - PEM formatted file that countains your private key
+               certfile - PEM formatted certificate chain file
 
-    def __init__(self, host, port = POP3_SSL_PORT, keyfile = None, certfile = None):
-        self.host = host
-        self.port = port
-        self.keyfile = keyfile
-        self.certfile = certfile
-        self.buffer = ""
-        msg = "getaddrinfo returns an empty list"
-        self.sock = None
-        for res in socket.getaddrinfo(self.host, self.port, 0, socket.SOCK_STREAM):
-            af, socktype, proto, canonname, sa = res
-            try:
-                self.sock = socket.socket(af, socktype, proto)
-                self.sock.connect(sa)
-            except socket.error, msg:
-                if self.sock:
-                    self.sock.close()
-                self.sock = None
-                continue
-            break
-        if not self.sock:
-            raise socket.error, msg
-        self.file = self.sock.makefile('rb')
-        self.sslobj = socket.ssl(self.sock, self.keyfile, self.certfile)
-        self._debugging = 0
-        self.welcome = self._getresp()
+            See the methods of the parent class POP3 for more documentation.
+        """
 
-    def _fillBuffer(self):
-        localbuf = self.sslobj.read()
-        if len(localbuf) == 0:
-            raise error_proto('-ERR EOF')
-        self.buffer += localbuf
+        def __init__(self, host, port = POP3_SSL_PORT, keyfile = None, certfile = None):
+            self.host = host
+            self.port = port
+            self.keyfile = keyfile
+            self.certfile = certfile
+            self.buffer = ""
+            msg = "getaddrinfo returns an empty list"
+            self.sock = None
+            for res in socket.getaddrinfo(self.host, self.port, 0, socket.SOCK_STREAM):
+                af, socktype, proto, canonname, sa = res
+                try:
+                    self.sock = socket.socket(af, socktype, proto)
+                    self.sock.connect(sa)
+                except socket.error, msg:
+                    if self.sock:
+                        self.sock.close()
+                    self.sock = None
+                    continue
+                break
+            if not self.sock:
+                raise socket.error, msg
+            self.file = self.sock.makefile('rb')
+            self.sslobj = ssl.sslsocket(self.sock, self.keyfile, self.certfile)
+            self._debugging = 0
+            self.welcome = self._getresp()
 
-    def _getline(self):
-        line = ""
-        renewline = re.compile(r'.*?\n')
-        match = renewline.match(self.buffer)
-        while not match:
-            self._fillBuffer()
+        def _fillBuffer(self):
+            localbuf = self.sslobj.read()
+            if len(localbuf) == 0:
+                raise error_proto('-ERR EOF')
+            self.buffer += localbuf
+
+        def _getline(self):
+            line = ""
+            renewline = re.compile(r'.*?\n')
             match = renewline.match(self.buffer)
-        line = match.group(0)
-        self.buffer = renewline.sub('' ,self.buffer, 1)
-        if self._debugging > 1: print '*get*', repr(line)
+            while not match:
+                self._fillBuffer()
+                match = renewline.match(self.buffer)
+            line = match.group(0)
+            self.buffer = renewline.sub('' ,self.buffer, 1)
+            if self._debugging > 1: print '*get*', repr(line)
 
-        octets = len(line)
-        if line[-2:] == CRLF:
-            return line[:-2], octets
-        if line[0] == CR:
-            return line[1:-1], octets
-        return line[:-1], octets
+            octets = len(line)
+            if line[-2:] == CRLF:
+                return line[:-2], octets
+            if line[0] == CR:
+                return line[1:-1], octets
+            return line[:-1], octets
 
-    def _putline(self, line):
-        if self._debugging > 1: print '*put*', repr(line)
-        line += CRLF
-        bytes = len(line)
-        while bytes > 0:
-            sent = self.sslobj.write(line)
-            if sent == bytes:
-                break    # avoid copy
-            line = line[sent:]
-            bytes = bytes - sent
+        def _putline(self, line):
+            if self._debugging > 1: print '*put*', repr(line)
+            line += CRLF
+            bytes = len(line)
+            while bytes > 0:
+                sent = self.sslobj.write(line)
+                if sent == bytes:
+                    break    # avoid copy
+                line = line[sent:]
+                bytes = bytes - sent
 
-    def quit(self):
-        """Signoff: commit changes on server, unlock mailbox, close connection."""
-        try:
-            resp = self._shortcmd('QUIT')
-        except error_proto, val:
-            resp = val
-        self.sock.close()
-        del self.sslobj, self.sock
-        return resp
+        def quit(self):
+            """Signoff: commit changes on server, unlock mailbox, close connection."""
+            try:
+                resp = self._shortcmd('QUIT')
+            except error_proto, val:
+                resp = val
+            self.sock.close()
+            del self.sslobj, self.sock
+            return resp
 
 
 if __name__ == "__main__":