Merged revisions 84825-84826,84830 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r84825 | antoine.pitrou | 2010-09-15 10:39:25 +0200 (mer., 15 sept. 2010) | 3 lines

  Add a comment explaining why SocketIO is needed
........
  r84826 | antoine.pitrou | 2010-09-15 11:32:45 +0200 (mer., 15 sept. 2010) | 3 lines

  Improve docs for socket.makefile() and SocketIO
........
  r84830 | antoine.pitrou | 2010-09-15 13:12:57 +0200 (mer., 15 sept. 2010) | 3 lines

  Reverted unwanted change in r84826
........

Doc/library/socket.rst

@@ -597,10 +597,9 @@ correspond to Unix system calls applicable to sockets.
    arguments are interpreted the same way as by the built-in :func:`open`
    function.
 
-   The returned file object references a :cfunc:`dup`\ ped version of the
+   Closing the file object won't close the socket unless there are no
-   socket file descriptor, so the file object and socket object may be
+   remaining references to the socket.  The socket must be in blocking mode
-   closed or garbage-collected independently.  The socket must be in
+   (it can not have a timeout).
-   blocking mode (it can not have a timeout).
 
 
 .. method:: socket.recv(bufsize[, flags])

Lib/socket.py

@@ -195,6 +195,13 @@ class SocketIO(io.RawIOBase):
     the raw I/O interface on top of a socket object.
     """
 
+    # One might wonder why not let FileIO do the job instead.  There are two
+    # main reasons why FileIO is not adapted:
+    # - it wouldn't work under Windows (where you can't used read() and
+    #   write() on a socket handle)
+    # - it wouldn't work with socket timeouts (FileIO would ignore the
+    #   timeout and consider the socket non-blocking)
+
     # XXX More docs
 
     def __init__(self, sock, mode):
@@ -209,22 +216,40 @@ def __init__(self, sock, mode):
         self._writing = "w" in mode
 
     def readinto(self, b):
+        """Read up to len(b) bytes into the writable buffer *b* and return
+        the number of bytes read.  If the socket is non-blocking and no bytes
+        are available, None is returned.
+
+        If *b* is non-empty, a 0 return value indicates that the connection
+        was shutdown at the other end.
+        """
         self._checkClosed()
         self._checkReadable()
         return self._sock.recv_into(b)
 
     def write(self, b):
+        """Write the given bytes or bytearray object *b* to the socket
+        and return the number of bytes written.  This can be less than
+        len(b) if not all data could be written.  If the socket is
+        non-blocking and no bytes could be written None is returned.
+        """
         self._checkClosed()
         self._checkWritable()
         return self._sock.send(b)
 
     def readable(self):
+        """True if the SocketIO is open for reading.
+        """
         return self._reading and not self.closed
 
     def writable(self):
+        """True if the SocketIO is open for writing.
+        """
         return self._writing and not self.closed
 
     def fileno(self):
+        """Return the file descriptor of the underlying socket.
+        """
         self._checkClosed()
         return self._sock.fileno()
 
@@ -237,6 +262,9 @@ def mode(self):
         return self._mode
 
     def close(self):
+        """Close the SocketIO object.  This doesn't close the underlying
+        socket, except if all references to it have disappeared.
+        """
         if self.closed:
             return
         io.RawIOBase.close(self)