SMART Attribute added

Author: vitals5

custom_components/scrutiny/api.py

@@ -8,12 +8,10 @@
 
 import aiohttp  # For making HTTP requests
 
-from .const import LOGGER  # Integration-specific logger
-
-# Custom exception classes for Scrutiny API interactions.
-# These allow for more specific error handling in the coordinator and config flow.
+from .const import ATTR_METADATA, LOGGER  # Integration-specific logger
 
 
+# Custom exception classes for Scrutiny API interactions.
 class ScrutinyApiError(Exception):
     """Generic base exception for Scrutiny API errors."""
 
@@ -29,51 +27,31 @@ class ScrutinyApiConnectionError(ScrutinyApiError):
 class ScrutinyApiAuthError(ScrutinyApiError):
     """Exception raised for authentication errors with the Scrutiny API."""
 
-    # Note: The /api/summary endpoint currently does not require authentication.
-    # This is included for completeness or future Scrutiny API changes.
-
 
 class ScrutinyApiResponseError(ScrutinyApiError):
     """
     Exception raised for issues with the Scrutiny API's response.
 
-    This includes unexpected data formats, or if the API itself indicates an error
-    (e.g., `success: false` in the response).
+    This includes unexpected data formats, or if the API itself indicates an error.
     """
 
 
 def _construct_api_exception_message(
     base_message: str, url: str | None = None, error: Exception | None = None
 ) -> str:
-    """
-    Construct a standardized and informative message for API-related exceptions.
-
-    Args:
-        base_message: The core message for the exception.
-        url: The URL that was being accessed, if applicable.
-        error: The original exception that caused this, if applicable.
-
-    Returns:
-        A formatted exception message string.
-
-    """
+    """Construct a standardized and informative message for API-related exceptions."""
     message = base_message
     if url:
         message += f" at {url}"
     if error:
-        # Use !s for safe string conversion of the original error.
         message += f": {error!s}"
     return message
 
 
-# Helper functions to raise specific API errors, primarily for Ruff's TRY301 compliance.
-# These ensure that 'raise ... from ...' statements are encapsulated.
-
-
 def _raise_scrutiny_api_response_error(
     message: str, original_exception: Exception
 ) -> NoReturn:
-    """Construct and raise a ScrutinyApiResponseError, chaining the original excep."""
+    """Construct and raise a ScrutinyApiResponseError, chaining the orig exception."""
     raise ScrutinyApiResponseError(message) from original_exception
 
 
@@ -86,15 +64,7 @@ class ScrutinyApiClient:
     """Client to interact with the Scrutiny API."""
 
     def __init__(self, host: str, port: int, session: aiohttp.ClientSession) -> None:
-        """
-        Initialize the API client.
-
-        Args:
-            host: The hostname or IP address of the Scrutiny server.
-            port: The port number the Scrutiny server is listening on.
-            session: The aiohttp.ClientSession to use for requests (provided by HA).
-
-        """
+        """Initialize the API client."""
         self._host = host
         self._port = port
         self._session = session
@@ -103,170 +73,113 @@ def __init__(self, host: str, port: int, session: aiohttp.ClientSession) -> None
     async def _request(
         self, method: str, endpoint: str, **kwargs: Any
     ) -> aiohttp.ClientResponse:
-        """
-        Make a generic HTTP request to a Scrutiny API endpoint.
-
-        Handles common request logic, timeouts, and basic error conversion.
-
-        Args:
-            method: The HTTP method (e.g., "get", "post").
-            endpoint: The API endpoint path (e.g., "summary").
-            **kwargs: Additional keyword arguments to pass to aiohttp's request method.
-
-        Returns:
-            The aiohttp.ClientResponse object on success.
-
-        Raises:
-            ScrutinyApiConnectionError: If a conn. error (timeout, DNS failure) occurs.
-            ScrutinyApiAuthError: If an authentication error (401, 403) occurs.
-            ScrutinyApiResponseError: If the API returns error statuses (4xx, 5xx).
-
-        """
+        """Make a generic HTTP request to a Scrutiny API endpoint."""
         url = f"{self._base_url}/{endpoint}"
         LOGGER.debug("Requesting Scrutiny data: %s %s", method, url)
 
         try:
-            # Use a timeout for the request to prevent indefinite blocking.
-            async with asyncio.timeout(10):  # 10-second timeout
+            async with asyncio.timeout(10):
                 response = await self._session.request(
                     method,
                     url,
-                    ssl=False,  # Assuming Scrutiny runs on HTTP by default
+                    ssl=False,
                     **kwargs,
                 )
-                # Raise an aiohttp.ClientResponseError for bad HTTP codes (4xx or 5xx).
                 response.raise_for_status()
                 return response
         except TimeoutError as exc:
-            # Handle request timeout specifically.
             msg = _construct_api_exception_message(
                 "Timeout connecting to Scrutiny", url
             )
             raise ScrutinyApiConnectionError(msg) from exc
         except aiohttp.ClientConnectionError as exc:
-            # Handle lower-level errors (DNS resolution failed, connection refused).
             msg = _construct_api_exception_message(
                 "Connection error with Scrutiny", url
             )
             raise ScrutinyApiConnectionError(msg) from exc
         except aiohttp.ClientResponseError as exc:
-            # Handle HTTP errors reported by the server (4xx, 5xx status codes).
             LOGGER.error(
                 "HTTP error from Scrutiny API at %s: %s (status: %s)",
                 url,
                 exc.message,
                 exc.status,
             )
-            if exc.status in (401, 403):  # Example for potential future authentication
+            if exc.status in (401, 403):
                 auth_msg = _construct_api_exception_message(
                     f"Authentication error with Scrutiny ({exc.status})", error=exc
                 )
                 raise ScrutinyApiAuthError(auth_msg) from exc
 
-            # For other HTTP errors, raise a generic response error.
             api_err_msg = _construct_api_exception_message(
                 f"Scrutiny API returned an error ({exc.status})", error=exc
             )
-            _raise_scrutiny_api_response_error(api_err_msg, exc)  # Use helper
+            _raise_scrutiny_api_response_error(api_err_msg, exc)
         except aiohttp.ClientError as exc:
-            # Catch other, more generic aiohttp client errors.
             generic_msg = _construct_api_exception_message(
                 "A client error occurred with Scrutiny", url
             )
             raise ScrutinyApiConnectionError(generic_msg) from exc
 
     async def async_get_summary(self) -> dict[str, dict]:
-        """
-        Fetch the summary data from the Scrutiny '/api/summary' endpoint.
-
-        This endpoint provides an overview of all monitored disks.
-
-        Returns:
-            A dictionary containing the 'summary' data, where keys are disk WWNs
-            and values are objects with 'device' and 'smart' details.
-
-        Raises:
-            ScrutinyApiResponseError: If the API response is not valid JSON,
-                                     if `success` is not true, or if the expected
-                                     data structure ('data.summary') is missing.
-            ScrutinyApiError: For other unexpected processing errors.
-            (Inherits connection errors from _request method)
-
-        """
-        response: aiohttp.ClientResponse | None = (
-            None  # Ensure response is defined for except block
-        )
+        """Fetch the summary data from the Scrutiny '/api/summary' endpoint."""
+        response: aiohttp.ClientResponse | None = None
         try:
             response = await self._request("get", "summary")
             content_type = response.headers.get("Content-Type", "")
 
             if "application/json" not in content_type:
-                # If the content type is not JSON, log the issue and raise an error.
                 text_response = await response.text()
                 LOGGER.error(
-                    "Unexpected content type from Scrutiny API: %s. Response: %s",
+                    """Unexpected content type from
+                      Scrutiny API (summary): %s. Response: %s""",
                     content_type,
-                    text_response[:200],  # Log only a snippet of the response
+                    text_response[:200],
                 )
-                msg = f"Expected JSON from Scrutiny, got {content_type}"
-                # This raise is in the try-block, not an except-block.
-                # Ruff TRY301 should not apply here typically, but if it does:
+                msg = f"Expected JSON from Scrutiny summary, got {content_type}"
                 raise ScrutinyApiResponseError(msg)  # noqa: TRY301
 
-            # Attempt to parse the JSON response.
             data: dict = await response.json()
 
         except json.JSONDecodeError as exc:
-            # Handle cases where the response claims to be JSON but isn't valid.
-            raw_response_text = "Could not retrieve raw response."
+            raw_response_text = "Could not retrieve raw response for summary."
             if response:
                 try:
                     raw_response_text = await response.text()
                     LOGGER.error(
-                        "Failed to decode JSON from Scrutiny. Raw response: %s",
-                        raw_response_text[:500],  # Log a larger snippet for debugging
+                        "Failed to decode JSON from Scrutiny summary. Raw response: %s",
+                        raw_response_text[:500],
                     )
                 # pylint: disable=broad-except
-                except Exception:  # noqa: BLE001 - Catching broad exception during error handling
+                except Exception:  # noqa: BLE001
                     LOGGER.error(
-                        "Failed to decode JSON and also fail to get raw text response."
+                        """Failed to decode JSON for summary
+                         and also failed to get raw text."""
                     )
             else:
                 LOGGER.error(
-                    "Failed to decode JSON, and no response object was available."
+                    """Failed to decode JSON for summary,
+                     no response object was available."""
                 )
 
-            msg = "Invalid JSON response received from Scrutiny"
-            _raise_scrutiny_api_response_error(msg, exc)  # Use helper
-
-        # Re-raise ScrutinyApiError or its subclasses if they were already caught
-        # and processed (e.g., by _request).
+            msg = "Invalid JSON response received from Scrutiny summary"
+            _raise_scrutiny_api_response_error(msg, exc)
         except ScrutinyApiError:
             raise
-
-        # Catch any other unexpected exceptions during the summary processing.
         # pylint: disable=broad-except
-        except Exception as exc:  # noqa: BLE001 - Intentional broad catch for API client robustness
+        except Exception as exc:  # noqa: BLE001
             LOGGER.exception(
                 "An unexpected error occurred while processing Scrutiny summary data"
             )
             msg = "Unexpected error occurred while processing Scrutiny summary"
-            _raise_scrutiny_api_error(msg, exc)  # Use helper
-
-        # This 'else' block executes only if the 'try' block completes without except.
+            _raise_scrutiny_api_error(msg, exc)
         else:
-            LOGGER.debug(
-                "Scrutiny API response data: %s", str(data)[:1000]
-            )  # Log snippet of data
+            LOGGER.debug("Scrutiny API summary response data: %s", str(data)[:1000])
 
-            # Validate the structure of the successful JSON response.
             if not isinstance(data, dict) or not data.get("success"):
                 err_msg = (
-                    """Scrutiny API call not successful or
-                    response format is unexpected: """
-                    f"{str(data)[:200]}"  # Include a snippet of the problematic data
+                    "Scrutiny API summary call not successful or unexpected format: "
+                    f"{str(data)[:200]}"
                 )
-                # This raise is part of data validation, not an except block.
                 raise ScrutinyApiResponseError(err_msg)
 
             summary_data = data.get("data", {}).get("summary")
@@ -278,3 +191,79 @@ async def async_get_summary(self) -> dict[str, dict]:
                 raise ScrutinyApiResponseError(err_msg)
 
             return summary_data
+
+    async def async_get_device_details(
+        self, wwn: str
+    ) -> dict[str, Any]:  # Rückgabetyp ist jetzt das "Gesamtobjekt"
+        """
+        Fetch detailed information for a specific disk from Scrutiny.
+
+        Args:
+            wwn: The World Wide Name of the disk.
+
+        Returns:
+            A dictionary representing the entire successful JSON response,
+            which should contain 'data' (with device, smart_results)
+            and 'metadata' keys.
+
+        Raises:
+            ScrutinyApiResponseError: If API response is not valid JSON,
+                                     if `success` is not true.
+            (Inherits connection errors from _request method)
+
+        """
+        endpoint = f"device/{wwn}/details"
+        response: aiohttp.ClientResponse | None = None
+        LOGGER.debug("Requesting Scrutiny device details for WWN: %s", wwn)
+
+        try:
+            response = await self._request("get", endpoint)
+            content_type = response.headers.get("Content-Type", "")
+
+            if "application/json" not in content_type:
+                msg = f"Expected JSON from Scrutiny device details, got {content_type}"
+                raise ScrutinyApiResponseError(msg)  # noqa: TRY301
+
+            # full_api_response_data ist jetzt die gesamte Antwort,
+            # z.B. {"data": {...}, "metadata": {...}, "success": true}
+            full_api_response_data: dict = await response.json()
+
+        except json.JSONDecodeError as exc:
+            msg = f"""Invalid JSON response received from
+              Scrutiny device details (WWN: {wwn})"""
+            _raise_scrutiny_api_response_error(msg, exc)
+        except ScrutinyApiError:
+            raise
+        except Exception as exc:  # noqa: BLE001 pylint: disable=broad-except
+            msg = f"Unexpected error processing Scrutiny device details (WWN: {wwn})"
+            _raise_scrutiny_api_error(msg, exc)
+        else:
+            LOGGER.debug(
+                "Scrutiny API device details FULL response for WWN %s: %s",
+                wwn,
+                str(full_api_response_data)[:2000],
+            )
+
+            if not isinstance(
+                full_api_response_data, dict
+            ) or not full_api_response_data.get("success"):
+                err_msg = (
+                    """Scrutiny API device details call
+                      not successful or unexpected format """
+                    f"(WWN: {wwn}): {str(full_api_response_data)[:200]}"
+                )
+                raise ScrutinyApiResponseError(err_msg)
+
+            if (
+                "data" not in full_api_response_data
+                or ATTR_METADATA not in full_api_response_data
+            ):  # ATTR_METADATA ist "metadata"
+                err_msg = (
+                    """Scrutiny API device details response
+                      is missing 'data' or 'metadata' key """
+                    f"(WWN: {wwn}): Keys present: {list(full_api_response_data.keys())}"
+                )
+                LOGGER.error(err_msg)
+                raise ScrutinyApiResponseError(err_msg)
+
+            return full_api_response_data