ics_2000_python 0.1.1__tar.gz → 0.1.3__tar.gz

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/PKG-INFO

@@ -1,14 +1,14 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: ics_2000_python
-Version: 0.1.1
+Version: 0.1.3
 Summary: 
-Home-page: https://github.com/zefanjajobse/ics_2000_python
 Keywords: ics_2000,ics-2000,klikaanklikuit
 Author: iiTzArcur
 Author-email: zefanjaj@gmail.com
 Requires-Python: >=3.12,<4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: pycryptodome (>=3.21.0,<4.0.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)
 Project-URL: Repository, https://github.com/zefanjajobse/ics_2000_python
@@ -19,8 +19,14 @@ This library gives methods to control a ICS-2000 from KlikAanKlikUit. It is made
 
 ## Usage example:
 ```py
+from ics_2000.entities.dim_device import DimDevice
+from ics_2000.entities.switch_device import SwitchDevice
+from ics_2000.hub import Hub
+
 hub = Hub("example@email.com", "password")
-hub.login() # Authenticate
+homes = hub.login()  # Authenticate
+print(homes) # returns a dictionary of homes, ex: {"0": "test home}
+hub.select_home("132829") # Select the right home by id
 hub.get_devices() # request devices
 for device in hub.devices:
     if type(device) is SwitchDevice or type(device) is DimDevice:

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/README.md

@@ -3,8 +3,14 @@ This library gives methods to control a ICS-2000 from KlikAanKlikUit. It is made
 
 ## Usage example:
 ```py
+from ics_2000.entities.dim_device import DimDevice
+from ics_2000.entities.switch_device import SwitchDevice
+from ics_2000.hub import Hub
+
 hub = Hub("example@email.com", "password")
-hub.login() # Authenticate
+homes = hub.login()  # Authenticate
+print(homes) # returns a dictionary of homes, ex: {"0": "test home}
+hub.select_home("132829") # Select the right home by id
 hub.get_devices() # request devices
 for device in hub.devices:
     if type(device) is SwitchDevice or type(device) is DimDevice:

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/ics_2000/command.py

@@ -13,10 +13,10 @@ class Command:
         hub_mac: str,
         device_id: int,
         device_function: int,
-        value: int,
+        value: int | float,
         aes_key: str,
         entity_type: Entity_Type,
-        device_functions: List[int] = [],
+        device_functions: List[int | float] = [],
     ):
         self.hub_mac = hub_mac
         self.device_id = device_id

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/ics_2000/encryption.py

@@ -1,13 +1,15 @@
 import base64
 from Crypto.Cipher import AES
 from Crypto.Util.Padding import unpad
-from Crypto.Random import get_random_bytes
 
 encoding = "utf-8"
 block_size = 16
-pad = lambda s: s + (block_size - len(s) % block_size) * chr(
-    block_size - len(s) % block_size
-)
+
+
+def pad(s):
+    return s + (block_size - len(s) % block_size) * chr(
+        block_size - len(s) % block_size
+    )
 
 
 def decrypt(string: str, aes: str) -> str:

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/ics_2000/entities/color_temperature_device.py

@@ -1,10 +1,18 @@
+from typing import TYPE_CHECKING
 from ..model.device_data import DeviceData
 from .dim_device import DimDevice
 from ..model.device_config import DeviceConfig
 
+if TYPE_CHECKING:
+    from ..hub import Hub
+
 
 class ColorTemperatureDevice(DimDevice):
-    def __init__(self, hub, device_data: DeviceData, device_config: DeviceConfig):
+    """Class used for color changeable, dimmable devices"""
+
+    def __init__(
+        self, hub: "Hub", device_data: DeviceData, device_config: DeviceConfig
+    ):
         super().__init__(hub, device_data, device_config)
 
         if device_config.color_temperature_function is None:
@@ -15,6 +23,9 @@ class ColorTemperatureDevice(DimDevice):
     def change_color_temperature(
         self, color_temperature: float, send_local: bool = True
     ) -> None:
+        if self.device_config.color_temperature_function is None:
+            return
+
         return self.get_hub().change_color_temperature(
             self.entity_id,
             self.device_config.color_temperature_function,
@@ -24,5 +35,8 @@ class ColorTemperatureDevice(DimDevice):
         )
 
     def get_color_temperature(self) -> float:
+        if self.device_config.color_temperature_function is None:
+            return 0
+
         status = self.get_hub().get_device_status(self.entity_id)
         return status[self.device_config.color_temperature_function]

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/ics_2000/entities/device.py

@@ -1,14 +1,22 @@
+from typing import TYPE_CHECKING
 from .entity import Entity
 from ..model.device_data import DeviceData
 from ..model.device_config import DeviceConfig
 
+if TYPE_CHECKING:
+    from ..hub import Hub
+
 
 class Device(Entity):
-    def __init__(self, hub, device_data: DeviceData, device_config: DeviceConfig):
+    def __init__(
+        self, hub: "Hub", device_data: DeviceData, device_config: DeviceConfig
+    ):
         super().__init__(
             hub, device_data, "group" in device_data.data and "group" or "module"
         )
         self.device_config = device_config
+        """List of device functions"""
         self.disabled = (
             device_config.disabled if device_config.disabled is not None else False
         )
+        """If the device can be changed"""

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/ics_2000/entities/dim_device.py

@@ -1,16 +1,33 @@
+from typing import TYPE_CHECKING
 from ..model.device_data import DeviceData
 from .switch_device import SwitchDevice
 from ..model.device_config import DeviceConfig
 
+if TYPE_CHECKING:
+    from ..hub import Hub
+
 
 class DimDevice(SwitchDevice):
-    def __init__(self, hub, device_data: DeviceData, device_config: DeviceConfig):
+    """Class used for all dimmable devices"""
+
+    def __init__(
+        self, hub: "Hub", device_data: DeviceData, device_config: DeviceConfig
+    ):
         super().__init__(hub, device_data, device_config)
 
         if device_config.dim_function is None:
             raise ValueError(f"Dim function not defined for '{self.device_data.name}'")
 
     def dim(self, dim_level: int, send_local: bool = True) -> None:
+        """Change the dim level of the device.
+
+        Args:
+          dim_level: new dim level (0-255).
+          send_local: Use the ip_address set on the hub to talk to the device
+        """
+        if self.device_config.dim_function is None:
+            return
+
         return self.get_hub().dim_device(
             self.entity_id,
             self.device_config.dim_function,
@@ -20,5 +37,12 @@ class DimDevice(SwitchDevice):
         )
 
     def get_dim_level(self) -> int:
+        """Get the dim level of a device
+
+        Returns:
+        Current dim level (0-255)."""
+        if self.device_config.dim_function is None:
+            return 0
+
         status = self.get_hub().get_device_status(self.entity_id)
         return status[self.device_config.dim_function]

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/ics_2000/entities/entity.py

@@ -1,13 +1,22 @@
-from typing import List
+from typing import List, TYPE_CHECKING
+
 from ..model.device_data import DeviceData
 from ..model.entity_type import EntityType
 
+if TYPE_CHECKING:
+    from ..hub import Hub
+
 
 class Entity:
-    def __init__(self, hub, device_data: DeviceData, entity_type: EntityType):
+    """Class used for all devices"""
+
+    def __init__(self, hub: "Hub", device_data: DeviceData, entity_type: EntityType):
         self._hub = hub
+        """Main hub"""
         self.entity_id = int(device_data.id)
+        """ID"""
         self.name = device_data.data[entity_type].get("name", "")
+        """Name of the device"""
         self.device_type = (
             device_data.data[entity_type].get("device", "")
             if "device" in device_data.data[entity_type]
@@ -19,7 +28,7 @@ class Entity:
     def get_status(self) -> List[int]:
         return self._hub.get_device_status(self.entity_id)
 
-    def get_hub(self):
+    def get_hub(self) -> "Hub":
         return self._hub
 
     def change_status(self, device_function: int, value: int, send_local: bool) -> None:

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/ics_2000/entities/switch_device.py

@@ -4,6 +4,8 @@ from .device import Device
 
 
 class SwitchDevice(Device):
+    """Class used for all switch devices"""
+
     def __init__(self, hub, device_data: DeviceData, device_config: DeviceConfig):
         super().__init__(hub, device_data, device_config)
 
@@ -13,6 +15,14 @@ class SwitchDevice(Device):
             )
 
     def turn_on_off(self, on: bool, send_local: bool = True) -> None:
+        """Change the state of the device.
+
+        Args:
+          on: new state of the device, True == on.
+          send_local: Use the ip_address set on the hub to talk to the device
+        """
+        if self.device_config.on_off_function is None:
+            return
         self.get_hub().turn_device_on_off(
             self.entity_id,
             on,
@@ -22,6 +32,13 @@ class SwitchDevice(Device):
         )
 
     def turn_on(self, send_local: bool = True) -> None:
+        """Turn on the device.
+
+        Args:
+          send_local: Use the ip_address set on the hub to talk to the device
+        """
+        if self.device_config.on_off_function is None:
+            return
         self.get_hub().turn_device_on_off(
             self.entity_id,
             True,
@@ -31,6 +48,13 @@ class SwitchDevice(Device):
         )
 
     def turn_off(self, send_local: bool = True) -> None:
+        """Turn off the device.
+
+        Args:
+          send_local: Use the ip_address set on the hub to talk to the device
+        """
+        if self.device_config.on_off_function is None:
+            return
         self.get_hub().turn_device_on_off(
             self.entity_id,
             False,
@@ -40,5 +64,8 @@ class SwitchDevice(Device):
         )
 
     def get_on_status(self) -> bool:
+        """Returns true if device is turned on"""
+        if self.device_config.on_off_function is None:
+            return False
         status = self.get_status()
         return status[self.device_config.on_off_function] == 1

ics_2000_python-0.1.3/ics_2000/exceptions.py

@@ -0,0 +1,12 @@
+
+class InvalidAuthException(Exception):
+    """When the authentication failed"""
+    
+class InvalidHomeException(Exception):
+    """When selected home does not exist as a option"""
+
+class InvalidMacOrAuthException(Exception):
+    """When the auth or mac address is not set"""
+
+class NoHomeSelectedException(Exception):
+    """When no home is selected"""

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/ics_2000/hub.py

@@ -1,6 +1,8 @@
 from datetime import datetime
 import json
 import requests
+
+from ics_2000.exceptions import InvalidAuthException, InvalidHomeException, InvalidMacOrAuthException, NoHomeSelectedException
 from .command import Command
 from .encryption import decrypt
 from .config import API_URL, device_configs
@@ -14,22 +16,43 @@ from .model.entity_type import Entity_Type
 
 
 class Hub:
+    """KlikAanKlikUit ICS-2000 Control Station connection info
+
+
+    Attributes:
+        email: Email address of the account connected to the ICS-2000
+        password: Password of the account connected to the ICS-2000
+    """
+
     def __init__(self, email: str, password: str):
+        self.homes = []
         self.devices: list[
             Device | DimDevice | SwitchDevice | ColorTemperatureDevice
         ] = []
+        """List of available devices within the authenticated home"""
         self.aes_key: str | None = None
+        """Authentication key"""
         self.mac: str | None = None
+        """MAC-Address of the KlikAanKlikUit ICS-2000"""
         self.home_name: str | None = None
+        """Name of the home given within KlikAanKlikUit"""
         self.home_id: str | None = None
+        """ID of the home"""
         self.email = email
+        """Email address of the account connected to the ICS-2000"""
         self.password = password
+        """Password of the account connected to the ICS-2000"""
         self.local_address: str | None = None
+        """Local IP address when you want to control it locally"""
         self.device_statuses: dict[int, list[int]] = {}
+        """Statuses of the devices"""
         self.update_date = datetime.min
+        """When the device statuses were last updated"""
 
-    def login(self):
-        test = requests.post(
+    def login(self) -> dict[str, str]:
+        """Logs in to the account given"""
+        self.homes = []
+        response = requests.post(
             f"{API_URL}/account.php",
             {
                 "action": "login",
@@ -41,24 +64,28 @@ class Hub:
             },
         )
 
-        if test.status_code != 200:
-            if test.status_code == 401:
-                raise Exception("Incorrect username or password")
-            raise Exception(test.content)
-
-        response = test.json()
-        if len(response.get("homes", [])) > 0:
-            home: dict = response["homes"][0]
-            self.aes_key = home.get("aes_key", "")
-            self.mac = home.get("mac", "")
-            self.home_id = home.get("home_id")
-            self.home_name = home.get("home_name")
-        else:
-            raise Exception("No homes")
+        if response.status_code != 200:
+            if response.status_code == 401:
+                raise InvalidAuthException("Incorrect username or password")
+            raise InvalidAuthException(response.content)
+
+        data = response.json()
+        if data is not None:
+            self.homes = data.get("homes", [])
+        return dict([(home.get("home_id"), home.get("home_name"))for home in self.homes])
+
+    def select_home(self, home_id: str) -> None:
+        home = next(home for home in self.homes if home.get("home_id") == home_id)
+        if home is None:
+            raise InvalidHomeException()
+        self.aes_key = home.get("aes_key", "")
+        self.mac = home.get("mac", "")
+        self.home_id = home.get("home_id")
+        self.home_name = home.get("home_name")
 
     def get_raw_devices_data(self, decrypt_data, decrypt_status) -> list:
         if self.aes_key is None or self.mac is None:
-            raise Exception("no mac or auth key")
+            raise InvalidMacOrAuthException()
 
         device_info = requests.post(
             f"{API_URL}/gateway.php",
@@ -91,9 +118,12 @@ class Hub:
 
         return data
 
-    def get_devices(self):
+    def get_devices(
+        self,
+    ) -> list[Device | DimDevice | SwitchDevice | ColorTemperatureDevice]:
+        """Gets all devices connected to the hub"""
         if self.home_id is None:
-            raise Exception("no home")
+            raise NoHomeSelectedException()
 
         entities = self.get_raw_devices_data(True, False)
         for device in entities:
@@ -129,14 +159,19 @@ class Hub:
                 self.devices.append(SwitchDevice(self, device_data, device_config))
             else:
                 self.devices.append(Device(self, device_data, device_config))
+        return self.devices
 
     def create_command(
-        self, device_id: int, device_function: int, value: int, entity_type: Entity_Type
+        self,
+        device_id: int,
+        device_function: int,
+        value: int | float,
+        entity_type: Entity_Type,
     ) -> Command:
         if self.aes_key is None or self.mac is None:
-            raise Exception("no mac or auth key")
+            raise InvalidMacOrAuthException()
 
-        device_functions: list[int] = []
+        device_functions: list[int | float] = []
 
         # if entity_type == Entity_Type.Group:
         #     device_functions = self.device_statuses.get(device_id, [])
@@ -159,6 +194,7 @@ class Hub:
         is_group: bool,
         send_local: bool,
     ) -> None:
+        """Change to the enabled state of the device"""
         command = self.create_command(
             device_id,
             on_function,
@@ -236,7 +272,7 @@ class Hub:
         self, data: dict, decrypt_data: bool, decrypt_status: bool
     ) -> dict:
         if self.aes_key is None or self.mac is None:
-            raise Exception("no mac or auth key")
+            raise InvalidMacOrAuthException()
 
         if decrypt_data:
             data["data"] = json.loads(decrypt(data.get("data", ""), self.aes_key))
@@ -294,7 +330,7 @@ class Hub:
         self,
         device_id: int,
         color_temp_function: int,
-        color_temperature: int,
+        color_temperature: float,
         is_group: bool,
         send_local: bool,
     ):

{ics_2000_python-0.1.1 → ics_2000_python-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "ics_2000_python"
-version = "0.1.1"
+version = "0.1.3"
 description = ""
 authors = ["iiTzArcur <zefanjaj@gmail.com>"]
 readme = "README.md"
@@ -15,7 +15,7 @@ pycryptodome = "^3.21.0"
 
 
 [tool.poetry.group.test.dependencies]
-pytest = "^8.3.3"
+pytest = "^8.3.4"
 requests-mock = "^1.12.1"
 
 [build-system]