pydiagral 1.5.0b1__py3-none-any.whl → 1.5.0b4__py3-none-any.whl

pydiagral/api.py

@@ -36,6 +36,7 @@ from .models import (
     Rudes,
     SystemDetails,
     SystemStatus,
+    TryConnectResult,
     Webhook,
 )
 from .utils import generate_hmac_signature
@@ -399,49 +400,49 @@ class DiagralAPI:
             self.__apikey = None
             self.__secret_key = None
 
-    async def try_connection(self, ephemeral: bool = True) -> bool:
-        """Establish a connection with the Diagral system.
+    async def try_connection(self, ephemeral: bool = True) -> TryConnectResult:
+        """Test connection with the Diagral system.
 
-        This method tries to connect to the Diagral API by:
-        1. Checking if API keys are provided
-        2. If not, generating temporary API keys
-        3. Validating the connection by checking system status
-        4. Optionally cleaning up temporary keys if requested
+        This method tests the connection by either using provided API credentials or generating
+        temporary ones. It validates the connection by checking the system status.
 
         Args:
-            ephemeral (bool, optional): If True and using temporary API keys,
-                deletes them after validation. Defaults to True.
+            ephemeral (bool, optional): If True, temporary API keys will be deleted after
+                connection test. Defaults to True.
 
         Returns:
-            bool: True if connection is successful
+            TryConnectResult: Object containing connection test results and optionally API keys
+                if non-ephemeral temporary keys were generated.
 
         Raises:
-            DiagralAPIError: If connection fails or system status check fails
+            DiagralAPIError: If connection attempt fails or system status check fails.
+
+        Note:
+            If API credentials are not provided during client initialization, temporary
+            keys will be generated (if ephemeral) for the connection test. These keys will be:
+            - Deleted after the test if ephemeral=True
+            - Returned in the result if ephemeral=False
 
         """
 
+        result: TryConnectResult = TryConnectResult()
         api_keys_provided = bool(self.__apikey and self.__secret_key)
-        _LOGGER.warning("API keys provided: %s", api_keys_provided)
         try:
+            # If API keys are not provided, generate temporary keys
             if not api_keys_provided:
                 api_key_response: ApiKeyWithSecret = await self.set_apikey()
-                _LOGGER.debug(
-                    "TEST CONNECTION - Successfully created temporary API key : %s",
-                    api_key_response,
-                )
-                if await self.validate_apikey(apikey=api_key_response.api_key):
-                    _LOGGER.debug(
-                        "TEST CONNECTION - Successfully validated temporary API key"
-                    )
-                    self.__apikey: str = api_key_response.api_key
-                    self.__secret_key: str = api_key_response.secret_key
 
+            # Retrieve system status to validate connection
             await self.get_system_status()
+            # 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
         except DiagralAPIError as e:
             raise DiagralAPIError(f"Failed to connect to the system: {e}") from e
-        return True
+        result.result = True
+        return result
 
     async def get_configuration(self) -> None:
         """Asynchronously retrieve the configuration of the Diagral system.
@@ -488,6 +489,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.
 

pydiagral/models.py

@@ -355,6 +355,30 @@ class ApiKeys(CamelCaseModel):
         )
 
 
+@dataclass
+class TryConnectResult(CamelCaseModel):
+    """A class representing the result of an API connection attempt.
+
+    This class is used to store the result of an API connection attempt
+    and the associated API keys if the connection was successful.
+
+    Attributes:
+        result (bool | None): Whether the connection attempt was successful. Defaults to False.
+        keys (ApiKeyWithSecret | None): The API keys associated with the successful connection. Defaults to None.
+
+    Example:
+        >>> result = TryConnectResult(result=True, keys=api_key_obj)
+        >>> print(result.result)
+        True
+        >>> print(result.keys)
+        ApiKeyWithSecret(api_key='abc123', api_secret='xyz789')
+
+    """
+
+    result: bool | None = False
+    keys: ApiKeyWithSecret | None = None
+
+
 #####################################
 # Data models for alarm configuration
 #####################################

{pydiagral-1.5.0b1.dist-info → pydiagral-1.5.0b4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydiagral
-Version: 1.5.0b1
+Version: 1.5.0b4
 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.0b4.dist-info/RECORD

@@ -0,0 +1,10 @@
+pydiagral/__init__.py,sha256=4uM-RD2GQ6JYJkxu-D6wj3XpqfY5gN2hP8NF6WvRI9k,576
+pydiagral/api.py,sha256=ZshZu5NTSyjK7ozPYrXO6q94yjxnHt3h_boiGzRIUzk,49410
+pydiagral/constants.py,sha256=2B0TdKxQHA3cpIBxojo43bMW44wN9xKYsHbBRHWsaBk,119
+pydiagral/exceptions.py,sha256=Q5wEpNtiykLs3Ck0W8r1IQAJek_omaQ3jpMOtiiwBUg,1030
+pydiagral/models.py,sha256=vUjxuApjVaMtd7H6Iw5LarwABi30O4FfdObhZRbUNuc,54931
+pydiagral/utils.py,sha256=-VxI-lNaC4bU1K4DSmWDhvbsS2bXv5FAGULGKBf1UMU,449
+pydiagral-1.5.0b4.dist-info/METADATA,sha256=qurrNFVqrGxsuLKX9VJKPdtsW8ZhnA2A19rnC1voRPM,48531
+pydiagral-1.5.0b4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pydiagral-1.5.0b4.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+pydiagral-1.5.0b4.dist-info/RECORD,,

pydiagral-1.5.0b1.dist-info/RECORD

@@ -1,10 +0,0 @@
-pydiagral/__init__.py,sha256=4uM-RD2GQ6JYJkxu-D6wj3XpqfY5gN2hP8NF6WvRI9k,576
-pydiagral/api.py,sha256=LEDHEdf5wRd7QB7flsk3hnb2X_sf1325sD9DPDkBOhM,48587
-pydiagral/constants.py,sha256=2B0TdKxQHA3cpIBxojo43bMW44wN9xKYsHbBRHWsaBk,119
-pydiagral/exceptions.py,sha256=Q5wEpNtiykLs3Ck0W8r1IQAJek_omaQ3jpMOtiiwBUg,1030
-pydiagral/models.py,sha256=AKJd9ywPhislF5R685XNLvEpmJouFlkxWzz1pJXY4tA,54136
-pydiagral/utils.py,sha256=-VxI-lNaC4bU1K4DSmWDhvbsS2bXv5FAGULGKBf1UMU,449
-pydiagral-1.5.0b1.dist-info/METADATA,sha256=CudZesyW4jeyR1tR-N7K5tXVt4no-2nzY7voKEgaecc,48531
-pydiagral-1.5.0b1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pydiagral-1.5.0b1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-pydiagral-1.5.0b1.dist-info/RECORD,,