From 1ee9283254446998c9f423896b1edffe42f246d3 Mon Sep 17 00:00:00 2001
From: Robert Collins <rbtcollins@hp.com>
Date: Wed, 29 Jul 2015 12:52:40 +1200
Subject: [PATCH] Issue #23254: Document how to close the TCPServer listening
 socket.

Patch from Martin Panter.
---
 Doc/library/socketserver.rst  | 13 +++++++++++--
 Lib/test/test_socketserver.py |  1 +
 Misc/NEWS                     |  3 +++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index 1ec44389bf8..3e49af6bba4 100644
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -33,9 +33,10 @@ Creating a server requires several steps.  First, you must create a request
 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
@@ -177,6 +178,13 @@ Server Objects
    Tell the :meth:`serve_forever` loop to stop and wait until it does.
 
 
+.. 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.
@@ -547,6 +555,7 @@ An example for the :class:`ThreadingMixIn` class::
        client(ip, port, "Hello World 3")
 
        server.shutdown()
+       server.server_close()
 
 
 The output of the example should look something like this::
diff --git a/Lib/test/test_socketserver.py b/Lib/test/test_socketserver.py
index 924b9c4d229..325d4856f92 100644
--- a/Lib/test/test_socketserver.py
+++ b/Lib/test/test_socketserver.py
@@ -144,6 +144,7 @@ class SocketServerTest(unittest.TestCase):
         server.shutdown()
         t.join()
         server.server_close()
+        self.assertEqual(-1, server.socket.fileno())
         if verbose: print("done")
 
     def stream_examine(self, proto, addr):
diff --git a/Misc/NEWS b/Misc/NEWS
index 4cf7d6d0ec9..83f310bb008 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -66,6 +66,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #23254: Document how to close the TCPServer listening socket.
+  Patch from Martin Panter.
+
 - Issue #19450: Update Windows builds to use SQLite 3.8.11.0
 
 - Issue #23441: rcompleter now prints a tab character instead of displaying