indevolt-api 1.2.3__tar.gz → 1.3.0__tar.gz

{indevolt_api-1.2.3 → indevolt_api-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: indevolt-api
-Version: 1.2.3
+Version: 1.3.0
 Summary: Python API client for Indevolt devices
 Author: A. Gideonse
 License: MIT
@@ -223,6 +223,64 @@ config = await api.get_config()
 print(config)
 ```
 
+#### `check_charge_limits(power: int, target_soc: int, generation: int) -> None`
+
+Check that charge parameters do not exceed device limits. Raises an exception if any boundary is violated.
+
+**Parameters:**
+
+- `power` (int): Requested charge power in watts
+- `target_soc` (int): Target state of charge percentage
+- `generation` (int): Device hardware generation (`1` or `2`), available from `get_config()` under `device.generation`
+
+**Raises:**
+
+- `ChargePowerExceedsMaxError`: If `power` exceeds the maximum for the given generation
+- `SocBelowMinimumError`: If `target_soc` is below `MINIMUM_SOC` (5%)
+
+**Example:**
+
+```python
+config = await api.get_config()
+generation = config["device"]["generation"]
+
+try:
+    api.check_charge_limits(power=1000, target_soc=80, generation=generation)
+except ChargePowerExceedsMaxError as e:
+    print(f"Power {e.power}W exceeds max {e.max_power}W for gen {e.generation}")
+except SocBelowMinimumError as e:
+    print(f"Target SOC {e.target_soc}% is below minimum {e.minimum_soc}%")
+```
+
+#### `check_discharge_limits(power: int, target_soc: int, generation: int) -> None`
+
+Check that discharge parameters do not exceed device limits. Raises an exception if any boundary is violated.
+
+**Parameters:**
+
+- `power` (int): Requested discharge power in watts
+- `target_soc` (int): Target state of charge percentage
+- `generation` (int): Device hardware generation (`1` or `2`), available from `get_config()` under `device.generation`
+
+**Raises:**
+
+- `DischargePowerExceedsMaxError`: If `power` exceeds the maximum for the given generation
+- `SocBelowMinimumError`: If `target_soc` is below `MINIMUM_SOC` (5%)
+
+**Example:**
+
+```python
+config = await api.get_config()
+generation = config["device"]["generation"]
+
+try:
+    api.check_discharge_limits(power=600, target_soc=10, generation=generation)
+except DischargePowerExceedsMaxError as e:
+    print(f"Power {e.power}W exceeds max {e.max_power}W for gen {e.generation}")
+except SocBelowMinimumError as e:
+    print(f"Target SOC {e.target_soc}% is below minimum {e.minimum_soc}%")
+```
+
 ### async_discover(timeout: float = 5.0) -> list[DiscoveredDevice]
 
 Discover Indevolt devices on the local network using UDP broadcast.
@@ -265,7 +323,7 @@ if device.name:
 
 ## Exception Handling
 
-The library provides two custom exceptions:
+The library provides custom exceptions for API errors and limit violations.
 
 ### `APIException`
 
@@ -275,6 +333,24 @@ Raised when there's a client error during API communication (network errors, HTT
 
 Raised when an API request times out (default timeout: 10 seconds).
 
+### `ChargePowerExceedsMaxError`
+
+Raised by `check_charge_limits()` when the requested charge power exceeds the device maximum.
+
+**Attributes:** `power`, `max_power`, `generation`
+
+### `DischargePowerExceedsMaxError`
+
+Raised by `check_discharge_limits()` when the requested discharge power exceeds the device maximum.
+
+**Attributes:** `power`, `max_power`, `generation`
+
+### `SocBelowMinimumError`
+
+Raised by `check_charge_limits()` or `check_discharge_limits()` when the target SOC is below the hard minimum of 5%.
+
+**Attributes:** `target_soc`, `minimum_soc`
+
 **Example:**
 
 ```python

{indevolt_api-1.2.3 → indevolt_api-1.3.0}/indevolt_api/__init__.py

@@ -2,18 +2,28 @@
 
 from .client import (
     APIException,
+    ChargePowerExceedsMaxError,
     DiscoveredDevice,
+    DischargePowerExceedsMaxError,
     IndevoltAPI,
+    MINIMUM_SOC,
+    POWER_LIMITS,
+    SocBelowMinimumError,
     TimeOutException,
     async_discover,
 )
 
-__version__ = "1.2.3"
+__version__ = "1.3.0"
 
 __all__ = [
     "IndevoltAPI",
     "APIException",
+    "ChargePowerExceedsMaxError",
+    "DiscoveredDevice",
+    "DischargePowerExceedsMaxError",
+    "MINIMUM_SOC",
+    "POWER_LIMITS",
+    "SocBelowMinimumError",
     "TimeOutException",
     "async_discover",
-    "DiscoveredDevice",
 ]

{indevolt_api-1.2.3 → indevolt_api-1.3.0}/indevolt_api/client.py

@@ -18,6 +18,40 @@ class APIException(Exception):
     """Raised on client error during API call."""
 
 
+MINIMUM_SOC: int = 5
+
+POWER_LIMITS: dict[int, dict[str, int]] = {
+    1: {"max_discharge_power": 800, "max_charge_power": 1200},
+    2: {"max_discharge_power": 2400, "max_charge_power": 2400},
+}
+
+
+class ChargePowerExceedsMaxError(Exception):
+    """Raised when requested charge power exceeds the device maximum."""
+
+    def __init__(self, power: int, max_power: int, generation: int) -> None:
+        self.power = power
+        self.max_power = max_power
+        self.generation = generation
+
+
+class DischargePowerExceedsMaxError(Exception):
+    """Raised when requested discharge power exceeds the device maximum."""
+
+    def __init__(self, power: int, max_power: int, generation: int) -> None:
+        self.power = power
+        self.max_power = max_power
+        self.generation = generation
+
+
+class SocBelowMinimumError(Exception):
+    """Raised when target SOC is below the API's hard minimum."""
+
+    def __init__(self, target_soc: int) -> None:
+        self.target_soc = target_soc
+        self.minimum_soc = MINIMUM_SOC
+
+
 # Discovery configuration
 DISCOVERY_PORT = 10000
 BROADCAST_PORT = 8099
@@ -282,6 +316,44 @@ class IndevoltAPI:
 
         return bool(response.get("result", False))
 
+    def check_charge_limits(self, power: int, target_soc: int, generation: int) -> None:
+        """Check that charge parameters do not exceed device limits.
+
+        Args:
+            power: Requested charge power in watts
+            target_soc: Target state of charge percentage
+            generation: Device hardware generation (1 or 2)
+
+        Raises:
+            ChargePowerExceedsMaxError: If power exceeds the device maximum
+            SocBelowMinimumError: If target_soc is below MINIMUM_SOC
+        """
+        max_power = POWER_LIMITS[generation]["max_charge_power"]
+        if power > max_power:
+            raise ChargePowerExceedsMaxError(power, max_power, generation)
+        if target_soc < MINIMUM_SOC:
+            raise SocBelowMinimumError(target_soc)
+
+    def check_discharge_limits(
+        self, power: int, target_soc: int, generation: int
+    ) -> None:
+        """Check that discharge parameters do not exceed device limits.
+
+        Args:
+            power: Requested discharge power in watts
+            target_soc: Target state of charge percentage
+            generation: Device hardware generation (1 or 2)
+
+        Raises:
+            DischargePowerExceedsMaxError: If power exceeds the device maximum
+            SocBelowMinimumError: If target_soc is below MINIMUM_SOC
+        """
+        max_power = POWER_LIMITS[generation]["max_discharge_power"]
+        if power > max_power:
+            raise DischargePowerExceedsMaxError(power, max_power, generation)
+        if target_soc < MINIMUM_SOC:
+            raise SocBelowMinimumError(target_soc)
+
     async def get_config(self) -> dict[str, Any]:
         """Get system configuration from the device.
 

{indevolt_api-1.2.3 → indevolt_api-1.3.0}/indevolt_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: indevolt-api
-Version: 1.2.3
+Version: 1.3.0
 Summary: Python API client for Indevolt devices
 Author: A. Gideonse
 License: MIT
@@ -223,6 +223,64 @@ config = await api.get_config()
 print(config)
 ```
 
+#### `check_charge_limits(power: int, target_soc: int, generation: int) -> None`
+
+Check that charge parameters do not exceed device limits. Raises an exception if any boundary is violated.
+
+**Parameters:**
+
+- `power` (int): Requested charge power in watts
+- `target_soc` (int): Target state of charge percentage
+- `generation` (int): Device hardware generation (`1` or `2`), available from `get_config()` under `device.generation`
+
+**Raises:**
+
+- `ChargePowerExceedsMaxError`: If `power` exceeds the maximum for the given generation
+- `SocBelowMinimumError`: If `target_soc` is below `MINIMUM_SOC` (5%)
+
+**Example:**
+
+```python
+config = await api.get_config()
+generation = config["device"]["generation"]
+
+try:
+    api.check_charge_limits(power=1000, target_soc=80, generation=generation)
+except ChargePowerExceedsMaxError as e:
+    print(f"Power {e.power}W exceeds max {e.max_power}W for gen {e.generation}")
+except SocBelowMinimumError as e:
+    print(f"Target SOC {e.target_soc}% is below minimum {e.minimum_soc}%")
+```
+
+#### `check_discharge_limits(power: int, target_soc: int, generation: int) -> None`
+
+Check that discharge parameters do not exceed device limits. Raises an exception if any boundary is violated.
+
+**Parameters:**
+
+- `power` (int): Requested discharge power in watts
+- `target_soc` (int): Target state of charge percentage
+- `generation` (int): Device hardware generation (`1` or `2`), available from `get_config()` under `device.generation`
+
+**Raises:**
+
+- `DischargePowerExceedsMaxError`: If `power` exceeds the maximum for the given generation
+- `SocBelowMinimumError`: If `target_soc` is below `MINIMUM_SOC` (5%)
+
+**Example:**
+
+```python
+config = await api.get_config()
+generation = config["device"]["generation"]
+
+try:
+    api.check_discharge_limits(power=600, target_soc=10, generation=generation)
+except DischargePowerExceedsMaxError as e:
+    print(f"Power {e.power}W exceeds max {e.max_power}W for gen {e.generation}")
+except SocBelowMinimumError as e:
+    print(f"Target SOC {e.target_soc}% is below minimum {e.minimum_soc}%")
+```
+
 ### async_discover(timeout: float = 5.0) -> list[DiscoveredDevice]
 
 Discover Indevolt devices on the local network using UDP broadcast.
@@ -265,7 +323,7 @@ if device.name:
 
 ## Exception Handling
 
-The library provides two custom exceptions:
+The library provides custom exceptions for API errors and limit violations.
 
 ### `APIException`
 
@@ -275,6 +333,24 @@ Raised when there's a client error during API communication (network errors, HTT
 
 Raised when an API request times out (default timeout: 10 seconds).
 
+### `ChargePowerExceedsMaxError`
+
+Raised by `check_charge_limits()` when the requested charge power exceeds the device maximum.
+
+**Attributes:** `power`, `max_power`, `generation`
+
+### `DischargePowerExceedsMaxError`
+
+Raised by `check_discharge_limits()` when the requested discharge power exceeds the device maximum.
+
+**Attributes:** `power`, `max_power`, `generation`
+
+### `SocBelowMinimumError`
+
+Raised by `check_charge_limits()` or `check_discharge_limits()` when the target SOC is below the hard minimum of 5%.
+
+**Attributes:** `target_soc`, `minimum_soc`
+
 **Example:**
 
 ```python

{indevolt_api-1.2.3 → indevolt_api-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "indevolt-api"
-version = "1.2.3"
+version = "1.3.0"
 description = "Python API client for Indevolt devices"
 readme = "readme.md"
 authors = [

{indevolt_api-1.2.3 → indevolt_api-1.3.0}/readme.md

@@ -197,6 +197,64 @@ config = await api.get_config()
 print(config)
 ```
 
+#### `check_charge_limits(power: int, target_soc: int, generation: int) -> None`
+
+Check that charge parameters do not exceed device limits. Raises an exception if any boundary is violated.
+
+**Parameters:**
+
+- `power` (int): Requested charge power in watts
+- `target_soc` (int): Target state of charge percentage
+- `generation` (int): Device hardware generation (`1` or `2`), available from `get_config()` under `device.generation`
+
+**Raises:**
+
+- `ChargePowerExceedsMaxError`: If `power` exceeds the maximum for the given generation
+- `SocBelowMinimumError`: If `target_soc` is below `MINIMUM_SOC` (5%)
+
+**Example:**
+
+```python
+config = await api.get_config()
+generation = config["device"]["generation"]
+
+try:
+    api.check_charge_limits(power=1000, target_soc=80, generation=generation)
+except ChargePowerExceedsMaxError as e:
+    print(f"Power {e.power}W exceeds max {e.max_power}W for gen {e.generation}")
+except SocBelowMinimumError as e:
+    print(f"Target SOC {e.target_soc}% is below minimum {e.minimum_soc}%")
+```
+
+#### `check_discharge_limits(power: int, target_soc: int, generation: int) -> None`
+
+Check that discharge parameters do not exceed device limits. Raises an exception if any boundary is violated.
+
+**Parameters:**
+
+- `power` (int): Requested discharge power in watts
+- `target_soc` (int): Target state of charge percentage
+- `generation` (int): Device hardware generation (`1` or `2`), available from `get_config()` under `device.generation`
+
+**Raises:**
+
+- `DischargePowerExceedsMaxError`: If `power` exceeds the maximum for the given generation
+- `SocBelowMinimumError`: If `target_soc` is below `MINIMUM_SOC` (5%)
+
+**Example:**
+
+```python
+config = await api.get_config()
+generation = config["device"]["generation"]
+
+try:
+    api.check_discharge_limits(power=600, target_soc=10, generation=generation)
+except DischargePowerExceedsMaxError as e:
+    print(f"Power {e.power}W exceeds max {e.max_power}W for gen {e.generation}")
+except SocBelowMinimumError as e:
+    print(f"Target SOC {e.target_soc}% is below minimum {e.minimum_soc}%")
+```
+
 ### async_discover(timeout: float = 5.0) -> list[DiscoveredDevice]
 
 Discover Indevolt devices on the local network using UDP broadcast.
@@ -239,7 +297,7 @@ if device.name:
 
 ## Exception Handling
 
-The library provides two custom exceptions:
+The library provides custom exceptions for API errors and limit violations.
 
 ### `APIException`
 
@@ -249,6 +307,24 @@ Raised when there's a client error during API communication (network errors, HTT
 
 Raised when an API request times out (default timeout: 10 seconds).
 
+### `ChargePowerExceedsMaxError`
+
+Raised by `check_charge_limits()` when the requested charge power exceeds the device maximum.
+
+**Attributes:** `power`, `max_power`, `generation`
+
+### `DischargePowerExceedsMaxError`
+
+Raised by `check_discharge_limits()` when the requested discharge power exceeds the device maximum.
+
+**Attributes:** `power`, `max_power`, `generation`
+
+### `SocBelowMinimumError`
+
+Raised by `check_charge_limits()` or `check_discharge_limits()` when the target SOC is below the hard minimum of 5%.
+
+**Attributes:** `target_soc`, `minimum_soc`
+
 **Example:**
 
 ```python