Added returns to Server.pool()

Author: michalpokusa

adafruit_httpserver/__init__.py

@@ -59,7 +59,13 @@
     JSONResponse,
     Redirect,
 )
-from .server import Server
+from .server import (
+    Server,
+    NO_REQUEST,
+    CONNECTION_TIMED_OUT,
+    REQUEST_HANDLED_NO_RESPONSE,
+    REQUEST_HANDLED_RESPONSE_SENT,
+)
 from .status import (
     Status,
     OK_200,

adafruit_httpserver/server.py

@@ -33,6 +33,12 @@
 from .status import BAD_REQUEST_400, UNAUTHORIZED_401, FORBIDDEN_403, NOT_FOUND_404
 
 
+NO_REQUEST = 0
+CONNECTION_TIMED_OUT = 1
+REQUEST_HANDLED_NO_RESPONSE = 2
+REQUEST_HANDLED_RESPONSE_SENT = 3
+
+
 class Server:  # pylint: disable=too-many-instance-attributes
     """A basic socket-based HTTP server."""
 
@@ -318,10 +324,13 @@ def _set_default_server_headers(self, response: Response) -> None:
                 name, value
             )
 
-    def poll(self):
+    def poll(self) -> int:
         """
         Call this method inside your main loop to get the server to check for new incoming client
         requests. When a request comes in, it will be handled by the handler function.
+
+        Returns int representing the result of the poll
+        e.g. ``NO_REQUEST`` or ``REQUEST_HANDLED_RESPONSE_SENT``.
         """
         if self.stopped:
             raise ServerStoppedError
@@ -333,7 +342,7 @@ def poll(self):
 
                 # Receive the whole request
                 if (request := self._receive_request(conn, client_address)) is None:
-                    return
+                    return CONNECTION_TIMED_OUT
 
                 # Find a handler for the route
                 handler = self._routes.find_handler(
@@ -344,7 +353,7 @@ def poll(self):
                 response = self._handle_request(request, handler)
 
                 if response is None:
-                    return
+                    return REQUEST_HANDLED_NO_RESPONSE
 
                 self._set_default_server_headers(response)
 
@@ -354,14 +363,16 @@ def poll(self):
                 if self.debug:
                     _debug_response_sent(response)
 
+                return REQUEST_HANDLED_RESPONSE_SENT
+
         except Exception as error:  # pylint: disable=broad-except
             if isinstance(error, OSError):
                 # There is no data available right now, try again later.
                 if error.errno == EAGAIN:
-                    return
+                    return NO_REQUEST
                 # Connection reset by peer, try again later.
                 if error.errno == ECONNRESET:
-                    return
+                    return NO_REQUEST
 
             if self.debug:
                 _debug_exception_in_handler(error)

docs/examples.rst

@@ -72,6 +72,8 @@ Between calling ``.poll()`` you can do something useful,
 for example read a sensor and capture an average or
 a running total of the last 10 samples.
 
+``.poll()`` return value can be used to check if there was a request and if it was handled.
+
 .. literalinclude:: ../examples/httpserver_start_and_poll.py
     :caption: examples/httpserver_start_and_poll.py
     :emphasize-lines: 24,33

examples/httpserver_start_and_poll.py

@@ -5,7 +5,12 @@
 import socketpool
 import wifi
 
-from adafruit_httpserver import Server, Request, FileResponse
+from adafruit_httpserver import (
+    Server,
+    REQUEST_HANDLED_RESPONSE_SENT,
+    Request,
+    FileResponse,
+)
 
 
 pool = socketpool.SocketPool(wifi.radio)
@@ -30,7 +35,11 @@ def base(request: Request):
         # or a running total of the last 10 samples
 
         # Process any waiting requests
-        server.poll()
+        pool_result = server.poll()
+
+        if pool_result == REQUEST_HANDLED_RESPONSE_SENT:
+            # Do something only after handling a request
+            pass
 
         # If you want you can stop the server by calling server.stop() anywhere in your code
     except OSError as error: