Updated docs and examples to new Response API, added example of Redirect

Author: michalpokusa

docs/api.rst

@@ -22,9 +22,6 @@
 .. automodule:: adafruit_httpserver.status
     :members:
 
-.. automodule:: adafruit_httpserver.methods
-    :members:
-
 .. automodule:: adafruit_httpserver.mime_types
     :members:
 

docs/examples.rst

@@ -49,11 +49,11 @@ In order to save memory, we are unregistering unused MIME types and registering
     :linenos:
 
 You can also serve a specific file from the handler.
-By default ``Response.send_file()`` looks for the file in the server's ``root_path`` directory, but you can change it.
+By default ``FileResponse`` looks for the file in the server's ``root_path`` directory, but you can change it.
 
 .. literalinclude:: ../examples/httpserver_handler_serves_file.py
     :caption: examples/httpserver_handler_serves_file.py
-    :emphasize-lines: 22-23
+    :emphasize-lines: 22
     :linenos:
 
 .. literalinclude:: ../examples/home.html
@@ -74,7 +74,7 @@ a running total of the last 10 samples.
 
 .. literalinclude:: ../examples/httpserver_start_and_poll.py
     :caption: examples/httpserver_start_and_poll.py
-    :emphasize-lines: 25,34
+    :emphasize-lines: 24,33
     :linenos:
 
 Server with MDNS
@@ -91,6 +91,17 @@ In this example, the server is accessible via ``http://custom-mdns-hostname/`` a
     :emphasize-lines: 12-14
     :linenos:
 
+Get CPU information
+-------------------
+
+You can return data from sensors or any computed value as JSON.
+That makes it easy to use the data in other applications.
+
+.. literalinclude:: ../examples/httpserver_cpu_information.py
+    :caption: examples/httpserver_cpu_information.py
+    :emphasize-lines: 9,27
+    :linenos:
+
 Handling different methods
 ---------------------------------------
 
@@ -107,7 +118,7 @@ In example below, handler for ``/api`` and ``/api/`` route will be called when a
 
 .. literalinclude:: ../examples/httpserver_methods.py
     :caption: examples/httpserver_methods.py
-    :emphasize-lines: 8,15
+    :emphasize-lines: 8,19,26,30,49
     :linenos:
 
 Change NeoPixel color
@@ -129,29 +140,19 @@ Tested on ESP32-S2 Feather.
 
 .. literalinclude:: ../examples/httpserver_neopixel.py
     :caption: examples/httpserver_neopixel.py
-    :emphasize-lines: 25-27,39-40,52-53,61,69
-    :linenos:
-
-Get CPU information
--------------------
-
-You can return data from sensors or any computed value as JSON.
-That makes it easy to use the data in other applications.
-
-.. literalinclude:: ../examples/httpserver_cpu_information.py
-    :caption: examples/httpserver_cpu_information.py
-    :emphasize-lines: 28-29
+    :emphasize-lines: 25-27,39,51,60,66
     :linenos:
 
 Chunked response
 ----------------
 
-Library supports chunked responses. This is useful for streaming data.
-To use it, you need to set the ``chunked=True`` when creating a ``Response`` object.
+Library supports chunked responses. This is useful for streaming large amounts of data.
+In order to use it, you need pass a generator that yields chunks of data to a ``ChunkedResponse``
+constructor.
 
 .. literalinclude:: ../examples/httpserver_chunked.py
     :caption: examples/httpserver_chunked.py
-    :emphasize-lines: 21-26
+    :emphasize-lines: 8,21-26,28
     :linenos:
 
 URL parameters and wildcards
@@ -163,7 +164,7 @@ Query/GET parameters are better suited for modifying the behaviour of the handle
 
 Of course it is only a suggestion, you can use them interchangeably and/or both at the same time.
 
-In order to use URL parameters, you need to wrap them inside ``<>`` in ``Server.route``, e.g. ``<my_parameter>``.
+In order to use URL parameters, you need to wrap them inside with angle brackets in ``Server.route``, e.g. ``<my_parameter>``.
 
 All URL parameters values are **passed as keyword arguments** to the handler function.
 
@@ -185,7 +186,7 @@ In both cases, wildcards will not match empty path segment, so ``/api/.../users`
 
 .. literalinclude:: ../examples/httpserver_url_parameters.py
     :caption: examples/httpserver_url_parameters.py
-    :emphasize-lines: 30-34,54-55
+    :emphasize-lines: 30-34,53-54
     :linenos:
 
 Authentication
@@ -206,7 +207,21 @@ In both cases you can check if ``request`` is authenticated by calling ``check_a
 
 .. literalinclude:: ../examples/httpserver_authentication_handlers.py
     :caption: examples/httpserver_authentication_handlers.py
-    :emphasize-lines: 9-15,21-25,33,44,57
+    :emphasize-lines: 9-15,21-25,33,47,59
+    :linenos:
+
+Redirects
+---------
+
+Sometimes you might want to redirect the user to a different URL, either on the same server or on a different one.
+
+You can do that by returning ``Redirect`` from your handler function.
+
+You can specify wheter the redirect is permanent or temporary by passing ``permanent=...``  to ``Redirect``.
+
+.. literalinclude:: ../examples/httpserver_redirects.py
+    :caption: examples/httpserver_redirects.py
+    :emphasize-lines: 14-18,26,38
     :linenos:
 
 Multiple servers
@@ -223,7 +238,7 @@ You can share same handler functions between servers or use different ones for e
 
 .. literalinclude:: ../examples/httpserver_multiple_servers.py
     :caption: examples/httpserver_multiple_servers.py
-    :emphasize-lines: 13-14,17,26,35-36,48-49,54-55
+    :emphasize-lines: 13-14,17,25,33-34,45-46,51-52
     :linenos:
 
 Debug mode
@@ -256,8 +271,7 @@ This is the default format of the logs::
     {client_ip} -- "{request_method} {path}" {request_size} -- "{response_status}" {response_size}
 
 If you need more information about the server or request, or you want it in a different format you can modify
-functions at the bottom of ``adafruit_httpserver/server.py`` and ``adafruit_httpserver/response.py`` that
-start with ``_debug_...``.
+functions at the bottom of ``adafruit_httpserver/server.py`` that start with ``_debug_...``.
 
 NOTE:
 *This is an advanced usage that might change in the future. It is not recommended to modify other parts of the code.*

examples/httpserver_authentication_handlers.py

@@ -32,8 +32,11 @@ def check_if_authenticated(request: Request):
     """
     is_authenticated = check_authentication(request, auths)
 
-    with Response(request, content_type="text/plain") as response:
-        response.send("Authenticated" if is_authenticated else "Not authenticated")
+    return Response(
+        request,
+        body="Authenticated" if is_authenticated else "Not authenticated",
+        content_type="text/plain",
+    )
 
 
 @server.route("/require-or-401")
@@ -43,8 +46,7 @@ def require_authentication_or_401(request: Request):
     """
     require_authentication(request, auths)
 
-    with Response(request, content_type="text/plain") as response:
-        response.send("Authenticated")
+    return Response(request, body="Authenticated", content_type="text/plain")
 
 
 @server.route("/require-or-handle")
@@ -56,12 +58,15 @@ def require_authentication_or_manually_handle(request: Request):
     try:
         require_authentication(request, auths)
 
-        with Response(request, content_type="text/plain") as response:
-            response.send("Authenticated")
+        return Response(request, body="Authenticated", content_type="text/plain")
 
     except AuthenticationError:
-        with Response(request, status=UNATUHORIZED_401) as response:
-            response.send("Not authenticated - Manually handled")
+        return Response(
+            request,
+            body="Not authenticated - Manually handled",
+            content_type="text/plain",
+            status=UNATUHORIZED_401,
+        )
 
 
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_authentication_server.py

@@ -25,8 +25,7 @@ def implicit_require_authentication(request: Request):
     Implicitly require authentication because of the server.require_authentication() call.
     """
 
-    with Response(request, content_type="text/plain") as response:
-        response.send("Authenticated")
+    return Response(request, body="Authenticated", content_type="text/plain")
 
 
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_chunked.py

@@ -5,7 +5,7 @@
 import socketpool
 import wifi
 
-from adafruit_httpserver import Server, Request, Response
+from adafruit_httpserver import Server, Request, ChunkedResponse
 
 
 pool = socketpool.SocketPool(wifi.radio)
@@ -18,12 +18,14 @@ def chunked(request: Request):
     Return the response with ``Transfer-Encoding: chunked``.
     """
 
-    with Response(request, chunked=True) as response:
-        response.send_chunk("Adaf")
-        response.send_chunk("ruit")
-        response.send_chunk(" Indus")
-        response.send_chunk("tr")
-        response.send_chunk("ies")
+    def body():
+        yield "Adaf"
+        yield b"ruit"  # Data chunk can be bytes or str.
+        yield " Indus"
+        yield b"tr"
+        yield "ies"
+
+    return ChunkedResponse(request, body)
 
 
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_cpu_information.py

@@ -2,12 +2,11 @@
 #
 # SPDX-License-Identifier: Unlicense
 
-import json
 import microcontroller
 import socketpool
 import wifi
 
-from adafruit_httpserver import Server, Request, Response
+from adafruit_httpserver import Server, Request, JSONResponse
 
 pool = socketpool.SocketPool(wifi.radio)
 server = Server(pool, debug=True)
@@ -25,8 +24,7 @@ def cpu_information_handler(request: Request):
         "voltage": microcontroller.cpu.voltage,
     }
 
-    with Response(request, content_type="application/json") as response:
-        response.send(json.dumps(data))
+    return JSONResponse(request, data)
 
 
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_handler_serves_file.py

@@ -6,7 +6,7 @@
 import socketpool
 import wifi
 
-from adafruit_httpserver import Server, Request, Response
+from adafruit_httpserver import Server, Request, FileResponse
 
 
 pool = socketpool.SocketPool(wifi.radio)
@@ -19,8 +19,7 @@ def home(request: Request):
     Serves the file /www/home.html.
     """
 
-    with Response(request, content_type="text/html") as response:
-        response.send_file("home.html", root_path="/www")
+    return FileResponse(request, "home.html", "/www")
 
 
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_mdns.py

@@ -6,7 +6,7 @@
 import socketpool
 import wifi
 
-from adafruit_httpserver import Server, Request, Response
+from adafruit_httpserver import Server, Request, FileResponse
 
 
 mdns_server = mdns.Server(wifi.radio)
@@ -22,8 +22,8 @@ def base(request: Request):
     """
     Serve the default index.html file.
     """
-    with Response(request, content_type="text/html") as response:
-        response.send_file("index.html")
+
+    return FileResponse(request, "index.html", "/www")
 
 
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_methods.py

@@ -5,33 +5,66 @@
 import socketpool
 import wifi
 
-from adafruit_httpserver import Server, Request, Response, GET, POST, PUT, DELETE
+from adafruit_httpserver import Server, Request, JSONResponse, GET, POST, PUT, DELETE
 
 
 pool = socketpool.SocketPool(wifi.radio)
 server = Server(pool, debug=True)
 
+objects = [
+    {"id": 1, "name": "Object 1"},
+]
+
 
 @server.route("/api", [GET, POST, PUT, DELETE], append_slash=True)
 def api(request: Request):
     """
     Performs different operations depending on the HTTP method.
     """
 
+    # Get objects
     if request.method == GET:
-        # Get objects
-        with Response(request) as response:
-            response.send("Objects: ...")
+        return JSONResponse(request, objects)
 
+    # Upload or update objects
     if request.method in [POST, PUT]:
-        # Upload or update objects
-        with Response(request) as response:
-            response.send("Object uploaded/updated")
+        uploaded_object = request.json()
+
+        # Find object with same ID
+        for i, obj in enumerate(objects):
+            if obj["id"] == uploaded_object["id"]:
+                objects[i] = uploaded_object
+
+                return JSONResponse(
+                    request, {"message": "Object updated", "object": uploaded_object}
+                )
+
+        # If not found, add it
+        objects.append(uploaded_object)
+        return JSONResponse(
+            request, {"message": "Object added", "object": uploaded_object}
+        )
 
+    # Delete objects
     if request.method == DELETE:
-        # Delete objects
-        with Response(request) as response:
-            response.send("Object deleted")
+        deleted_object = request.json()
+
+        # Find object with same ID
+        for i, obj in enumerate(objects):
+            if obj["id"] == deleted_object["id"]:
+                del objects[i]
+
+                return JSONResponse(
+                    request, {"message": "Object deleted", "object": deleted_object}
+                )
+
+        # If not found, return error
+        return JSONResponse(
+            request, {"message": "Object not found", "object": deleted_object}
+        )
+
+    # If we get here, something went wrong
+    return JSONResponse(request, {"message": "Something went wrong"})
 
 
 server.serve_forever(str(wifi.radio.ipv4_address))