Updated examples and added new ones hat present added functionality

Author: michalpokusa

adafruit_httpserver/server.py

@@ -43,14 +43,18 @@ def route(self, path: str, method: HTTPMethod = HTTPMethod.GET) -> Callable:
         """
         Decorator used to add a route.
 
-        :param str path: filename path
+        :param str path: URL path
         :param HTTPMethod method: HTTP method: HTTPMethod.GET, HTTPMethod.POST, etc.
 
         Example::
 
             @server.route("/example", HTTPMethod.GET)
             def route_func(request):
                 ...
+
+            @server.route("/example/<my_parameter>", HTTPMethod.GET)
+            def route_func(request, my_parameter):
+                ...
         """
 
         def route_decorator(func: Callable) -> Callable:

docs/examples.rst

@@ -36,7 +36,8 @@ Change NeoPixel color
 If you want your code to do more than just serve web pages,
 use the start/poll methods as shown in this example.
 
-For example by going to ``/change-neopixel-color?r=255&g=0&b=0`` you can change the color of the NeoPixel to red.
+For example by going to ``/change-neopixel-color?r=255&g=0&b=0`` or ``/change-neopixel-color/255/0/0``
+you can change the color of the NeoPixel to red.
 Tested on ESP32-S2 Feather.
 
 .. literalinclude:: ../examples/httpserver_neopixel.py
@@ -62,3 +63,28 @@ To use it, you need to set the ``chunked=True`` when creating a ``HTTPResponse``
 .. literalinclude:: ../examples/httpserver_chunked.py
     :caption: examples/httpserver_chunked.py
     :linenos:
+
+URL parameters
+---------------------
+
+Alternatively to using query parameters, you can use URL parameters.
+
+In order to use URL parameters, you need to wrap them inside ``<>`` in ``HTTPServer.route``, e.g. ``<my_parameter>``.
+
+All URL parameters are passed as positional arguments to the handler function, in order they are specified.
+
+Notice how the handler function in example below accepts two additional arguments : ``device_id`` and ``action``.
+
+If you specify multiple routes for single handler function and they have different number of URL parameters,
+make sure to add default values for all the ones that might not be passed.
+In the example below the second route has only one URL parameter, so the ``action`` parameter has a default value of ``None``.
+
+Keep in mind that URL parameters are always passed as strings, so you need to convert them to the desired type.
+Also note that the names of the function parameters **do not have to match** with the ones used in route, but they **must** be in the same order.
+Look at the example below to see how the ``route_param_1`` and ``route_param_1`` are named differently in the handler function.
+
+Although it is possible, it makes more sens be consistent with the names of the parameters in the route and in the handler function.
+
+.. literalinclude:: ../examples/httpserver_url_parameters.py
+    :caption: examples/httpserver_url_parameters.py
+    :linenos:

examples/httpserver_neopixel.py

@@ -28,9 +28,9 @@
 
 
 @server.route("/change-neopixel-color")
-def change_neopixel_color_handler(request: HTTPRequest):
+def change_neopixel_color_handler_query_params(request: HTTPRequest):
     """
-    Changes the color of the built-in NeoPixel.
+    Changes the color of the built-in NeoPixel using query/GET params.
     """
     r = request.query_params.get("r")
     g = request.query_params.get("g")
@@ -42,5 +42,18 @@ def change_neopixel_color_handler(request: HTTPRequest):
         response.send(f"Changed NeoPixel to color ({r}, {g}, {b})")
 
 
+@server.route("/change-neopixel-color/<r>/<g>/<b>")
+def change_neopixel_color_handler_url_params(
+    request: HTTPRequest, r: str, g: str, b: str
+):
+    """
+    Changes the color of the built-in NeoPixel using URL params.
+    """
+    pixel.fill((int(r or 0), int(g or 0), int(b or 0)))
+
+    with HTTPResponse(request, content_type=MIMEType.TYPE_TXT) as response:
+        response.send(f"Changed NeoPixel to color ({r}, {g}, {b})")
+
+
 print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_url_parameters.py

@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import secrets  # pylint: disable=no-name-in-module
+
+import socketpool
+import wifi
+
+from adafruit_httpserver.mime_type import MIMEType
+from adafruit_httpserver.request import HTTPRequest
+from adafruit_httpserver.response import HTTPResponse
+from adafruit_httpserver.server import HTTPServer
+
+
+ssid, password = secrets.WIFI_SSID, secrets.WIFI_PASSWORD  # pylint: disable=no-member
+
+print("Connecting to", ssid)
+wifi.radio.connect(ssid, password)
+print("Connected to", ssid)
+
+pool = socketpool.SocketPool(wifi.radio)
+server = HTTPServer(pool)
+
+
+class Device:
+    def turn_on(self):
+        raise NotImplementedError
+
+    def turn_off(self):
+        raise NotImplementedError
+
+
+def get_device(device_id: str) -> Device:  # pylint: disable=unused-argument
+    """
+    This is a **made up** function that returns a `Device` object.
+    """
+    return Device()
+
+
+@server.route("/device/<device_id>/action/<action>")
+@server.route("/device/emergency-power-off/<device_id>")
+def perform_action(request: HTTPRequest, device_id: str, action: str = None):
+    """
+    Performs an "action" on a specified device.
+    """
+
+    device = get_device(device_id)
+
+    if action == "turn_on":
+        device.turn_on()
+    elif action == "turn_off" or action is None:
+        device.turn_off()
+
+    with HTTPResponse(request, content_type=MIMEType.TYPE_TXT) as response:
+        response.send(f"Action ({action}) performed on device with ID: {device_id}")
+
+
+@server.route("/something/<route_param_1>/<route_param_2>")
+def different_name_parameters(
+    request: HTTPRequest,
+    handler_param_1: str,  #  pylint: disable=unused-argument
+    handler_param_2: str = None,  #  pylint: disable=unused-argument
+):
+    """
+    Presents that the parameters can be named anything.
+
+    ``route_param_1`` -> ``handler_param_1``
+    ``route_param_2`` -> ``handler_param_2``
+    """
+
+    with HTTPResponse(request, content_type=MIMEType.TYPE_TXT) as response:
+        response.send("200 OK")
+
+
+print(f"Listening on http://{wifi.radio.ipv4_address}:80")
+server.serve_forever(str(wifi.radio.ipv4_address))