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
........
diff --git a/Lib/socket.py b/Lib/socket.py
index a2df891..f94c469 100644
--- a/Lib/socket.py
+++ b/Lib/socket.py
@@ -195,6 +195,13 @@
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 @@
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 @@
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)