Clarify and clean up the separation between BaseServer and TCPServer

Author: tungol

Doc/library/socketserver.rst

@@ -24,6 +24,55 @@ There are four basic concrete server classes:
    :meth:`~BaseServer.server_activate`.  The other parameters are passed to
    the :class:`BaseServer` base class.
 
+   In addition to the methods and attributes inherited from :class:`BaseServer`,
+   :class:`TCPServer` provides:
+
+
+   .. method:: fileno()
+
+      Return an integer file descriptor for the socket on which the server is
+      listening.  This function is most commonly passed to :mod:`selectors`, to
+      allow monitoring multiple servers in the same process.
+
+
+   .. method:: server_bind()
+
+      Called by the server's constructor to bind the socket to the desired address.
+      May be overridden.
+
+
+   .. attribute:: address_family
+
+      The family of protocols to which the server's socket belongs.
+      Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.
+
+
+   .. attribute:: socket
+
+      The socket object on which the server will listen for incoming requests.
+
+
+   .. attribute:: allow_reuse_address
+
+      Whether the server will allow the reuse of an address.  This defaults to
+      :const:`False`, and can be set in subclasses to change the policy.
+
+
+   .. attribute:: request_queue_size
+
+      The size of the request queue.  If it takes a long time to process a single
+      request, any requests that arrive while the server is busy are placed into a
+      queue, up to :attr:`request_queue_size` requests.  Once the queue is full,
+      further requests from clients will get a "Connection denied" error.  The default
+      value is usually 5, but this can be overridden by subclasses.
+
+
+   .. attribute:: socket_type
+
+      The type of socket used by the server; :const:`socket.SOCK_STREAM` and
+      :const:`socket.SOCK_DGRAM` are two common values.
+
+
 
 .. class:: UDPServer(server_address, RequestHandlerClass, bind_and_activate=True)
 
@@ -211,13 +260,6 @@ Server Objects
    :attr:`server_address` and :attr:`RequestHandlerClass` attributes.
 
 
-   .. method:: fileno()
-
-      Return an integer file descriptor for the socket on which the server is
-      listening.  This function is most commonly passed to :mod:`selectors`, to
-      allow monitoring multiple servers in the same process.
-
-
    .. method:: handle_request()
 
       Process a single request.  This function calls the following methods in
@@ -264,12 +306,6 @@ Server Objects
       Clean up the server. May be overridden.
 
 
-   .. attribute:: address_family
-
-      The family of protocols to which the server's socket belongs.
-      Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.
-
-
    .. attribute:: RequestHandlerClass
 
       The user-provided request handler class; an instance of this class is created
@@ -285,36 +321,10 @@ Server Objects
       the address, and an integer port number: ``('127.0.0.1', 80)``, for example.
 
 
-   .. attribute:: socket
-
-      The socket object on which the server will listen for incoming requests.
-
-
    The server classes support the following class variables:
 
    .. XXX should class variables be covered before instance variables, or vice versa?
 
-   .. attribute:: allow_reuse_address
-
-      Whether the server will allow the reuse of an address.  This defaults to
-      :const:`False`, and can be set in subclasses to change the policy.
-
-
-   .. attribute:: request_queue_size
-
-      The size of the request queue.  If it takes a long time to process a single
-      request, any requests that arrive while the server is busy are placed into a
-      queue, up to :attr:`request_queue_size` requests.  Once the queue is full,
-      further requests from clients will get a "Connection denied" error.  The default
-      value is usually 5, but this can be overridden by subclasses.
-
-
-   .. attribute:: socket_type
-
-      The type of socket used by the server; :const:`socket.SOCK_STREAM` and
-      :const:`socket.SOCK_DGRAM` are two common values.
-
-
    .. attribute:: timeout
 
       Timeout duration, measured in seconds, or :const:`None` if no timeout is
@@ -341,6 +351,10 @@ Server Objects
       socket object to be used to communicate with the client, and the client's
       address.
 
+      An implementation of :meth:`get_request` is provided by :class:`TCPServer`.
+      Other classes which inherit from :class:`BaseServer` directly must provide
+      their own implementation.
+
 
    .. method:: handle_error(request, client_address)
 
@@ -382,12 +396,6 @@ Server Objects
       on the server's socket.  May be overridden.
 
 
-   .. method:: server_bind()
-
-      Called by the server's constructor to bind the socket to the desired address.
-      May be overridden.
-
-
    .. method:: verify_request(request, client_address)
 
       Must return a Boolean value; if the value is :const:`True`, the request will
@@ -697,4 +705,3 @@ The output of the example should look something like this:
 The :class:`ForkingMixIn` class is used in the same way, except that the server
 will spawn a new process for each request.
 Available only on POSIX platforms that support :func:`~os.fork`.
-

Lib/socketserver.py

@@ -161,14 +161,15 @@ class BaseServer:
     - __init__(server_address, RequestHandlerClass)
     - serve_forever(poll_interval=0.5)
     - shutdown()
-    - handle_request()  # if you do not use serve_forever()
-    - fileno() -> int   # for selector
+    - handle_request()  # if you don't use serve_forever()
+
+    Methods that must be overridden:
+
+    - get_request() -> request, client_address
 
     Methods that may be overridden:
 
-    - server_bind()
     - server_activate()
-    - get_request() -> request, client_address
     - handle_timeout()
     - verify_request(request, client_address)
     - server_close()
@@ -186,15 +187,11 @@ class BaseServer:
     instances:
 
     - timeout
-    - address_family
-    - socket_type
-    - allow_reuse_address
-    - allow_reuse_port
 
     Instance variables:
 
+    - server_address
     - RequestHandlerClass
-    - socket
 
     """
 
@@ -273,18 +270,16 @@ def service_actions(self):
     # - finish_request() instantiates the request handler class; this
     #   constructor will handle the request all by itself
 
+    def _get_timeout(self):
+        """Hook so child classes can support other sources of timeout."""
+        return self.timeout
+
     def handle_request(self):
         """Handle one request, possibly blocking.
 
         Respects self.timeout.
         """
-        # Support people who used socket.settimeout() to escape
-        # handle_request before self.timeout was available.
-        timeout = self.socket.gettimeout()
-        if timeout is None:
-            timeout = self.timeout
-        elif self.timeout is not None:
-            timeout = min(timeout, self.timeout)
+        timeout = self._get_timeout()
         if timeout is not None:
             deadline = time() + timeout
 
@@ -325,6 +320,13 @@ def _handle_request_noblock(self):
         else:
             self.shutdown_request(request)
 
+    def get_request(self):
+        """Get the request and client address from the socket.
+
+        Must be overridden by subclasses.
+        """
+        raise NotImplementedError
+
     def handle_timeout(self):
         """Called if no new request arrives within self.timeout.
 
@@ -489,6 +491,16 @@ def server_close(self):
         """
         self.socket.close()
 
+    def _get_timeout(self):
+        # Support people who used socket.settimeout() to escape
+        # handle_request before self.timeout was available.
+        timeout = self.socket.gettimeout()
+        if timeout is None:
+            timeout = self.timeout
+        elif self.timeout is not None:
+            timeout = min(timeout, self.timeout)
+        return timeout
+
     def fileno(self):
         """Return socket file number.
 

Misc/NEWS.d/next/Documentation/2024-12-15-14-08-40.gh-issue-127209.17oPD0.rst

@@ -0,0 +1,3 @@
+Updated documentation for :mod:`socketserver` to clarify the differences
+between :class:`socketserver.BaseServer` and
+:class:`socketserver.TCPServer`.