Index: Doc/library/socket.rst =================================================================== --- Doc/library/socket.rst (revision 79791) +++ Doc/library/socket.rst (working copy) @@ -140,7 +140,15 @@ .. versionadded:: 2.3 +.. exception:: partialdataerror + This exception is raised when the :meth:`recvall` and :meth:`recvall_into` methods + fail before all of the data could be received. Its value is a tuple with three + elements: ``(errno, message, partialdata)``. + + .. versionadded:: 2.7 + + .. data:: AF_UNIX AF_INET AF_INET6 @@ -672,11 +680,45 @@ rather than creating a new string. If *nbytes* is not specified (or 0), receive up to the size available in the given buffer. See the Unix manual page :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults - to zero. + to zero. This method returns the number of bytes actually read. .. versionadded:: 2.5 +.. method:: socket.recvall(bufsize[, flags]) + + Receive a piece of data with a well-known size from the socket in one call. + When the system supports the :const:`MSG_WAITALL` socket flag, it uses that. + Otherwise, it will use an internal loop, until all bytes have been received. + The return value is a string representing the data received. + The exact size of the data to be received is specified by *bufsize*. + See the Unix manual page :manpage:`recv(2)` for the meaning of the optional + argument *flags*; it defaults to zero. + + .. note:: + + As with :meth:`recv`, for best match with hardware and network realities, the + value of *bufsize* should be a relatively small power of 2, for example, 4096. + + .. note:: + + If an error occurs when only part of the requested data has been received, + a :exc:`socket.partialdataerror` is raised. The application can extract the + received part of the data from the args tuple of that exception object. + + .. versionadded:: 2.7 + + +.. method:: socket.recvall_into(buffer[, nbytes[, flags]]) + + This is the version of :meth:`recv_into` that receives all data in one call, + in the same way as :meth:`recvall` does compared to :meth:`recv`. See those methods + for more details. This method returns the number of bytes actually read, + even if an error occurs when only part of the requested data has been received. + + .. versionadded:: 2.7 + + .. method:: socket.send(string[, flags]) Send data to the socket. The socket must be connected to a remote socket. The