pydiagral 1.5.0b2__tar.gz → 1.5.0b5__tar.gz

pydiagral-1.5.0b5/CHANGELOG.md

@@ -0,0 +1,40 @@
+# [1.5.0-beta.5](https://github.com/mguyard/pydiagral/compare/v1.5.0-beta.4...v1.5.0-beta.5) (2025-03-01)
+
+
+### Bug Fixes
+
+* **api:** 🔧 Refactor API key handling and introduce new exceptions ([b1f6d06](https://github.com/mguyard/pydiagral/commit/b1f6d060e52c0c660e760c1dc86c5fa75613e4b2))
+
+# [1.5.0-beta.4](https://github.com/mguyard/pydiagral/compare/v1.5.0-beta.3...v1.5.0-beta.4) (2025-02-28)
+
+
+### Bug Fixes
+
+* **api:** 🔧 Update log message for alarm name retrieval ([fca40e4](https://github.com/mguyard/pydiagral/commit/fca40e44bccd59f6399ae2b89a29c2b4fcc80172))
+
+# [1.5.0-beta.3](https://github.com/mguyard/pydiagral/compare/v1.5.0-beta.2...v1.5.0-beta.3) (2025-02-28)
+
+
+### Features
+
+* **api:** 🚀 Add `get_alarm_name` method and log alarm name in tests ([96e727f](https://github.com/mguyard/pydiagral/commit/96e727fe851a1086d8689c6fb7204efdb702938d))
+
+# [1.5.0-beta.2](https://github.com/mguyard/pydiagral/compare/v1.5.0-beta.1...v1.5.0-beta.2) (2025-02-28)
+
+
+### Features
+
+* **api:** 🚀 Add connection testing functionality with result handling ([a07bbfc](https://github.com/mguyard/pydiagral/commit/a07bbfc22a1f41418dad0347394cadcab31685e8))
+
+# [1.5.0-beta.1](https://github.com/mguyard/pydiagral/compare/v1.4.0...v1.5.0-beta.1) (2025-02-28)
+
+
+### Features
+
+* **api:** 🚀 Add testing connection feature ([53981f6](https://github.com/mguyard/pydiagral/commit/53981f6bdb8b797b7f4408fbaf2264b66a58ab38))
+
+# 1.4.0 (2025-02-23)
+
+### Features
+
+- Initial Public release

{pydiagral-1.5.0b2 → pydiagral-1.5.0b5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydiagral
-Version: 1.5.0b2
+Version: 1.5.0b5
 Summary: A Python library for interacting with Diagral systems
 Project-URL: Homepage, https://github.com/mguyard/pydiagral
 Project-URL: Documentation, https://github.com/mguyard/pydiagral

{pydiagral-1.5.0b2 → pydiagral-1.5.0b5}/example_code.py

@@ -239,6 +239,9 @@ async def test_diagral_api() -> None:  # noqa: D103,C901
                 stop_result = await alarm.stop_system()
                 _LOGGER.info("Stop System with result: %s", stop_result)
 
+            alarm_name: str = await alarm.get_alarm_name()  # Get the alarm name
+            _LOGGER.info("Alarm Name is: %s", alarm_name)
+
             if (
                 APIKEY_DELETION and APIKEY_CREATION
             ):  # Only when the API key has been created

{pydiagral-1.5.0b2 → pydiagral-1.5.0b5}/src/pydiagral/api.py

@@ -16,6 +16,8 @@ import aiohttp
 
 from .constants import API_VERSION, BASE_URL
 from .exceptions import (
+    APIKeyCreationError,
+    APIValidationError,
     AuthenticationError,
     ClientError,
     ConfigurationError,
@@ -266,7 +268,8 @@ class DiagralAPI:
             ApiKeyWithSecret: An instance of ApiKeyWithSecret containing the created API key and secret key.
 
         Raises:
-            AuthenticationError: If the API key is not found in the response or if the created API key fails validation.
+            APIKeyCreationError: If the API key creation fails.
+            APIValidationError: If the API key validation fails.
 
         """
 
@@ -285,16 +288,16 @@ class DiagralAPI:
             set_apikey_response: ApiKeyWithSecret = ApiKeyWithSecret.from_dict(
                 response_data
             )
-            self.__apikey = set_apikey_response.api_key
+            self.__apikey: str = set_apikey_response.api_key
             if not self.__apikey:
                 error_msg = "API key not found in response"
                 _LOGGER.error(error_msg)
-                raise AuthenticationError(error_msg)
-            self.__secret_key = set_apikey_response.secret_key
+                raise APIKeyCreationError(error_msg)
+            self.__secret_key: str = set_apikey_response.secret_key
             if not self.__secret_key:
                 error_msg = "Secret key not found in response"
                 _LOGGER.error(error_msg)
-                raise AuthenticationError(error_msg)
+                raise APIKeyCreationError(error_msg)
 
             _LOGGER.info("Successfully created new API key: ...%s", self.__apikey[-4:])
             # Verify if the API key is valid
@@ -303,14 +306,14 @@ class DiagralAPI:
                 _LOGGER.info(
                     "Successfully verified new API key: ...%s", self.__apikey[-4:]
                 )
-            except AuthenticationError as e:
+            except APIValidationError as e:
                 _LOGGER.error("Created API key failed validation: %s", e)
                 self.__apikey = None
                 raise
         except DiagralAPIError as e:
             error_msg: str = f"Failed to create API key: {e!s}"
             _LOGGER.error(error_msg)
-            raise AuthenticationError(error_msg) from e
+            raise APIKeyCreationError(error_msg) from e
 
         return ApiKeyWithSecret(api_key=self.__apikey, secret_key=self.__secret_key)
 
@@ -329,6 +332,7 @@ class DiagralAPI:
 
         Raises:
             ConfigurationError: If no API key is provided or if the API key is invalid.
+            APIValidationError: If the API key is invalid or not found in the list of valid keys.
 
         """
 
@@ -357,7 +361,7 @@ class DiagralAPI:
         if is_valid:
             _LOGGER.info("API key successfully validated")
         else:
-            raise AuthenticationError(
+            raise APIValidationError(
                 "API key is invalid or not found in the list of valid keys"
             )
 
@@ -400,7 +404,7 @@ class DiagralAPI:
             self.__apikey = None
             self.__secret_key = None
 
-    async def try_connection(self, ephemeral: bool = True) -> bool:
+    async def try_connection(self, ephemeral: bool = True) -> TryConnectResult:
         """Test connection with the Diagral system.
 
         This method tests the connection by either using provided API credentials or generating
@@ -415,7 +419,14 @@ class DiagralAPI:
                 if non-ephemeral temporary keys were generated.
 
         Raises:
-            DiagralAPIError: If connection attempt fails or system status check fails.
+            APIKeyCreationError: If creation of temporary API keys fails
+            APIValidationError: If API key validation fails
+            SessionError: If the session is not initialized.
+            DiagralAPIError: If the request results in a 400 status code or other API errors.
+            AuthenticationError: If authentication fails or request results in a 401 or 403 status code.
+            ValidationError: If the request results in a 422 status code.
+            ServerError: If the request results in a 500 or 503 status code.
+            ClientError: If there is a network error.
 
         Note:
             If API credentials are not provided during client initialization, temporary
@@ -427,20 +438,25 @@ class DiagralAPI:
 
         result: TryConnectResult = TryConnectResult()
         api_keys_provided = bool(self.__apikey and self.__secret_key)
-        try:
-            # If API keys are not provided, generate temporary keys
-            if not api_keys_provided:
-                api_key_response: ApiKeyWithSecret = await self.set_apikey()
 
-            # Retrieve system status to validate connection
+        # If API keys are not provided, generate temporary keys
+        if not api_keys_provided:
+            api_key_response: ApiKeyWithSecret = await self.set_apikey()
+
+        # Retrieve system status to validate connection
+        try:
             await self.get_system_status()
-            # If connection is successful, clean up temporary keys if requested (ephemeral)
+        except DiagralAPIError:
             if ephemeral and not api_keys_provided:
                 await self.delete_apikey(apikey=self.__apikey)
-            elif not ephemeral and not api_keys_provided:
-                result.keys = api_key_response
-        except DiagralAPIError as e:
-            raise DiagralAPIError(f"Failed to connect to the system: {e}") from e
+            raise
+
+        # If connection is successful, clean up temporary keys if requested (ephemeral)
+        if ephemeral and not api_keys_provided:
+            await self.delete_apikey(apikey=self.__apikey)
+        elif not ephemeral and not api_keys_provided:
+            result.keys = api_key_response
+
         result.result = True
         return result
 
@@ -489,6 +505,28 @@ class DiagralAPI:
         )
         return self.alarm_configuration
 
+    async def get_alarm_name(self) -> str:
+        """Get the name of the alarm from the configuration.
+
+        Returns:
+            str: The name of the alarm from the configuration.
+
+        Raises:
+            ConfigurationError: If unable to retrieve the alarm configuration.
+
+        Note:
+            This method will attempt to fetch the configuration if it hasn't been loaded yet.
+
+        """
+
+        if not self.alarm_configuration:
+            await self.get_configuration()
+
+        if not self.alarm_configuration:
+            raise ConfigurationError("Failed to retrieve alarm configuration")
+
+        return self.alarm_configuration.alarm.name
+
     async def get_devices_info(self) -> DeviceList:
         """Asynchronously retrieves information about various device types from the alarm configuration.
 
@@ -580,17 +618,17 @@ class DiagralAPI:
             SystemStatus: An instance of SystemStatus containing the retrieved system status.
 
         Raises:
-            AuthenticationError: If the API key, secret key, or PIN code is not provided.
+            ConfigurationError: If the API key, secret key, or PIN code is not provided.
 
         """
 
         if not self.__apikey or not self.__secret_key:
-            raise AuthenticationError(
+            raise ConfigurationError(
                 "API key and secret key required to get system details"
             )
 
         if not self.__pincode:
-            raise AuthenticationError("PIN code required to get system details")
+            raise ConfigurationError("PIN code required to get system details")
 
         _TIMESTAMP = str(int(time.time()))
         _HMAC: str = generate_hmac_signature(

{pydiagral-1.5.0b2 → pydiagral-1.5.0b5}/src/pydiagral/exceptions.py

@@ -37,3 +37,11 @@ class ServerError(DiagralAPIError):
 
 class ClientError(DiagralAPIError):
     """Raised when client returns error."""
+
+
+class APIKeyCreationError(DiagralAPIError):
+    """Raised when API key creation fails."""
+
+
+class APIValidationError(DiagralAPIError):
+    """Raised when API validation fails."""

{pydiagral-1.5.0b2 → pydiagral-1.5.0b5}/tests/test_pydiagral_api.py

@@ -8,7 +8,12 @@ from unittest.mock import AsyncMock, patch
 
 import pytest
 
-from pydiagral.exceptions import ConfigurationError, DiagralAPIError
+from pydiagral.exceptions import (
+    APIKeyCreationError,
+    APIValidationError,
+    ConfigurationError,
+    DiagralAPIError,
+)
 
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../src")))
 import json
@@ -186,7 +191,7 @@ async def test_set_apikey(mock_request):
         pincode=PIN_CODE,
     ) as diagral:
         await diagral.login()
-        api_keys = await diagral.set_apikey()
+        api_keys: ApiKeyWithSecret = await diagral.set_apikey()
         assert isinstance(api_keys, ApiKeyWithSecret)
         assert api_keys.api_key == API_KEY
         assert api_keys.secret_key == SECRET_KEY
@@ -198,22 +203,22 @@ async def test_set_apikey_with_invalid_user_rights(mock_request):
     """Test the `set_apikey` method of the `DiagralAPI` class when the user has invalid permissions.
 
     This test simulates the scenario where a user with invalid permissions tries to set an API key.
-    It mocks the `mock_request` to raise an `AuthenticationError` indicating that the user does not have the right permissions.
+    It mocks the `mock_request` to raise an `APIKeyCreationError` indicating that the user does not have the right permissions.
 
     Args:
         mock_request (Mock): A mock object for simulating API requests.
 
     Raises:
-        AuthenticationError: If the user does not have the right permissions.
+        APIKeyCreationError: If the user does not have the right permissions.
 
     """
 
-    mock_request.side_effect = AuthenticationError(
+    mock_request.side_effect = APIKeyCreationError(
         "The user does not have the right permissions"
     )
     mock_request.side_effect = [
         ({"access_token": FAKE_TOKEN}, 200),  # Response for login
-        AuthenticationError(
+        APIKeyCreationError(
             "The user does not have the right permissions"
         ),  # Response for set_apikey
     ]
@@ -226,7 +231,7 @@ async def test_set_apikey_with_invalid_user_rights(mock_request):
         pincode=PIN_CODE,
     ) as diagral:
         await diagral.login()
-        with pytest.raises(AuthenticationError):
+        with pytest.raises(APIKeyCreationError):
             await diagral.set_apikey()
 
 
@@ -310,14 +315,14 @@ async def test_validate_apikey_not_existing(mock_request):
 
     This test mocks the responses for the login and validate_apikey requests. It first simulates a successful login
     response and then simulates a response for the validate_apikey request with a list of API keys that do not match
-    the provided API key. The test expects an `AuthenticationError` to be raised when the `validate_apikey` method
+    the provided API key. The test expects an `APIValidationError` to be raised when the `validate_apikey` method
     is called with a non-existing API key.
 
     Args:
         mock_request (MagicMock): A mock object to simulate HTTP requests and responses.
 
     Raises:
-        AuthenticationError: If the API key validation fails.
+        APIValidationError: If the API key validation fails.
 
     """
     mock_request.side_effect = [
@@ -336,7 +341,7 @@ async def test_validate_apikey_not_existing(mock_request):
         pincode=PIN_CODE,
     ) as diagral:
         await diagral.login()
-        with pytest.raises(AuthenticationError):
+        with pytest.raises(APIValidationError):
             await diagral.validate_apikey()
 
 
@@ -799,10 +804,10 @@ async def test_get_system_status_without_apikey(mock_request):
     1. Set up the mock responses for the login and get_system_status API calls.
     2. Create an instance of `DiagralAPI` with the provided credentials.
     3. Perform the login operation.
-    4. Attempt to get the system status and expect an `AuthenticationError` to be raised.
+    4. Attempt to get the system status and expect an `ConfigurationError` to be raised.
 
     Raises:
-        AuthenticationError: If the API key is not provided or invalid.
+        ConfigurationError: If the API key is not provided or invalid.
 
     """
     mock_request.side_effect = [
@@ -815,7 +820,7 @@ async def test_get_system_status_without_apikey(mock_request):
         pincode=PIN_CODE,
     ) as diagral:
         await diagral.login()
-        with pytest.raises(AuthenticationError):
+        with pytest.raises(ConfigurationError):
             await diagral.get_system_status()
 
 
@@ -840,10 +845,10 @@ async def test_get_system_status_without_pincode(mock_request):
         1. Create an instance of `DiagralAPI` with the provided credentials.
         2. Call the `login` method to authenticate and obtain an access token.
         3. Attempt to call the `get_system_status` method without providing a pincode.
-        4. Verify that an `AuthenticationError` is raised, indicating that a pincode is required.
+        4. Verify that an `ConfigurationError` is raised, indicating that a pincode is required.
 
     Expected Result:
-        - An `AuthenticationError` is raised when attempting to get the system status without a pincode.
+        - An `ConfigurationError` is raised when attempting to get the system status without a pincode.
 
     """
     mock_request.side_effect = [
@@ -857,7 +862,7 @@ async def test_get_system_status_without_pincode(mock_request):
         secret_key=SECRET_KEY,
     ) as diagral:
         await diagral.login()
-        with pytest.raises(AuthenticationError):
+        with pytest.raises(ConfigurationError):
             await diagral.get_system_status()
 
 

pydiagral-1.5.0b2/CHANGELOG.md

@@ -1,19 +0,0 @@
-# [1.5.0-beta.2](https://github.com/mguyard/pydiagral/compare/v1.5.0-beta.1...v1.5.0-beta.2) (2025-02-28)
-
-
-### Features
-
-* **api:** 🚀 Add connection testing functionality with result handling ([a07bbfc](https://github.com/mguyard/pydiagral/commit/a07bbfc22a1f41418dad0347394cadcab31685e8))
-
-# [1.5.0-beta.1](https://github.com/mguyard/pydiagral/compare/v1.4.0...v1.5.0-beta.1) (2025-02-28)
-
-
-### Features
-
-* **api:** 🚀 Add testing connection feature ([53981f6](https://github.com/mguyard/pydiagral/commit/53981f6bdb8b797b7f4408fbaf2264b66a58ab38))
-
-# 1.4.0 (2025-02-23)
-
-### Features
-
-- Initial Public release