Refactor API endpoints and add docstrings

Author: shauneccles

ledfx/api/__init__.py

@@ -63,6 +63,84 @@ async def json_decode_error(self) -> web.Response:
         }
         return web.json_response(data=response, status=400)
 
+    async def internal_error(self, type, msg) -> web.Response:
+        """
+        Handle messaging for internal errors.
+
+        Returns:
+            A web response with a JSON payload containing the error and a 500 status.
+        """
+        response = {
+            "status": "failed",
+            "payload": {"type": type, "reason": msg},
+        }
+        return web.json_response(data=response, status=500)
+
+    async def invalid_request(
+        self, reason="Invalid request", type="error", resp_code=200
+    ) -> web.Response:
+        """
+        Returns a JSON response indicating an invalid request.
+
+        Args:
+            reason (str): The reason for the invalid request. Defaults to 'Invalid request'.
+            type (str): The type of error. Defaults to 'error'. Options 'default','error', 'success', 'warning','info'.
+            resp_code (int): The response code to be returned. Defaults to 200 so that snackbar works.
+
+        Returns:
+            web.Response: A JSON response with the status and reason for the invalid request.
+        """
+        response = {
+            "status": "failed",
+            "payload": {
+                "type": type,
+                "reason": reason,
+            },
+        }
+        return web.json_response(data=response, status=resp_code)
+
+    async def request_success(
+        self, type=None, message=None, resp_code=200
+    ) -> web.Response:
+        """
+        Returns a JSON response indicating a successful request.
+        Optionally include a snackbar type and message to return to the user.
+
+        Args:
+            type (str): The type of snackbar to display. Defaults to None.
+            message (str): The message to display in the snackbar. Defaults to None.
+            resp_code (int): The response code to be returned. Defaults to 200.
+
+        Returns:
+            web.Response: A JSON response with the status and payload for the successful request.
+        """
+        response = {
+            "status": "success",
+        }
+        if type and message is not None:
+            response["payload"] = {
+                "type": type,
+                "reason": message,
+            }
+        return web.json_response(data=response, status=resp_code)
+
+    async def bare_request_success(self, payload) -> web.Response:
+        """
+        Returns a "bare" JSON response indicating a successful request - only a payload and a 200 code.
+
+        Args:
+            payload (dict): The payload to be returned.
+            resp_code (int): The response code to be returned. Defaults to 200.
+
+        Returns:
+            web.Response: A JSON response with the status and payload for the successful request.
+        """
+        if payload is None:
+            raise ValueError(
+                "Payload must be provided to the bare request_success method"
+            )
+        return web.json_response(data=payload, status=200)
+
 
 class RestApi(RegistryLoader):
     PACKAGE_NAME = "ledfx.api"

ledfx/api/audio_devices.py

@@ -18,43 +18,51 @@ class AudioDevicesEndpoint(RestEndpoint):
     _audio = None
 
     async def get(self) -> web.Response:
-        """Get list of audio devices using sound device"""
+        """
+        Get list of audio devices using sound device
 
+        Returns:
+            web.Response: The response containing the list of audio devices and the active device index.
+        """
         audio_config = AudioInputSource.AUDIO_CONFIG_SCHEMA.fget()(
-            self._ledfx.config.get("audio", {})
+            self._ledfx.config.get("audio_device", {})
         )
 
         response = {}
-        response["active_device_index"] = audio_config["device_index"]
+        response["active_device_index"] = audio_config["audio_device"]
         response[
             "devices"
         ] = AudioInputSource.input_devices()  # dict(enumerate(input_devices))
+        return await self.request_success(response)
 
-        return web.json_response(data=response, status=200)
+    async def put(self, request: web.Request) -> web.Response:
+        """
+        Set audio device to use as input.
 
-    async def put(self, request) -> web.Response:
-        """Set audio device to use as input"""
+        Args:
+            request (web.Request): The request object containing the new device `index`.
+
+        Returns:
+            web.Response: The HTTP response object.
+
+        """
         try:
             data = await request.json()
         except JSONDecodeError:
             return await self.json_decode_error()
 
         index = data.get("index")
         if index is None:
-            response = {
-                "status": "failed",
-                "reason": 'Required attribute "index" was not provided',
-            }
-            return web.json_response(data=response, status=400)
+            return await self.invalid_request(
+                reason="Required attribute 'index' was not provided"
+            )
 
         valid_indexes = AudioInputSource.valid_device_indexes()
 
         if index not in valid_indexes:
-            response = {
-                "status": "failed",
-                "reason": f"Invalid device index [{index}]",
-            }
-            return web.json_response(data=response, status=400)
+            return await self.invalid_request(
+                reason=f"Invalid device index [{index}]"
+            )
 
         # Update and save config
         new_config = self._ledfx.config.get("audio", {})
@@ -69,5 +77,4 @@ async def put(self, request) -> web.Response:
         if self._ledfx.audio:
             self._ledfx.audio.update_config(new_config)
 
-        response = {"status": "success"}
-        return web.json_response(data=response, status=200)
+        await self.request_success()

ledfx/api/colors.py

@@ -1,4 +1,5 @@
 import logging
+from json import JSONDecodeError
 
 from aiohttp import web
 
@@ -14,6 +15,9 @@ class ColorEndpoint(RestEndpoint):
     async def get(self) -> web.Response:
         """
         Get LedFx colors and gradients
+
+        Returns:
+            web.Response: The response containing the colors and gradients.
         """
         response = {
             "colors": dict(
@@ -23,41 +27,60 @@ async def get(self) -> web.Response:
                 zip(("builtin", "user"), self._ledfx.gradients.get_all())
             ),
         }
+        return await self.bare_request_success(response)
 
-        return web.json_response(data=response, status=200)
-
-    async def delete(self, request) -> web.Response:
+    async def delete(self, request: web.Request) -> web.Response:
         """
         Deletes a user defined color or gradient
         Request body is a string of the color key to delete
         eg. ["my_red_color"]
+
+        Parameters:
+        - request (web.Request): The HTTP request object
+
+        Returns:
+        - web.Response: The HTTP response object
         """
 
         data = await request.json()
 
         for key in data:
             del self._ledfx.colors[key]
             del self._ledfx.gradients[key]
+        return await self.request_success("success", "Deleted {key}")
 
-        response = {
-            "status": "success",
-            "payload": {
-                "type": "success",
-                "reason": "Deleted",
-            },
-        }
-
-        return web.json_response(data=response, status=200)
-
-    async def post(self, request) -> web.Response:
+    async def post(self, request: web.Request) -> web.Response:
         """
         Creates or updates existing colors or gradients.
-        eg. {"my_red_color": "#ffffff"}
-        or  {"my_cool_gradient": "lin..."}
-        """
 
-        data = await request.json()
+        Parameters:
+        - request (web.Request): The request containing the color or gradient to create or update.
+
+        Returns:
+        - web.Response: The HTTP response object.
 
+        Example:
+        ```
+        {
+            "my_red_color": "#ffffff"
+        }
+        ```
+        or
+        ```
+        {
+            "my_cool_gradient": "lin..."
+        }
+        """
+        try:
+            data = await request.json()
+        except JSONDecodeError:
+            return await self.json_decode_error()
+        if data is None:
+            return await self.invalid_request(
+                reason="Required attribute was not provided"
+            )
+
+        # TODO: Handle instances where neither color nor gradient is provided
         for key, val in data.items():
             try:
                 is_color = validate_color(val)
@@ -68,12 +91,4 @@ async def post(self, request) -> web.Response:
             else:
                 self._ledfx.gradients[key] = val
 
-        response = {
-            "status": "success",
-            "payload": {
-                "type": "success",
-                "reason": "Saved",
-            },
-        }
-
-        return web.json_response(data=response, status=200)
+        return await self.request_success("success", "Saved {key}")

ledfx/api/com_ports.py

@@ -12,11 +12,16 @@ class InfoEndpoint(RestEndpoint):
     ENDPOINT_PATH = "/api/comports"
 
     async def get(self) -> web.Response:
+        """
+        Get the list of available COM ports.
+
+        Returns:
+            web.Response: The response containing the list of available COM ports.
+        """
         ports = serial.tools.list_ports.comports()
 
         available_ports = []
 
         for p in ports:
             available_ports.append(p.device)
-
-        return web.json_response(data=available_ports, status=200)
+        return await self.bare_request_success(available_ports)