pydiagral 1.5.0b1__tar.gz → 1.5.0b2__tar.gz

{pydiagral-1.5.0b1 → pydiagral-1.5.0b2}/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydiagral
-Version: 1.5.0b1
+Version: 1.5.0b2
 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.0b1 → pydiagral-1.5.0b2}/example_code.py

@@ -9,6 +9,7 @@ from pydiagral.models import (
     ApiKeyWithSecret,
     SystemDetails,
     SystemStatus,
+    TryConnectResult,
     Webhook,
 )
 from src.pydiagral import DiagralAPI, DiagralAPIError
@@ -22,7 +23,7 @@ logging.basicConfig(
     level=getattr(logging, log_level, logging.INFO),
     format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
 )
-logger: logging.Logger = logging.getLogger(__name__)
+_LOGGER: logging.Logger = logging.getLogger(__name__)
 
 # Connection information (replace with your own data)
 # For this, create a .env file in the root of the project with the following content:
@@ -47,9 +48,11 @@ WEBHOOK_URL: str | None = os.getenv("WEBHOOK_URL")  # Optional
 #   Switch to True the actions you want to test
 TRY_CONNECTION_WITH_KEYS = False
 TRY_CONNECTION_WITHOUT_KEYS = False
-APIKEY_CREATION = True
-APIKEY_DELETION = True
-LIST_GROUPS = True
+TRY_CONNECTION_WITH_KEYS_EPHEMERAL = False
+TRY_CONNECTION_WITHOUT_KEYS_EPHEMERAL = False
+APIKEY_CREATION = False
+APIKEY_DELETION = False
+LIST_GROUPS = False
 LIST_SYSTEM_DETAILS = False
 LIST_SYSTEM_STATUS = False
 LIST_SYSTEM_CONFIGURATION = False
@@ -62,12 +65,16 @@ TEST_PARTIAL_ACTIONS = False
 
 ######################################## DON'T MODIFY BELOW THIS LINE ########################################
 
-if APIKEY_CREATION or TRY_CONNECTION_WITHOUT_KEYS:
+if (
+    APIKEY_CREATION
+    or TRY_CONNECTION_WITHOUT_KEYS
+    or TRY_CONNECTION_WITHOUT_KEYS_EPHEMERAL
+):
     API_KEY = None
     SECRET_KEY = None
 
 
-async def test_diagral_api() -> None:  # noqa: D103
+async def test_diagral_api() -> None:  # noqa: D103,C901
     try:
         # Initialization of the DiagralAPI object
         diagral = DiagralAPI(
@@ -78,47 +85,76 @@ async def test_diagral_api() -> None:  # noqa: D103
             secret_key=SECRET_KEY,
             pincode=PIN_CODE,
         )
-        logger.info("Initialisation de DiagralAPI réussie")
+        _LOGGER.info("Initialisation de DiagralAPI réussie")
 
         # Connection to the Diagral API
         async with diagral as alarm:
-            logger.info("Connection to the Diagral API successful")
+            _LOGGER.info("Connection to the Diagral API successful")
             if APIKEY_CREATION and (not API_KEY or not SECRET_KEY):
                 await alarm.login()  # Login to the API
                 # await asyncio.sleep(3700) # Wait for the access token to expire
                 api_keys: ApiKeyWithSecret = (
                     await alarm.set_apikey()
                 )  # Create a new API key
-                logger.info("API Key: %s", api_keys.api_key)  # Display the API key
-                logger.info(
+                _LOGGER.info("API Key: %s", api_keys.api_key)  # Display the API key
+                _LOGGER.info(
                     "Secret Key: %s", api_keys.secret_key
                 )  # Display the secret key
                 await (
                     alarm.validate_apikey()
                 )  # Validate the API key - Optional as already done in set_apikey
 
+            if TRY_CONNECTION_WITH_KEYS:
+                connection: TryConnectResult = await alarm.try_connection(
+                    ephemeral=False
+                )  # Try to connect to the API with keys
+                if connection.result:
+                    _LOGGER.info("Connection (with provided keys) successful")
+                else:
+                    _LOGGER.error("Connection (with provided keys) failed")
+
             if TRY_CONNECTION_WITHOUT_KEYS:
-                result: bool = await alarm.try_connection(
+                connection: TryConnectResult = await alarm.try_connection(
+                    ephemeral=False
+                )  # Try to connect to the API with keys
+                if connection.result:
+                    _LOGGER.info("Connection (with provided keys) successful")
+                    _LOGGER.info("Generated keys are : %s", connection.keys)
+                    _LOGGER.info("Running cleanup by deleting the generated keys")
+                    await alarm.delete_apikey(connection.keys.api_key)  # For cleanup
+                else:
+                    _LOGGER.error("Connection (with provided keys) failed")
+
+            if TRY_CONNECTION_WITH_KEYS_EPHEMERAL:
+                connection: TryConnectResult = await alarm.try_connection(
                     ephemeral=True
                 )  # Try to connect to the API without keys
-                if result:
-                    logger.info("Connection (without provided keys) successful")
+                if connection.result:
+                    if connection.keys is not None:
+                        _LOGGER.warning(
+                            "Keys was returned. Not a normal behavior as keys was provided"
+                        )
+                    _LOGGER.info("Connection (without provided keys) successful")
                 else:
-                    logger.error("Connection (without provided keys) failed")
+                    _LOGGER.error("Connection (without provided keys) failed")
 
-            if TRY_CONNECTION_WITH_KEYS:
-                result = await alarm.try_connection(
-                    ephemeral=False
-                )  # Try to connect to the API with keys
-                if result:
-                    logger.info("Connection (with provided keys) successful")
+            if TRY_CONNECTION_WITHOUT_KEYS_EPHEMERAL:
+                connection: TryConnectResult = await alarm.try_connection(
+                    ephemeral=True
+                )  # Try to connect to the API without keys
+                if connection.result:
+                    if connection.keys is not None:
+                        _LOGGER.warning(
+                            "Keys was returned. Not a normal behavior as keys was provided"
+                        )
+                    _LOGGER.info("Connection (without provided keys) successful")
                 else:
-                    logger.error("Connection (with provided keys) failed")
+                    _LOGGER.error("Connection (without provided keys) failed")
 
             if LIST_GROUPS:
                 await alarm.get_devices_info()
                 for group in alarm.alarm_configuration.groups:
-                    logger.info(
+                    _LOGGER.info(
                         "Group %i: %s",
                         group.index,
                         group.name,
@@ -128,80 +164,80 @@ async def test_diagral_api() -> None:  # noqa: D103
                 system_details: SystemDetails = (
                     await alarm.get_system_details()
                 )  # Get the system details
-                logger.info("System Details: %s", system_details)
+                _LOGGER.info("System Details: %s", system_details)
 
             if LIST_SYSTEM_STATUS:
                 system_status: SystemStatus = (
                     await alarm.get_system_status()
                 )  # Get the system status
-                logger.info("System Status: %s", system_status)
+                _LOGGER.info("System Status: %s", system_status)
 
             if LIST_SYSTEM_CONFIGURATION:
                 if not alarm.alarm_configuration:
                     await alarm.get_configuration()  # Get the configuration
-                logger.info(
+                _LOGGER.info(
                     "System Configuration: %s",
                     alarm.alarm_configuration.grp_marche_partielle2,
                 )
 
             if WEHBOOK_REGISTRATION and WEBHOOK_URL:
-                logger.info("-----> WEBHOOK <-----")
+                _LOGGER.info("-----> WEBHOOK <-----")
                 webhook_register_output: Webhook | None = await alarm.register_webhook(
                     webhook_url=WEBHOOK_URL,
                     subscribe_to_anomaly=True,
                     subscribe_to_alert=True,
                     subscribe_to_state=True,
                 )
-                logger.info("Webhook Register Output: %s", webhook_register_output)
+                _LOGGER.info("Webhook Register Output: %s", webhook_register_output)
                 webhook_update_output: Webhook | None = await alarm.update_webhook(
                     webhook_url=WEBHOOK_URL,
                     subscribe_to_anomaly=True,
                     subscribe_to_alert=True,
                     subscribe_to_state=True,
                 )
-                logger.info("Webhook Update Output: %s", webhook_update_output)
+                _LOGGER.info("Webhook Update Output: %s", webhook_update_output)
                 if WEBHOOK_DELETION:
                     await alarm.delete_webhook()
                     webhook_sub: Webhook = await alarm.get_webhook()
 
-                logger.info("Webhook Subscription: %s", webhook_sub)
+                _LOGGER.info("Webhook Subscription: %s", webhook_sub)
 
             if GET_ANOMALIES:
-                logger.info("-----> ANOMALIES <-----")
+                _LOGGER.info("-----> ANOMALIES <-----")
                 anomalies: Anomalies | dict = await alarm.get_anomalies()
-                logger.info("Anomalies: %s", anomalies)
+                _LOGGER.info("Anomalies: %s", anomalies)
 
             if TEST_FULL_ACTIONS:
                 start_result: SystemStatus = (
                     await alarm.start_system()
                 )  # Start the system
-                logger.info("Start System with result: %s", start_result)
+                _LOGGER.info("Start System with result: %s", start_result)
                 await asyncio.sleep(30)  # Wait for 30 seconds
                 stop_result: SystemStatus = await alarm.stop_system()  # Stop the system
-                logger.info("Stop System with result: %s", stop_result)
+                _LOGGER.info("Stop System with result: %s", stop_result)
 
             if TEST_PRESENCE:
                 presence_result: SystemStatus = (
                     await alarm.presence()
                 )  # Activate the presence mode
-                logger.info("Presence with result: %s", presence_result)
+                _LOGGER.info("Presence with result: %s", presence_result)
                 await asyncio.sleep(30)  # Wait for 30 seconds
                 stop_result = await alarm.stop_system()  # Stop the system
-                logger.info("Stop System with result: %s", stop_result)
+                _LOGGER.info("Stop System with result: %s", stop_result)
 
             if TEST_PARTIAL_ACTIONS:
                 activategroup_result: SystemStatus = await alarm.activate_group(
                     groups=[1, 2]
                 )
-                logger.info("Activate Group with result: %s", activategroup_result)
+                _LOGGER.info("Activate Group with result: %s", activategroup_result)
                 await asyncio.sleep(30)  # Wait for 30 seconds
                 disablegroup_result: SystemStatus = await alarm.disable_group(
                     groups=[2]
                 )
-                logger.info("Disable Group with result: %s", disablegroup_result)
+                _LOGGER.info("Disable Group with result: %s", disablegroup_result)
                 await asyncio.sleep(30)  # Wait for 30 seconds
                 stop_result = await alarm.stop_system()
-                logger.info("Stop System with result: %s", stop_result)
+                _LOGGER.info("Stop System with result: %s", stop_result)
 
             if (
                 APIKEY_DELETION and APIKEY_CREATION
@@ -209,7 +245,7 @@ async def test_diagral_api() -> None:  # noqa: D103
                 await alarm.delete_apikey()  # Delete the API key
 
     except DiagralAPIError as e:
-        logger.error("Erreur : %s", e)
+        _LOGGER.error("Erreur : %s", e)
 
 
 if __name__ == "__main__":

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

@@ -36,6 +36,7 @@ from .models import (
     Rudes,
     SystemDetails,
     SystemStatus,
+    TryConnectResult,
     Webhook,
 )
 from .utils import generate_hmac_signature
@@ -400,48 +401,48 @@ class DiagralAPI:
             self.__secret_key = None
 
     async def try_connection(self, ephemeral: bool = True) -> bool:
-        """Establish a connection with the Diagral system.
+        """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.

{pydiagral-1.5.0b1 → pydiagral-1.5.0b2}/src/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
 #####################################