changeset:   97112:8afd995802a6
branch:      2.7
parent:      97097:d4f64d27ded7
user:        Robert Collins <rbtcollins@hp.com>
date:        Wed Jul 29 12:48:42 2015 +1200
files:       Doc/library/socketserver.rst Lib/test/test_socketserver.py Misc/NEWS
description:
Issue #23254: Document how to close the TCPServer listening socket.

Patch from Martin Panter.


diff -r d4f64d27ded7 -r 8afd995802a6 Doc/library/socketserver.rst
--- a/Doc/library/socketserver.rst	Tue Jul 28 00:00:47 2015 -0500
+++ b/Doc/library/socketserver.rst	Wed Jul 29 12:48:42 2015 +1200
@@ -39,9 +39,10 @@
 handler class by subclassing the :class:`BaseRequestHandler` class and
 overriding its :meth:`handle` method; this method will process incoming
 requests.  Second, you must instantiate one of the server classes, passing it
-the server's address and the request handler class.  Finally, call the
+the server's address and the request handler class.  Then call the
 :meth:`handle_request` or :meth:`serve_forever` method of the server object to
-process one or many requests.
+process one or many requests.  Finally, call :meth:`~BaseServer.server_close`
+to close the socket.
 
 When inheriting from :class:`ThreadingMixIn` for threaded connection behavior,
 you should explicitly declare how you want your threads to behave on an abrupt
@@ -170,6 +171,13 @@
    .. versionadded:: 2.6
 
 
+.. method:: BaseServer.server_close()
+
+   Clean up the server. May be overridden.
+
+   .. versionadded:: 2.6
+
+
 .. attribute:: BaseServer.address_family
 
    The family of protocols to which the server's socket belongs.
@@ -540,6 +548,7 @@
        client(ip, port, "Hello World 3")
 
        server.shutdown()
+       server.server_close()
 
 
 The output of the example should look something like this::
diff -r d4f64d27ded7 -r 8afd995802a6 Lib/test/test_socketserver.py
--- a/Lib/test/test_socketserver.py	Tue Jul 28 00:00:47 2015 -0500
+++ b/Lib/test/test_socketserver.py	Wed Jul 29 12:48:42 2015 +1200
@@ -158,6 +158,8 @@
         if verbose: print "waiting for server"
         server.shutdown()
         t.join()
+        server.server_close()
+        self.assertRaises(socket.error, server.socket.fileno)
         if verbose: print "done"
 
     def stream_examine(self, proto, addr):
diff -r d4f64d27ded7 -r 8afd995802a6 Misc/NEWS
--- a/Misc/NEWS	Tue Jul 28 00:00:47 2015 -0500
+++ b/Misc/NEWS	Wed Jul 29 12:48:42 2015 +1200
@@ -34,6 +34,9 @@
 Library
 -------
 
+- Issue #23254: Document how to close the TCPServer listening socket.
+  Patch from Martin Panter.
+
 - Issue #17527: Add PATCH to wsgiref.validator. Patch from Luca Sbardella.
 
 - Issue #24613: Calling array.fromstring() with self is no longer allowed