comwatt-client 0.2.2__tar.gz → 0.2.4__tar.gz

{comwatt_client-0.2.2/comwatt_client.egg-info → comwatt_client-0.2.4}/PKG-INFO

@@ -1,19 +1,19 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: comwatt-client
-Version: 0.2.2
+Version: 0.2.4
 Summary: Python Client for Comwatt API
-Home-page: https://github.com/MateoGreil/python-comwatt-client
-Author: Matéo Greil
-Author-email: contact@greil.fr
+Author-email: Matéo Greil <contact@greil.fr>
+Project-URL: Homepage, https://github.com/MateoGreil/python-comwatt-client
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
-Requires-Dist: requests
+Requires-Dist: requests>=2.32.4
 
 # Comwatt Python Client
 
@@ -25,13 +25,26 @@ Please note that the Comwatt client is exclusively for gen4 devices: it use `ene
 ## Features
 The client currently supports the following methods:
 
-- `authenticate(self, username, password)`: Authenticates a user with the provided username and password.
+- `authenticate(self, username, password)`: Authenticates a user with the provided username and password. The client re-authenticates automatically on session expiry (HTTP 401) and retries the request once; pass `ComwattClient(auto_reauth=False)` to disable this.
+- `is_authenticated(self)`: Returns whether the current session is still valid (probes the API; `True`/`False`, re-raises unexpected errors).
 - `get_authenticated_user(self)`: Retrieves information about the authenticated user.
 - `get_sites(self)`: Retrieves a list of sites associated with the authenticated user.
-- `get_site_networks_ts_time_ago(self, site_id, measure_kind = "VIRTUAL_QUANTITY", aggregation_level = "HOUR", aggregation_type = "SUM", time_ago_unit = "DAY", time_ago_value = 1)`: Retrieves the time series data for the networks of a specific site, based on the provided parameters.
-- `get_site_consumption_breakdown_time_ago(self, site_id, aggregation_level = "HOUR", time_ago_unit = "DAY", time_ago_value = 1)` Retrieves the consumption breakdown data for a specific site, based on the provided parameters.
+- `get_site_networks_ts_time_ago(self, site_id, measure_kind = "FLOW", aggregation_level = "NONE", aggregation_type = None, time_ago_unit = "HOUR", time_ago_value = 1, start = None, end = None)`: Retrieves the time series data for the networks of a specific site, based on the provided parameters.
+- `get_site_consumption_breakdown_time_ago(self, site_id, aggregation_level = "HOUR", time_ago_unit = "DAY", time_ago_value = 1, start = None, end = None)` Retrieves the consumption breakdown data for a specific site, based on the provided parameters.
 - `get_devices(self, site_id)`: Retrieves a list of devices for the specified site.
-- `get_device_ts_time_ago(self, device_id, measure_kind = "FLOW", aggregation_level = "HOUR", aggregation_type = "MAX", time_ago_unit = "DAY", time_ago_value = "1")`: Retrieves the time series data for a specific device, based on the provided parameters.
+- `get_device_ts_time_ago(self, device_id, measure_kind = "FLOW", aggregation_level = "HOUR", aggregation_type = "MAX", time_ago_unit = "DAY", time_ago_value = "1", start = None, end = None)`: Retrieves the time series data for a specific device, based on the provided parameters.
+
+`start`/`end` accept a `datetime` or ISO-8601 string and select an absolute window instead of the relative `time_ago_*` params; a naive `datetime` is treated as UTC:
+
+```python
+from datetime import datetime
+
+client.get_device_ts_time_ago(
+    "device-1",
+    start=datetime(2026, 7, 4, 0, 0, 0),
+    end=datetime(2026, 7, 5, 0, 0, 0),
+)
+```
 - `get_device(self, device_id)`: Retrieves information about a specific device.
 - `put_device(self, device_id, payload)`: Updates a specific device with the provided payload.
 
@@ -46,7 +59,7 @@ pip install comwatt-client
 Here's a simple example of how to use the Comwatt Python Client:
 
 ```python
-from comwatt.client import ComwattClient
+from comwatt_client import ComwattClient
 
 # Create a Comwatt client instance
 client = ComwattClient()
@@ -95,5 +108,25 @@ client.switch_capacity(capacity_id, True)
 
 Make sure to replace `'username'`, `'password'` with the actual values for your Comwatt account.
 
+## Error handling
+
+All errors raised by the client subclass `ComwattError`:
+
+- `ComwattAuthError` — login failed or the session expired (HTTP 401). Re-authenticate.
+- `ComwattAPIError` — any other unexpected HTTP status. Exposes `.status_code`, `.url`, `.detail`.
+
+```python
+from comwatt_client import ComwattClient, ComwattAuthError, ComwattAPIError
+
+client = ComwattClient()
+try:
+    client.authenticate("username", "password")
+    sites = client.get_sites()
+except ComwattAuthError:
+    ...  # credentials wrong or session expired — re-authenticate
+except ComwattAPIError as e:
+    print(e.status_code, e.url, e.detail)
+```
+
 ## Contributing
 Contributions to the Comwatt Python Client are welcome! If you find any issues or have suggestions for improvement, please open an issue or submit a pull request on the GitHub repository.

comwatt_client-0.2.2/PKG-INFO → comwatt_client-0.2.4/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.1
-Name: comwatt-client
-Version: 0.2.2
-Summary: Python Client for Comwatt API
-Home-page: https://github.com/MateoGreil/python-comwatt-client
-Author: Matéo Greil
-Author-email: contact@greil.fr
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Description-Content-Type: text/markdown
-Requires-Dist: requests
-
 # Comwatt Python Client
 
 ## Overview
@@ -25,13 +8,26 @@ Please note that the Comwatt client is exclusively for gen4 devices: it use `ene
 ## Features
 The client currently supports the following methods:
 
-- `authenticate(self, username, password)`: Authenticates a user with the provided username and password.
+- `authenticate(self, username, password)`: Authenticates a user with the provided username and password. The client re-authenticates automatically on session expiry (HTTP 401) and retries the request once; pass `ComwattClient(auto_reauth=False)` to disable this.
+- `is_authenticated(self)`: Returns whether the current session is still valid (probes the API; `True`/`False`, re-raises unexpected errors).
 - `get_authenticated_user(self)`: Retrieves information about the authenticated user.
 - `get_sites(self)`: Retrieves a list of sites associated with the authenticated user.
-- `get_site_networks_ts_time_ago(self, site_id, measure_kind = "VIRTUAL_QUANTITY", aggregation_level = "HOUR", aggregation_type = "SUM", time_ago_unit = "DAY", time_ago_value = 1)`: Retrieves the time series data for the networks of a specific site, based on the provided parameters.
-- `get_site_consumption_breakdown_time_ago(self, site_id, aggregation_level = "HOUR", time_ago_unit = "DAY", time_ago_value = 1)` Retrieves the consumption breakdown data for a specific site, based on the provided parameters.
+- `get_site_networks_ts_time_ago(self, site_id, measure_kind = "FLOW", aggregation_level = "NONE", aggregation_type = None, time_ago_unit = "HOUR", time_ago_value = 1, start = None, end = None)`: Retrieves the time series data for the networks of a specific site, based on the provided parameters.
+- `get_site_consumption_breakdown_time_ago(self, site_id, aggregation_level = "HOUR", time_ago_unit = "DAY", time_ago_value = 1, start = None, end = None)` Retrieves the consumption breakdown data for a specific site, based on the provided parameters.
 - `get_devices(self, site_id)`: Retrieves a list of devices for the specified site.
-- `get_device_ts_time_ago(self, device_id, measure_kind = "FLOW", aggregation_level = "HOUR", aggregation_type = "MAX", time_ago_unit = "DAY", time_ago_value = "1")`: Retrieves the time series data for a specific device, based on the provided parameters.
+- `get_device_ts_time_ago(self, device_id, measure_kind = "FLOW", aggregation_level = "HOUR", aggregation_type = "MAX", time_ago_unit = "DAY", time_ago_value = "1", start = None, end = None)`: Retrieves the time series data for a specific device, based on the provided parameters.
+
+`start`/`end` accept a `datetime` or ISO-8601 string and select an absolute window instead of the relative `time_ago_*` params; a naive `datetime` is treated as UTC:
+
+```python
+from datetime import datetime
+
+client.get_device_ts_time_ago(
+    "device-1",
+    start=datetime(2026, 7, 4, 0, 0, 0),
+    end=datetime(2026, 7, 5, 0, 0, 0),
+)
+```
 - `get_device(self, device_id)`: Retrieves information about a specific device.
 - `put_device(self, device_id, payload)`: Updates a specific device with the provided payload.
 
@@ -46,7 +42,7 @@ pip install comwatt-client
 Here's a simple example of how to use the Comwatt Python Client:
 
 ```python
-from comwatt.client import ComwattClient
+from comwatt_client import ComwattClient
 
 # Create a Comwatt client instance
 client = ComwattClient()
@@ -95,5 +91,25 @@ client.switch_capacity(capacity_id, True)
 
 Make sure to replace `'username'`, `'password'` with the actual values for your Comwatt account.
 
+## Error handling
+
+All errors raised by the client subclass `ComwattError`:
+
+- `ComwattAuthError` — login failed or the session expired (HTTP 401). Re-authenticate.
+- `ComwattAPIError` — any other unexpected HTTP status. Exposes `.status_code`, `.url`, `.detail`.
+
+```python
+from comwatt_client import ComwattClient, ComwattAuthError, ComwattAPIError
+
+client = ComwattClient()
+try:
+    client.authenticate("username", "password")
+    sites = client.get_sites()
+except ComwattAuthError:
+    ...  # credentials wrong or session expired — re-authenticate
+except ComwattAPIError as e:
+    print(e.status_code, e.url, e.detail)
+```
+
 ## Contributing
 Contributions to the Comwatt Python Client are welcome! If you find any issues or have suggestions for improvement, please open an issue or submit a pull request on the GitHub repository.

comwatt_client-0.2.4/comwatt_client/__init__.py

@@ -0,0 +1,4 @@
+from .client import ComwattClient
+from .exceptions import ComwattError, ComwattAuthError, ComwattAPIError
+
+__all__ = ["ComwattClient", "ComwattError", "ComwattAuthError", "ComwattAPIError"]

comwatt_client-0.2.4/comwatt_client/client.py

@@ -0,0 +1,440 @@
+from __future__ import annotations
+
+import requests
+import json
+import hashlib
+
+from datetime import datetime, timezone
+from types import TracebackType
+from typing import Any, TYPE_CHECKING
+
+from .exceptions import ComwattAPIError, ComwattAuthError, ComwattError
+
+
+def _format_timestamp(value: datetime | str) -> str:
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    if isinstance(value, str):
+        return value
+    raise TypeError(f"Expected datetime or str, got {type(value).__name__}")
+
+
+def _aggregations_query(*, id_param: str, id_value: int | str, aggregation_level: str,
+        measure_kind: str | None = None, aggregation_type: str | None = None,
+        time_ago_unit: str | None = None, time_ago_value: int | str | None = None,
+        start: datetime | str | None = None, end: datetime | str | None = None) -> dict[str, str]:
+    if end is not None and start is None:
+        raise ValueError("end requires start")
+
+    params: dict[str, str] = {id_param: str(id_value), "aggregationLevel": aggregation_level}
+
+    if measure_kind is not None:
+        params["measureKind"] = measure_kind
+    if aggregation_type is not None:
+        params["aggregationType"] = aggregation_type
+
+    if start is not None:
+        params["start"] = _format_timestamp(start)
+        if end is not None:
+            params["end"] = _format_timestamp(end)
+    else:
+        if time_ago_unit is not None:
+            params["timeAgoUnit"] = time_ago_unit
+        if time_ago_value is not None:
+            params["timeAgoValue"] = str(time_ago_value)
+
+    return params
+
+
+def _response_detail(response: requests.Response) -> str | None:
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    if isinstance(body, dict):
+        return body.get("detail")
+    return None
+
+
+def _api_error(response: requests.Response) -> ComwattError:
+    detail = _response_detail(response)
+    exc_cls = ComwattAuthError if response.status_code == 401 else ComwattAPIError
+    return exc_cls(status_code=response.status_code, url=response.url, detail=detail, response=response)
+
+
+class ComwattClient:
+    """
+    A client for interacting with the Comwatt API.
+
+    Args:
+        None
+
+    Attributes:
+        base_url (str): The base URL of the Comwatt API.
+        session (requests.Session): The session object for making HTTP requests.
+
+    """
+    def __init__(self, timeout: float = 30, auto_reauth: bool = True) -> None:
+        self.base_url = 'https://energy.comwatt.com/api'
+        self.session = requests.Session()
+        self.timeout = timeout
+        self.auto_reauth = auto_reauth
+        self._username: str | None = None
+        self._auth_hash: str | None = None
+
+    @staticmethod
+    def _hash_password(password: str) -> str:
+        return hashlib.sha256(f'jbjaonfusor_{password}_4acuttbuik9'.encode()).hexdigest()
+
+    def _post_authent(self, username: str, password_hash: str) -> None:
+        url = f'{self.base_url}/v1/authent'
+        data = {'username': username, 'password': password_hash}
+
+        response = self.session.post(url, json=data, timeout=self.timeout)
+
+        if response.status_code != 200:
+            detail = _response_detail(response)
+            raise ComwattAuthError(status_code=response.status_code, url=response.url, detail=detail, response=response)
+
+        if not self.session.cookies.get("cwt_session"):
+            raise ComwattAuthError("Authentication succeeded (HTTP 200) but no cwt_session cookie was set")
+
+    def authenticate(self, username: str, password: str) -> None:
+        """
+        Authenticates a user with the provided username and password.
+
+        Args:
+            username (str): The username of the user.
+            password (str): The password of the user.
+
+        Returns:
+            None
+
+        Raises:
+            Exception: If the authentication fails.
+
+        """
+
+        password_hash = self._hash_password(password)
+        self._post_authent(username, password_hash)
+
+        self._username = username
+        self._auth_hash = password_hash
+
+    def _reauthenticate(self) -> None:
+        if self._username and self._auth_hash:
+            self._post_authent(self._username, self._auth_hash)
+        else:
+            raise ComwattAuthError("Session expired and no stored credentials to re-authenticate")
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> requests.Response:
+        url = f'{self.base_url}{path}'
+        response = self.session.request(method, url, timeout=self.timeout, **kwargs)
+        if response.status_code == 200:
+            return response
+
+        if response.status_code == 401 and self.auto_reauth and self._username and self._auth_hash:
+            self._reauthenticate()
+            retry_response = self.session.request(method, url, timeout=self.timeout, **kwargs)
+            if retry_response.status_code == 200:
+                return retry_response
+            raise _api_error(retry_response)
+
+        raise _api_error(response)
+
+    def is_authenticated(self) -> bool:
+        """
+        Checks whether the current session cookie is still accepted by the API.
+
+        Args:
+            None
+
+        Returns:
+            bool: True if the session is authenticated, False if the API
+                rejected it (401/403).
+
+        Raises:
+            Exception: If an unexpected error occurs while probing the API.
+
+        """
+
+        url = f'{self.base_url}/users/authenticated'
+
+        response = self.session.get(url, timeout=self.timeout)
+        if response.status_code == 200:
+            return True
+        elif response.status_code in (401, 403):
+            return False
+        else:
+            raise _api_error(response)
+
+    def get_authenticated_user(self) -> dict[str, Any]:
+        """
+        Retrieves information about the authenticated user.
+
+        Args:
+            None
+
+        Returns:
+            dict: Information about the authenticated user.
+
+        Raises:
+            Exception: If an error occurs while retrieving the information.
+
+        """
+
+        return self._request("GET", "/users/authenticated").json()
+
+    def get_sites(self) -> list[dict[str, Any]]:
+        """
+        Retrieves a list of sites associated with the authenticated user.
+
+        Args:
+            None
+
+        Returns:
+            list: A list of sites.
+
+        Raises:
+            Exception: If an error occurs while retrieving the sites.
+
+        """
+
+        return self._request("GET", "/sites").json()
+
+
+    def get_site_networks_ts_time_ago(self, site_id: int | str,
+            measure_kind: str = "FLOW",
+            aggregation_level: str = "NONE",
+            aggregation_type: str | None = None,
+            time_ago_unit: str = "HOUR",
+            time_ago_value: int | str = 1,
+            start: datetime | str | None = None,
+            end: datetime | str | None = None) -> dict[str, Any]:
+        """
+        Retrieves the time series data for the networks of a specific site, based on the provided parameters.
+
+        Args:
+            site_id (str): The ID of the site.
+            measure_kind (str): The kind of measure (default: "FLOW").
+            aggregation_level (str): The aggregation level (default: "NONE").
+            aggregation_type (str): The aggregation type (default: None, can be : None, "SUM", "MAX").
+            time_ago_unit (str): The unit of time ago (default: "HOUR").
+            time_ago_value (int): The value of time ago (default: 1).
+            start (datetime | str): The start of an absolute time window (default: None).
+                Accepts a `datetime` or an ISO-8601 string; a naive `datetime` is treated as UTC.
+                When provided, the relative `time_ago_unit`/`time_ago_value` parameters are ignored.
+            end (datetime | str): The end of an absolute time window (default: None).
+                Accepts a `datetime` or an ISO-8601 string; a naive `datetime` is treated as UTC.
+                Defaults server-side to "now" when omitted. Passing `end` without `start` raises `ValueError`.
+
+        Returns:
+            dict: The time series data.
+
+        Raises:
+            ValueError: If `end` is given without `start`.
+            Exception: If an error occurs while retrieving the data.
+
+        """
+
+        params = _aggregations_query(
+            id_param="siteId", id_value=site_id, aggregation_level=aggregation_level,
+            measure_kind=measure_kind, aggregation_type=aggregation_type,
+            time_ago_unit=time_ago_unit, time_ago_value=time_ago_value,
+            start=start, end=end,
+        )
+
+        return self._request("GET", "/aggregations/site-networks-ts-time-ago", params=params).json()
+
+    def get_site_consumption_breakdown_time_ago(self, site_id: int | str,
+            aggregation_level: str = "HOUR",
+            time_ago_unit: str = "DAY",
+            time_ago_value: int | str = 1,
+            start: datetime | str | None = None,
+            end: datetime | str | None = None) -> dict[str, Any]:
+        """
+        Retrieves the consumption breakdown data for a specific site, based on the provided parameters.
+
+        Args:
+            site_id (str): The ID of the site.
+            aggregation_level (str): The aggregation level (default: "HOUR").
+            time_ago_unit (str): The unit of time ago (default: "DAY").
+            time_ago_value (int): The value of time ago (default: 1).
+            start (datetime | str): The start of an absolute time window (default: None).
+                Accepts a `datetime` or an ISO-8601 string; a naive `datetime` is treated as UTC.
+                When provided, the relative `time_ago_unit`/`time_ago_value` parameters are ignored.
+            end (datetime | str): The end of an absolute time window (default: None).
+                Accepts a `datetime` or an ISO-8601 string; a naive `datetime` is treated as UTC.
+                Defaults server-side to "now" when omitted. Passing `end` without `start` raises `ValueError`.
+
+        Returns:
+            dict: The consumption breakdown data.
+
+        Raises:
+            ValueError: If `end` is given without `start`.
+            Exception: If an error occurs while retrieving the data.
+
+        """
+
+        params = _aggregations_query(
+            id_param="siteId", id_value=site_id, aggregation_level=aggregation_level,
+            time_ago_unit=time_ago_unit, time_ago_value=time_ago_value,
+            start=start, end=end,
+        )
+
+        return self._request("GET", "/aggregations/consumption-breakdown-time-ago", params=params).json()
+
+    def get_devices(self, site_id: int | str) -> list[dict[str, Any]]:
+        """
+        Retrieves a list of devices for the specified site.
+
+        Args:
+            site_id (str): The ID of the site.
+
+        Returns:
+            list: A list of devices.
+
+        Raises:
+            Exception: If an error occurs while retrieving the devices.
+
+        """
+
+        return self._request("GET", f"/devices?siteId={site_id}").json()
+
+    def get_device(self, device_id: int | str) -> dict[str, Any]:
+        """
+        Retrieves information about a specific device.
+
+        Args:
+            device_id (str): The ID of the device.
+
+        Returns:
+            dict: A dictionary containing the device information.
+
+        """
+        return self._request("GET", f"/devices/{device_id}").json()
+
+    def put_device(self, device_id: int | str, payload: dict[str, Any]) -> dict[str, Any]:
+        """
+        Updates a specific device with the provided payload.
+
+        Args:
+            device_id (str): The ID of the device.
+            payload (dict): The payload to update the device.
+
+        Returns:
+            dict: A dictionary containing the response from the API.
+
+        """
+        return self._request("PUT", f"/devices/{device_id}", json=payload).json()
+
+
+    def get_device_ts_time_ago(self, device_id: int | str,
+            measure_kind: str = "FLOW",
+            aggregation_level: str = "HOUR",
+            aggregation_type: str = "MAX",
+            time_ago_unit: str = "DAY",
+            time_ago_value: int | str = "1",
+            start: datetime | str | None = None,
+            end: datetime | str | None = None) -> dict[str, Any]:
+        """
+        Retrieves the time series data for a specific device, based on the provided parameters.
+
+        Args:
+            device_id (str): The ID of the device.
+            measure_kind (str): The kind of measure (default: "FLOW").
+            aggregation_level (str): The aggregation level (default: "HOUR").
+            aggregation_type (str): The aggregation type (default: "MAX").
+            time_ago_unit (str): The unit of time ago (default: "DAY").
+            time_ago_value (str): The value of time ago (default: "1").
+            start (datetime | str): The start of an absolute time window (default: None).
+                Accepts a `datetime` or an ISO-8601 string; a naive `datetime` is treated as UTC.
+                When provided, the relative `time_ago_unit`/`time_ago_value` parameters are ignored.
+            end (datetime | str): The end of an absolute time window (default: None).
+                Accepts a `datetime` or an ISO-8601 string; a naive `datetime` is treated as UTC.
+                Defaults server-side to "now" when omitted. Passing `end` without `start` raises `ValueError`.
+
+        Returns:
+            dict: The time series data.
+
+        Raises:
+            ValueError: If `end` is given without `start`.
+            Exception: If an error occurs while retrieving the data.
+
+        """
+
+        params = _aggregations_query(
+            id_param="id", id_value=device_id, aggregation_level=aggregation_level,
+            measure_kind=measure_kind, aggregation_type=aggregation_type,
+            time_ago_unit=time_ago_unit, time_ago_value=time_ago_value,
+            start=start, end=end,
+        )
+
+        return self._request("GET", "/aggregations/time-series", params=params).json()
+
+    def switch_capacity(self, capacity_id: int | str, enable: bool) -> dict[str, Any]:
+        """
+        Switch a specific capcaity to the enable value.
+
+        Args:
+            capacity_id (str): The ID of the capacity.
+            enable (bool): The target state.
+
+        Returns:
+            dict: A dictionary containing the response from the API.
+
+        """
+        return self._request("PUT", f"/capacities/{capacity_id}/switch?enable={str(enable).lower()}").json()
+
+    def close(self) -> None:
+        """
+        Releases the local HTTP resources held by the client.
+
+        This only closes the local `requests.Session` (its connection pool
+        and sockets). It does not perform any network call, so it does not
+        log out server-side (no `POST /v1/logout` is issued) and does not
+        invalidate the Comwatt server session.
+
+        Safe to call multiple times.
+
+        Args:
+            None
+
+        Returns:
+            None
+
+        """
+
+        self.session.close()
+
+    def __enter__(self) -> ComwattClient:
+        """
+        Enters the runtime context for this client.
+
+        Args:
+            None
+
+        Returns:
+            ComwattClient: This client instance.
+
+        """
+
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) -> None:
+        """
+        Exits the runtime context, closing the client's local resources.
+
+        Args:
+            exc_type (type): The exception type, if any.
+            exc_val (Exception): The exception instance, if any.
+            exc_tb (traceback): The exception traceback, if any.
+
+        Returns:
+            None
+
+        """
+
+        self.close()

comwatt_client-0.2.4/comwatt_client/exceptions.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import requests
+
+
+class ComwattError(Exception):
+    """Base class for all errors raised by the Comwatt client."""
+
+    def __init__(self, message: str | None = None, *, status_code: int | None = None, url: str | None = None, detail: str | None = None, response: requests.Response | None = None) -> None:
+        self.status_code = status_code
+        self.url = url
+        self.detail = detail
+        self.response = response
+        if message is None:
+            message = f"{status_code} {url}"
+            if detail:
+                message = f"{message}: {detail}"
+        super().__init__(message)
+
+
+class ComwattAuthError(ComwattError):
+    """The session is invalid or login failed (HTTP 401, or a failed authenticate()).
+    Callers should re-authenticate."""
+
+
+class ComwattAPIError(ComwattError):
+    """Any other unexpected HTTP status from the Comwatt API."""