[Python-checkins] cpython (3.3): Issue #19882: tweak docs for socket.close()

[antoine.pitrou]

http://hg.python.org/cpython/rev/e10bb7c1b8f8
changeset:   87766:e10bb7c1b8f8
branch:      3.3
parent:      87756:f39a989f5b1a
user:        Antoine Pitrou <solipsis at pitrou.net>
date:        Wed Dec 04 21:02:42 2013 +0100
summary:
  Issue #19882: tweak docs for socket.close()

files:
  Doc/library/socket.rst |  28 +++++++++++++++++++---------
  1 files changed, 19 insertions(+), 9 deletions(-)


diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -701,8 +701,9 @@
 Socket Objects
 --------------
 
-Socket objects have the following methods.  Except for :meth:`makefile` these
-correspond to Unix system calls applicable to sockets.
+Socket objects have the following methods.  Except for
+:meth:`~socket.makefile`, these correspond to Unix system calls applicable
+to sockets.
 
 
 .. method:: socket.accept()
@@ -721,9 +722,15 @@
 
 .. method:: socket.close()
 
-   Close the socket.  All future operations on the socket object will fail. The
-   remote end will receive no more data (after queued data is flushed). Sockets are
-   automatically closed when they are garbage-collected.
+   Mark the socket closed.  The underlying system resource (e.g. a file
+   descriptor) is also closed when all file objects from :meth:`makefile()`
+   are closed.  Once that happens, all future operations on the socket
+   object will fail. The remote end will receive no more data (after
+   queued data is flushed).
+
+   Sockets are automatically closed when they are garbage-collected, but
+   it is recommended to :meth:`close` them explicitly, or to use a
+   :keyword:`with` statement around them.
 
    .. note::
       :meth:`close()` releases the resource associated with a connection but
@@ -829,10 +836,13 @@
    type depends on the arguments given to :meth:`makefile`.  These arguments are
    interpreted the same way as by the built-in :func:`open` function.
 
-   Closing the file object won't close the socket unless there are no remaining
-   references to the socket.  The socket must be in blocking mode; it can have
-   a timeout, but the file object's internal buffer may end up in a inconsistent
-   state if a timeout occurs.
+   The socket must be in blocking mode; it can have a timeout, but the file
+   object's internal buffer may end up in a inconsistent state if a timeout
+   occurs.
+
+   Closing the file object returned by :meth:`makefile` won't close the
+   original socket unless all other file objects have been closed and
+   :meth:`socket.close` has been called on the socket object.
 
    .. note::
 

-- 
Repository URL: http://hg.python.org/cpython