pydiagral 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

pydiagral/api.py

@@ -7,7 +7,6 @@ retrieving system status, and controlling various aspects of the alarm system.
 
 from __future__ import annotations
 
-from datetime import datetime
 import logging
 import re
 import time
@@ -17,6 +16,8 @@ import aiohttp
 
 from .constants import API_VERSION, BASE_URL
 from .exceptions import (
+    APIKeyCreationError,
+    APIValidationError,
     AuthenticationError,
     ClientError,
     ConfigurationError,
@@ -37,11 +38,12 @@ from .models import (
     Rudes,
     SystemDetails,
     SystemStatus,
+    TryConnectResult,
     Webhook,
 )
 from .utils import generate_hmac_signature
 
-_LOGGER = logging.getLogger(__name__)
+_LOGGER: logging.Logger = logging.getLogger(__name__)
 
 # Minimum Python version: 3.10
 
@@ -84,17 +86,17 @@ class DiagralAPI:
             or not self.__is_valid_email(username)
         ):
             raise ConfigurationError("username must be a valid non-empty email address")
-        self.username = username
+        self.username: str = username
 
         # Validate password
         if not password or not isinstance(password, str):
             raise ConfigurationError("password must be a non-empty string")
-        self.__password = password
+        self.__password: str = password
 
         # Validate serial_id
         if not serial_id or not isinstance(serial_id, str):
             raise ConfigurationError("serial_id must be a non-empty string")
-        self.serial_id = serial_id
+        self.serial_id: str = serial_id
 
         # Set apikey and secret_key
         self.__apikey = apikey
@@ -104,12 +106,11 @@ class DiagralAPI:
         if pincode is not None:
             if not isinstance(pincode, int):
                 raise ConfigurationError("pincode must be an integer")
-        self.__pincode = pincode
+        self.__pincode: int | None = pincode
 
         # Initialize session and access_token
         self.session: aiohttp.ClientSession | None = None
         self.__access_token: str | None = None
-        self.access_token_expires: datetime | None = None
 
         # Set default values for other attributes
         self.alarm_configuration: AlarmConfiguration | None = None
@@ -120,7 +121,7 @@ class DiagralAPI:
         _LOGGER.info("Successfully initialized DiagralAPI session")
         return self
 
-    async def __aexit__(self, exc_type, exc, tb):
+    async def __aexit__(self, exc_type, exc, tb) -> None:
         """Close the aiohttp ClientSession."""
         if self.session:
             await self.session.close()
@@ -156,8 +157,8 @@ class DiagralAPI:
             _LOGGER.error(error_msg)
             raise SessionError(error_msg)
 
-        url = f"{BASE_URL}/{API_VERSION}/{endpoint}"
-        headers = kwargs.pop("headers", {})
+        url: str = f"{BASE_URL}/{API_VERSION}/{endpoint}"
+        headers: Any = kwargs.pop("headers", {})
         _LOGGER.debug(
             "Sending %s request to %s with headers %s and data %s",
             method,
@@ -170,7 +171,7 @@ class DiagralAPI:
             async with self.session.request(
                 method, url, headers=headers, timeout=timeout, **kwargs
             ) as response:
-                response_data = await response.json()
+                response_data: Any = await response.json()
                 if response.status == 400:
                     response = HTTPErrorResponse(**response_data)
                     raise DiagralAPIError(
@@ -236,13 +237,13 @@ class DiagralAPI:
             raise SessionError(error_msg)
 
         _LOGGER.debug("Attempting to login to Diagral API")
-        _DATA = {"username": self.username, "password": self.__password}
+        _DATA: dict[str, str] = {"username": self.username, "password": self.__password}
         try:
             response_data, *_ = await self._request(
                 "POST", "users/authenticate/login?vendor=DIAGRAL", json=_DATA
             )
             _LOGGER.debug("Login Response data: %s", response_data)
-            login_response = LoginResponse.from_dict(response_data)
+            login_response: LoginResponse = LoginResponse.from_dict(response_data)
             _LOGGER.debug("Login response: %s", login_response)
 
             self.__access_token = login_response.access_token
@@ -253,39 +254,30 @@ class DiagralAPI:
 
             _LOGGER.info("Successfully logged in to Diagral API")
         except DiagralAPIError as e:
-            error_msg = f"Failed to login : {e!s}"
+            error_msg: str = f"Failed to login : {e!s}"
             _LOGGER.error(error_msg)
             raise AuthenticationError(error_msg) from e
 
     async def set_apikey(self) -> ApiKeyWithSecret:
         """Asynchronously set the API key for the Diagral API.
 
-        This method first ensures that the access token is valid and not expired.
-        If the access token is expired, it attempts to log in again to refresh it.
-        Then, it sends a request to create a new API key using the current access token.
+        It sends a request to create a new API key using the current access token.
         If the API key is successfully created, it verifies the API key to ensure its validity.
 
         Returns:
             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.
 
         """
 
         if not self.__access_token:
             await self.login()
 
-        if (
-            self.__access_token
-            and self.access_token_expires
-            and datetime.now() >= self.access_token_expires
-        ):
-            _LOGGER.warning("Access token has expired, attempting to login again")
-            await self.login()
-
-        _DATA = {"serial_id": self.serial_id}
-        _HEADERS = {
+        _DATA: dict[str, str] = {"serial_id": self.serial_id}
+        _HEADERS: dict[str, str] = {
             "Authorization": f"Bearer {self.__access_token}",
         }
 
@@ -293,17 +285,19 @@ class DiagralAPI:
             response_data, *_ = await self._request(
                 "POST", "users/api_key", json=_DATA, headers=_HEADERS
             )
-            set_apikey_response = ApiKeyWithSecret.from_dict(response_data)
-            self.__apikey = set_apikey_response.api_key
+            set_apikey_response: ApiKeyWithSecret = ApiKeyWithSecret.from_dict(
+                response_data
+            )
+            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
@@ -312,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 = f"Failed to create API key: {e!s}"
+            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)
 
@@ -338,10 +332,11 @@ 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.
 
         """
 
-        apikey_to_validate = apikey or self.__apikey
+        apikey_to_validate: str = apikey or self.__apikey
 
         if not apikey_to_validate:
             _LOGGER.warning("No API key provided to validate")
@@ -350,7 +345,7 @@ class DiagralAPI:
         if not self.__access_token:
             await self.login()
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "Authorization": f"Bearer {self.__access_token}",
         }
         response_data, *_ = await self._request(
@@ -358,7 +353,7 @@ class DiagralAPI:
             f"users/systems/{self.serial_id}/api_keys",
             headers=_HEADERS,
         )
-        validate_apikey_response = ApiKeys.from_dict(response_data)
+        validate_apikey_response: ApiKeys = ApiKeys.from_dict(response_data)
         is_valid = any(
             key_info.api_key == apikey_to_validate
             for key_info in validate_apikey_response.api_keys
@@ -366,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"
             )
 
@@ -387,7 +382,7 @@ class DiagralAPI:
 
         """
 
-        apikey_to_delete = apikey or self.__apikey
+        apikey_to_delete: str = apikey or self.__apikey
 
         if not apikey_to_delete:
             raise AuthenticationError("An API key is required to delete it")
@@ -395,7 +390,7 @@ class DiagralAPI:
         if not self.__access_token:
             await self.login()
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "Authorization": f"Bearer {self.__access_token}",
         }
         await self._request(
@@ -409,6 +404,63 @@ class DiagralAPI:
             self.__apikey = None
             self.__secret_key = None
 
+    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
+        temporary ones. It validates the connection by checking the system status.
+
+        Args:
+            ephemeral (bool, optional): If True, temporary API keys will be deleted after
+                connection test. Defaults to True.
+
+        Returns:
+            TryConnectResult: Object containing connection test results and optionally API keys
+                if non-ephemeral temporary keys were generated.
+
+        Raises:
+            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
+            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)
+
+        # 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()
+        except DiagralAPIError:
+            # If connection fails, clean up keys
+            if not api_keys_provided:
+                await self.delete_apikey(apikey=self.__apikey)
+            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
+
     async def get_configuration(self) -> None:
         """Asynchronously retrieve the configuration of the Diagral system.
 
@@ -433,14 +485,14 @@ class DiagralAPI:
             )
 
         _TIMESTAMP = str(int(time.time()))
-        _HMAC = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
             "X-APIKEY": self.__apikey,
@@ -454,6 +506,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.
 
@@ -475,13 +549,13 @@ class DiagralAPI:
         if not self.alarm_configuration:
             raise ConfigurationError("Failed to retrieve alarm configuration")
 
-        device_types = sorted(
+        device_types: list[str] = sorted(
             ["cameras", "commands", "sensors", "sirens", "transmitters"]
         )
         devices_infos = {}
         for device_type in device_types:
             _LOGGER.debug("Retrieving devices information for %s", device_type)
-            devices = getattr(self.alarm_configuration, device_type, None)
+            devices: Any | None = getattr(self.alarm_configuration, device_type, None)
             if devices is not None:
                 devices_infos[device_type] = [
                     {"index": device.index, "label": device.label} for device in devices
@@ -515,14 +589,14 @@ class DiagralAPI:
             raise AuthenticationError("PIN code required to get system details")
 
         _TIMESTAMP = str(int(time.time()))
-        _HMAC = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-PIN-CODE": str(self.__pincode),
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
@@ -545,27 +619,27 @@ 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 = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-PIN-CODE": str(self.__pincode),
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
@@ -612,14 +686,14 @@ class DiagralAPI:
             raise AuthenticationError(f"PIN code required to do system action {action}")
 
         _TIMESTAMP = str(int(time.time()))
-        _HMAC = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-PIN-CODE": str(self.__pincode),
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
@@ -736,7 +810,7 @@ class DiagralAPI:
             await self.get_configuration()
 
         # Check if the groups are valid
-        invalid_groups = [
+        invalid_groups: list[int] = [
             group
             for group in groups
             if group not in [g.index for g in self.alarm_configuration.groups]
@@ -747,20 +821,20 @@ class DiagralAPI:
             )
 
         _TIMESTAMP = str(int(time.time()))
-        _HMAC = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-PIN-CODE": str(self.__pincode),
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
             "X-APIKEY": self.__apikey,
         }
-        data = {"groups": groups}
+        data: dict[str, list[int]] = {"groups": groups}
         response_data, *_ = await self._request(
             "POST",
             f"systems/{self.serial_id}/{action}",
@@ -854,14 +928,14 @@ class DiagralAPI:
             raise AuthenticationError("PIN code required to get system details")
 
         _TIMESTAMP = str(int(time.time()))
-        _HMAC = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-PIN-CODE": str(self.__pincode),
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
@@ -935,14 +1009,14 @@ class DiagralAPI:
             )
 
         _TIMESTAMP = str(int(time.time()))
-        _HMAC = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
             "X-APIKEY": self.__apikey,
@@ -990,14 +1064,14 @@ class DiagralAPI:
             )
 
         _TIMESTAMP = str(int(time.time()))
-        _HMAC = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
             "X-APIKEY": self.__apikey,
@@ -1043,14 +1117,14 @@ class DiagralAPI:
             )
 
         _TIMESTAMP = str(int(time.time()))
-        _HMAC = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
             "X-APIKEY": self.__apikey,
@@ -1108,14 +1182,14 @@ class DiagralAPI:
             )
 
         _TIMESTAMP = str(int(time.time()))
-        _HMAC = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
             "X-APIKEY": self.__apikey,
@@ -1216,14 +1290,14 @@ class DiagralAPI:
             )
 
         _TIMESTAMP = str(int(time.time()))
-        _HMAC = generate_hmac_signature(
+        _HMAC: str = generate_hmac_signature(
             timestamp=_TIMESTAMP,
             serial_id=self.serial_id,
             api_key=self.__apikey,
             secret_key=self.__secret_key,
         )
 
-        _HEADERS = {
+        _HEADERS: dict[str, str] = {
             "X-HMAC": _HMAC,
             "X-TIMESTAMP": _TIMESTAMP,
             "X-APIKEY": self.__apikey,

pydiagral/exceptions.py

@@ -10,8 +10,8 @@ class DiagralAPIError(Exception):
         :param message: The error message.
         :param status_code: The status code of the error, if any.
         """
-        self.message = message
-        self.status_code = status_code
+        self.message: str = message
+        self.status_code: int | None = status_code
         super().__init__(self.message)
 
 
@@ -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/models.py

@@ -15,7 +15,7 @@ import re
 import types
 from typing import TypeVar, Union, get_args, get_origin, get_type_hints
 
-logger = logging.getLogger(__name__)
+logger: logging.Logger = logging.getLogger(__name__)
 
 
 #######################################################
@@ -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/utils.py

@@ -10,5 +10,5 @@ def generate_hmac_signature(
 ) -> str:
     """Generate an HMAC signature for the given parameters."""
     timestamp = str(int(time.time()))
-    message = f"{timestamp}.{serial_id}.{api_key}"
+    message: str = f"{timestamp}.{serial_id}.{api_key}"
     return hmac.new(secret_key.encode(), message.encode(), hashlib.sha256).hexdigest()

{pydiagral-1.4.0.dist-info → pydiagral-1.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydiagral
-Version: 1.4.0
+Version: 1.5.0
 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
@@ -685,7 +685,7 @@ License:                     GNU GENERAL PUBLIC LICENSE
         <https://www.gnu.org/licenses/why-not-lgpl.html>.
 License-File: LICENSE
 Keywords: diagral,home automation,python
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Operating System :: OS Independent
@@ -702,9 +702,6 @@ Description-Content-Type: text/markdown
 <p align="center">
   <img src="https://raw.githubusercontent.com/mguyard/pydiagral/main/docs/pydiagral-Logo.png" width="400" />
 </p>
-<p align="center">
-    <h1 align="center">PyDiagral</h1>
-</p>
 <p align="center">
     A powerful and easy-to-use Python library for seamless integration with the Diagral alarm system.
 </p>
@@ -729,19 +726,25 @@ Description-Content-Type: text/markdown
 </p>
 <br /><br />
 
-# Documentation pydiagral
+# pydiagral
 
 Welcome to the documentation for pydiagral, a Python library for interacting with the Diagral API.
 
-## About pydiagral
+## 📍 About pydiagral
 
-pydiagral is an asynchronous Python interface for the Diagral alarm system. This library allows users to control and monitor their Diagral alarm system through the official API.
+`pydiagral` is an asynchronous Python interface for the Diagral alarm system. This library allows users to control and monitor their Diagral alarm system through the official API.
 
-## Requirement
+> [!CAUTION]
+>
+> Please note that the Diagral alarm system is a security system, and it may be preferable not to connect it to any automation platform for security reasons.
+> In no event shall the developer of [`pydiagral`](https://github.com/mguyard/pydiagral) library be held liable for any issues arising from the use of this [`pydiagral`](https://github.com/mguyard/pydiagral) library.
+> The user installs and uses this integration at their own risk and with full knowledge of the potential implications.
+
+## ✅ Requirement
 
 To use this library, which leverages the Diagral APIs, you must have a Diagral box (DIAG56AAX). This box connects your Diagral alarm system to the internet, enabling interaction with the alarm system via the API. You can find more information about the Diagral box [here](https://www.diagral.fr/commande/box-alerte-et-pilotage).
 
-## Key Features
+## 📦 Key Features
 
 The `DiagralAPI` class offers the following functionalities:
 
@@ -766,7 +769,7 @@ The `DiagralAPI` class offers the following functionalities:
   - Activate or Desactivate system (partially or globally)
   - Automatism actions
 
-## Quick Start
+## 🚀 Quick Start
 
 To get started with pydiagral, follow these steps:
 
@@ -796,33 +799,72 @@ And run the [example_code.py](https://github.com/mguyard/pydiagral/blob/main/exa
 >
 > You can customize the actions performed by [example_code.py](https://github.com/mguyard/pydiagral/blob/main/example_code.py) by modifying the parameters in the code, as indicated by the `CUSTOMIZE THE TESTS` section title.
 
+# 📖 Documentations
+
+## Package Documentation
+
+Library documentation is available [here](https://mguyard.github.io/pydiagral/).
+
+### Package Structure
+
+For detailed library documentation, please refer to the following sections:
+
+- [API Reference](https://mguyard.github.io/pydiagral/api/): Comprehensive documentation of the DiagralAPI class and its methods
+- [Data Models](https://mguyard.github.io/pydiagral/models/): Description of the data structures used
+- [Exceptions](https://mguyard.github.io/pydiagral/exceptions/): List of package exceptions
+
 ## Diagral API Official documentation
 
 Official Diagral API is available [here](https://appv3.tt-monitor.com/emerald/redoc).
 
+# 🙋 FAQ
+
 ## How to find Serial on DIAG56AAX
 
 The serial number can only be found with physical access to the box. You need to open it, and you will find a label with a QR Code.
+
 On this label, there is a 15-character code that represents the serial number of the box.
 
-![How to find your Diagral Serial](docs/how-to-find-diagral-serial.png)
+![How to find your Diagral Serial](https://raw.githubusercontent.com/mguyard/pydiagral/main/docs/how-to-find-diagral-serial.png)
 
 > [!IMPORTANT]
 >
 > This code is necessary to use this library and Diagral API.
 
-## API Structure
+# 🤝 Contribution
+
+Contributions are welcome! Here are several ways you can contribute:
+
+- **Submit Pull Requests**: Review open PRs, and submit your own PRs.
+- **Report Issues**: Submit bugs found or log feature requests.
 
-For detailed API documentation, please refer to the following sections:
+<details closed>
+    <summary>Contributing Guidelines</summary>
 
-- [API Reference](https://XXXXXXXXXXXXXXXX): Comprehensive documentation of the DiagralAPI class and its methods
-- [Data Models](https://XXXXXXXXXXXXXXXX): Description of the data structures used
-- [Exceptions](https://XXXXXXXXXXXXXXXX): List of package exceptions
+1. **Fork the Repository**: Start by forking the project repository to your GitHub account.
+2. **Clone Locally**: Clone the forked repository to your local machine using a Git client.
+   ```sh
+   git clone https://github.com/mguyard/pydiagral
+   ```
+3. **Create a New Branch**: Always work on a new branch, giving it a descriptive name.
+   ```sh
+   git checkout -b new-feature-x
+   ```
+4. **Make Your Changes**: Develop and test your changes locally.
+5. **Commit Your Changes**: Commit your changes with a clear and concise message that follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) guidelines.
+   ```sh
+   git commit -m 'feat: Implemented new feature x.'
+   ```
+6. **Push to GitHub**: Push the changes to your forked repository.
+   ```sh
+   git push origin new-feature-x
+   ```
+7. **Submit a Pull Request**: Create a PR against the original project repository. Clearly describe the changes and their motivations.
 
-## Contribution
+Once your PR is reviewed and approved, it will be merged into the `beta` branch. After final testing, it will be merged into the `main` branch.
 
-Contributions to pydiagral are welcome! Please check our contribution guidelines for more information on how to participate in the development of this library.
+</details>
 
-## License
+# 📄 License
 
 pydiagral is distributed under the GPL-v3 License. See the [LICENSE](https://github.com/mguyard/pydiagral/blob/main/LICENSE) file for more details.

pydiagral-1.5.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pydiagral/__init__.py,sha256=4uM-RD2GQ6JYJkxu-D6wj3XpqfY5gN2hP8NF6WvRI9k,576
+pydiagral/api.py,sha256=nEmP1UuZWIMoSpWMxGk4dF2AbejlE7AJHMTBGUeLra8,50129
+pydiagral/constants.py,sha256=2B0TdKxQHA3cpIBxojo43bMW44wN9xKYsHbBRHWsaBk,119
+pydiagral/exceptions.py,sha256=vMhGDQW-AhYIH9gcKHK1-4SHV3eZUXeeqXPyznUAKnU,1211
+pydiagral/models.py,sha256=vUjxuApjVaMtd7H6Iw5LarwABi30O4FfdObhZRbUNuc,54931
+pydiagral/utils.py,sha256=-VxI-lNaC4bU1K4DSmWDhvbsS2bXv5FAGULGKBf1UMU,449
+pydiagral-1.5.0.dist-info/METADATA,sha256=znS_27alZXQQyVkcNyvWXDmhHA7V3E84z9O_qlyiYVA,48529
+pydiagral-1.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pydiagral-1.5.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+pydiagral-1.5.0.dist-info/RECORD,,

pydiagral-1.4.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-pydiagral/__init__.py,sha256=4uM-RD2GQ6JYJkxu-D6wj3XpqfY5gN2hP8NF6WvRI9k,576
-pydiagral/api.py,sha256=sX46Fct3Bwei5yKKQ5PnGDKl261BBqZ0CYMFUnXZ5Mw,46753
-pydiagral/constants.py,sha256=2B0TdKxQHA3cpIBxojo43bMW44wN9xKYsHbBRHWsaBk,119
-pydiagral/exceptions.py,sha256=PLo85XJ55q4_dzsyaMYXLIaX8Ws7HH6vDUWNWodzCpM,1013
-pydiagral/models.py,sha256=shnAf7ojh6y5fGp3l5RbGdp4qpuEyOZI-0ePrWAg2l0,54120
-pydiagral/utils.py,sha256=weccW18dseD_Ypwe4dKvNz6TlZPA7BQbf5l5qk3GXOg,444
-pydiagral-1.4.0.dist-info/METADATA,sha256=uomaH_YBT9vnk7pplGjfSA4vnxvxq9jBVAsE5Wc2zAc,46568
-pydiagral-1.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pydiagral-1.4.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-pydiagral-1.4.0.dist-info/RECORD,,