Added as_route decorator as shorthand for creating Route objects

Author: michalpokusa

adafruit_httpserver/__init__.py

@@ -61,7 +61,7 @@
     SSEResponse,
     Websocket,
 )
-from .route import Route
+from .route import Route, as_route
 from .server import Server
 from .status import (
     Status,

adafruit_httpserver/route.py

@@ -111,8 +111,55 @@ def match(self, other: "Route") -> Tuple[bool, Dict[str, str]]:
     def __repr__(self) -> str:
         path = repr(self.path)
         methods = repr(self.methods)
+        handler = repr(self.handler)
 
-        return f"Route(path={path}, methods={methods})"
+        return f"Route({path=}, {methods=}, {handler=})"
+
+
+def as_route(
+    path: str,
+    methods: Union[str, Set[str]] = GET,
+    *,
+    append_slash: bool = False,
+) -> "Callable[[Callable[..., Response]], Route]":
+    """
+    Decorator used to convert a function into a ``Route`` object.
+
+    It is a shorthand for manually creating a ``Route`` object, that can be used only one time
+    per function. Later it can be imported and registered in the ``Server``.
+
+    :param str path: URL path
+    :param str methods: HTTP method(s): ``"GET"``, ``"POST"``, ``["GET", "POST"]`` etc.
+    :param bool append_slash: If True, the route will be accessible with and without a
+        trailing slash
+
+    Example::
+
+        # Default method is GET
+        @as_route("/example")
+        def some_func(request):
+            ...
+
+        some_func  # Route(path="/example", methods={"GET"}, handler=<function some_func at 0x...>)
+
+        # If a route in another file, you can import it and register it to the server
+
+        from .routes import some_func
+
+        ...
+
+        server.add_routes([
+            some_func,
+        ])
+    """
+
+    def route_decorator(func: Callable) -> Route:
+        if isinstance(func, Route):
+            raise ValueError("as_route can be used only once per function.")
+
+        return Route(path, methods, func, append_slash=append_slash)
+
+    return route_decorator
 
 
 class _Routes:

examples/httpserver_neopixel.py

@@ -7,7 +7,7 @@
 import socketpool
 import wifi
 
-from adafruit_httpserver import Server, Route, Request, Response, GET, POST
+from adafruit_httpserver import Server, Route, as_route, Request, Response, GET, POST
 
 
 pool = socketpool.SocketPool(wifi.radio)
@@ -16,6 +16,7 @@
 pixel = neopixel.NeoPixel(board.NEOPIXEL, 1)
 
 
+# This is the simplest way to register a route. It uses the Server object in current scope.
 @server.route("/change-neopixel-color", GET)
 def change_neopixel_color_handler_query_params(request: Request):
     """Changes the color of the built-in NeoPixel using query/GET params."""
@@ -31,7 +32,9 @@ def change_neopixel_color_handler_query_params(request: Request):
     return Response(request, f"Changed NeoPixel to color ({r}, {g}, {b})")
 
 
-@server.route("/change-neopixel-color", POST)
+# This is another way to register a route. It uses the decorator that converts the function into
+# a Route object that can be imported and registered later.
+@as_route("/change-neopixel-color", POST)
 def change_neopixel_color_handler_post_body(request: Request):
     """Changes the color of the built-in NeoPixel using POST body."""
 
@@ -54,6 +57,13 @@ def change_neopixel_color_handler_post_json(request: Request):
     return Response(request, f"Changed NeoPixel to color ({r}, {g}, {b})")
 
 
+# You can always manually create a Route object and import or register it later.
+# Using this approach you can also use the same handler for multiple routes.
+post_json_route = Route(
+    "/change-neopixel-color/json", GET, change_neopixel_color_handler_post_json
+)
+
+
 def change_neopixel_color_handler_url_params(
     request: Request, r: str = "0", g: str = "0", b: str = "0"
 ):
@@ -66,17 +76,17 @@ def change_neopixel_color_handler_url_params(
     return Response(request, f"Changed NeoPixel to color ({r}, {g}, {b})")
 
 
-url_params_route = Route(
-    "/change-neopixel-color/<r>/<g>/<b>", GET, change_neopixel_color_handler_url_params
-)
-
-# Alternative way of registering routes.
+# Registering Route objects
 server.add_routes(
     [
+        change_neopixel_color_handler_post_body,
+        post_json_route,
+        # You can also register a inline created Route object
         Route(
-            "/change-neopixel-color/json", GET, change_neopixel_color_handler_post_json
+            path="/change-neopixel-color/<r>/<g>/<b>",
+            methods=GET,
+            handler=change_neopixel_color_handler_url_params,
         ),
-        url_params_route,
     ]
 )