Documentation.

Link socket and SSLSocket objects to their version appropriate
documentation on python.org.

Explicitly use the version-specific base socket class for SSLSocket.
This prevents the docs from listing the wrong base (because the docs are
built on Python 3 and so gevent.socket would be gevent._socket3, leading
the base of gevent._ssl2.SSLSocket to be gevent._socket3.socket).

Also, no need to 'from io import BlockingIOError' for Python 3. It
became a builtin in Python 3.3 which is the lowest version we support.

gevent/_socket2.py

@@ -92,7 +92,8 @@ timeout_default = object()
 
 class socket(object):
     """
-    gevent socket object.
+    gevent `socket.socket <https://docs.python.org/2/library/socket.html#socket-objects>`_
+    for Python 2.
     """
 
     def __init__(self, family=AF_INET, type=SOCK_STREAM, proto=0, _sock=None):

gevent/_socket3.py

@@ -8,7 +8,6 @@ import sys
 import time
 from gevent import _socketcommon
 import _socket
-from io import BlockingIOError
 from os import dup
 
 for key in _socketcommon.__dict__:
@@ -44,7 +43,7 @@ class _wrefsocket(_socket.socket):
     # monkey patched to be the object from this module), but we still
     # need to make sure what we do create can be weakrefd.
 
-    __slots__ = ["__weakref__", ]
+    __slots__ = ("__weakref__", )
 
 _closedsocket = _wrefsocket()
 _closedsocket.close()
@@ -52,9 +51,13 @@ _closedsocket.close()
 
 class socket(object):
     """
-    gevent socket object.
+    gevent `socket.socket <https://docs.python.org/3/library/socket.html#socket-objects>`_
+    for Python 3.
     """
 
+    # Subclasses can set this to customize the type of the
+    # native _socket.socket we create. It MUST be a subclass
+    # of _wrefsocket. (gevent internal usage only)
     _gevent_sock_class = _wrefsocket
 
     def __init__(self, family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None):

gevent/_ssl2.py

@@ -17,7 +17,8 @@ except AttributeError:
 
 import sys
 import errno
-from gevent.socket import socket, _fileobject, timeout_default
+from gevent._socket2 import socket
+from gevent.socket import _fileobject, timeout_default
 from gevent.socket import error as socket_error, EWOULDBLOCK
 from gevent.socket import timeout as _socket_timeout
 from gevent.hub import string_types, PYPY
@@ -64,6 +65,10 @@ __all__ = list(set(__implements__) | set(__imports__))
 
 
 class SSLSocket(socket):
+    """
+    gevent `ssl.SSLSocket <https://docs.python.org/2.6/library/ssl.html#sslsocket-objects>`_
+    for Pythons < 2.7.9.
+    """
 
     def __init__(self, sock, keyfile=None, certfile=None,
                  server_side=False, cert_reqs=CERT_NONE,

gevent/_ssl3.py

@@ -96,6 +96,10 @@ class _contextawaresock(socket._gevent_sock_class):
 
 
 class SSLSocket(socket):
+    """
+    gevent `ssl.SSLSocket <https://docs.python.org/3/library/ssl.html#ssl-sockets>`_
+    for Python 3.
+    """
 
     _gevent_sock_class = _contextawaresock
 

gevent/_sslgte279.py

@@ -13,7 +13,8 @@ import ssl as __ssl__
 _ssl = __ssl__._ssl
 
 import errno
-from gevent.socket import socket, timeout_default
+from gevent._socket2 import socket
+from gevent.socket import timeout_default
 from gevent.socket import error as socket_error
 from gevent.socket import timeout as _socket_timeout
 from gevent.hub import PYPY
@@ -166,6 +167,10 @@ _create_stdlib_context = _create_unverified_context
 
 
 class SSLSocket(socket):
+    """
+    gevent `ssl.SSLSocket <https://docs.python.org/2/library/ssl.html#ssl-sockets>`_
+    for Pythons >= 2.7.9 but less than 3.
+    """
 
     def __init__(self, sock=None, keyfile=None, certfile=None,
                  server_side=False, cert_reqs=CERT_NONE,

gevent/server.py

@@ -5,9 +5,6 @@ import _socket
 from gevent.baseserver import BaseServer
 from gevent.socket import EWOULDBLOCK, socket
 from gevent.hub import PYPY, PY3
-if PY3:
-    from io import BlockingIOError
-
 
 __all__ = ['StreamServer', 'DatagramServer']