socketry 0.2.0__tar.gz → 0.2.2__tar.gz

{socketry-0.2.0 → socketry-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socketry
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python API and CLI for controlling Jackery portable power stations
 Author: Jesus Lopez
 Author-email: Jesus Lopez <jesus@jesusla.com>
@@ -15,7 +15,7 @@ Description-Content-Type: text/markdown
 # socketry
 
 [![CI](https://github.com/jlopez/socketry/actions/workflows/ci.yml/badge.svg)](https://github.com/jlopez/socketry/actions/workflows/ci.yml)
-![Coverage](https://img.shields.io/badge/coverage-74%25-yellowgreen)
+![Coverage](https://img.shields.io/badge/coverage-76%25-yellowgreen)
 ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
 
 Python API and CLI for controlling Jackery portable power stations.

{socketry-0.2.0 → socketry-0.2.2}/README.md

@@ -1,7 +1,7 @@
 # socketry
 
 [![CI](https://github.com/jlopez/socketry/actions/workflows/ci.yml/badge.svg)](https://github.com/jlopez/socketry/actions/workflows/ci.yml)
-![Coverage](https://img.shields.io/badge/coverage-74%25-yellowgreen)
+![Coverage](https://img.shields.io/badge/coverage-76%25-yellowgreen)
 ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
 
 Python API and CLI for controlling Jackery portable power stations.

{socketry-0.2.0 → socketry-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "socketry"
-version = "0.2.0"
+version = "0.2.2"
 description = "Python API and CLI for controlling Jackery portable power stations"
 readme = "README.md"
 authors = [

socketry-0.2.2/src/socketry/__init__.py

@@ -0,0 +1,23 @@
+"""Python API and CLI for controlling Jackery portable power stations."""
+
+from socketry.client import (
+    AuthenticationError,
+    Client,
+    Device,
+    MqttError,
+    SocketryError,
+    Subscription,
+)
+from socketry.properties import MODEL_NAMES, PROPERTIES, Setting
+
+__all__ = [
+    "AuthenticationError",
+    "Client",
+    "Device",
+    "MODEL_NAMES",
+    "MqttError",
+    "PROPERTIES",
+    "Setting",
+    "SocketryError",
+    "Subscription",
+]

{socketry-0.2.0 → socketry-0.2.2}/src/socketry/client.py

@@ -55,10 +55,41 @@ from socketry.properties import Setting, resolve
 _TOKEN_EXPIRY_BUFFER = 3600  # seconds before expiry to trigger proactive refresh
 
 
-class TokenExpiredError(RuntimeError):
+class SocketryError(Exception):
+    """Base exception for all socketry errors."""
+
+
+class TokenExpiredError(SocketryError):
     """Raised when the Jackery API returns error code 10402 (token expired)."""
 
 
+class AuthenticationError(SocketryError):
+    """Raised when login fails after an automatic re-authentication attempt.
+
+    Triggered when the Jackery API returns an auth error (session invalidated
+    by the server) and the automatic re-login attempt also fails (e.g. bad
+    credentials, account suspended).
+    """
+
+
+class _SessionInvalidatedError(SocketryError):
+    """Internal sentinel: API returned a non-token-expiry auth/API error.
+
+    Raised by HTTP helpers to signal that the current session is rejected by
+    the server.  :meth:`Client._relogin` catches this, attempts one re-login,
+    and re-raises as :class:`AuthenticationError` on failure.
+    """
+
+
+class MqttError(SocketryError, ConnectionError):
+    """Raised when an MQTT operation fails.
+
+    Wraps :class:`aiomqtt.MqttError` so callers do not need to import
+    ``aiomqtt`` to catch MQTT-related failures from :meth:`Client.set_property`
+    or :meth:`Device.set_property`.
+    """
+
+
 class Device:
     """A specific Jackery device.
 
@@ -116,6 +147,10 @@ class Device:
                 self._client._creds["tokenExp"] = 0
                 await self._client._ensure_fresh_token()
                 return await _fetch_device_properties(self._client.token, self._id, session)
+            except _SessionInvalidatedError:
+                stale = self._client.token
+                await self._client._relogin(stale)
+                return await _fetch_device_properties(self._client.token, self._id, session)
 
     async def get_property(self, name: str) -> tuple[Setting, object]:
         """Fetch a single property by slug or raw key.
@@ -168,22 +203,25 @@ class Device:
         body: dict[str, object] = {setting.prop_key: int_value}
         assert setting.action_id is not None
 
-        if wait:
-            result = await self._client._publish_and_wait(
-                self._sn,
-                setting.action_id,
-                body,
-                expected_keys=set(body.keys()),
-                verbose=verbose,
-            )
-            if result is not None:
-                resp = result.get("body")
-                if isinstance(resp, dict):
-                    return resp
-            return None
-        else:
-            await self._client._publish_command(self._sn, setting.action_id, body)
-            return None
+        try:
+            if wait:
+                result = await self._client._publish_and_wait(
+                    self._sn,
+                    setting.action_id,
+                    body,
+                    expected_keys=set(body.keys()),
+                    verbose=verbose,
+                )
+                if result is not None:
+                    resp = result.get("body")
+                    if isinstance(resp, dict):
+                        return resp
+                return None
+            else:
+                await self._client._publish_command(self._sn, setting.action_id, body)
+                return None
+        except aiomqtt.MqttError as e:
+            raise MqttError(str(e)) from e
 
 
 class Client:
@@ -273,6 +311,11 @@ class Client:
         """Current JWT auth token."""
         return str(self._creds.get("token", ""))
 
+    @property
+    def user_id(self) -> str:
+        """Authenticated user ID."""
+        return str(self._creds.get("userId", ""))
+
     # ------------------------------------------------------------------
     # Token refresh
     # ------------------------------------------------------------------
@@ -313,6 +356,46 @@ class Client:
             if self._auto_save:
                 self.save_credentials()
 
+    async def _relogin(self, stale_token: str) -> None:
+        """Re-authenticate using stored credentials and update the session.
+
+        Called automatically when the server rejects the current session
+        (:class:`_SessionInvalidatedError`).  Raises :class:`AuthenticationError`
+        if the re-login attempt fails (wrong password, account suspended, etc.)
+        or if no credentials are stored.
+
+        *stale_token* is the token that was rejected.  If another concurrent
+        call has already refreshed the token by the time this call acquires
+        :attr:`_refresh_lock`, the re-login is skipped (the session is already
+        healed).
+
+        Only the auth fields (``token``, ``mqttPassWord``, ``tokenExp``) are
+        updated so that device selection is preserved.
+        """
+        email = str(self._creds.get("email", ""))
+        password = str(self._creds.get("password", ""))
+        if not email or not password:
+            raise AuthenticationError(
+                "Cannot re-authenticate: no email or password stored in credentials."
+            )
+
+        async with self._refresh_lock:
+            # Another concurrent task may have already refreshed the session
+            # while we were waiting for the lock.  If the token has changed,
+            # the session is healed — skip the re-login.
+            if self.token != stale_token:
+                return
+
+            try:
+                new_creds = await _http_login(email, password, fetch_devices=False)
+            except Exception as exc:
+                raise AuthenticationError(f"Re-authentication failed: {exc}") from exc
+            self._creds["token"] = new_creds["token"]
+            self._creds["mqttPassWord"] = new_creds["mqttPassWord"]
+            self._creds["tokenExp"] = new_creds.get("tokenExp")
+            if self._auto_save:
+                self.save_credentials()
+
     # ------------------------------------------------------------------
     # Device management
     # ------------------------------------------------------------------
@@ -330,6 +413,10 @@ class Client:
                 self._creds["tokenExp"] = 0
                 await self._ensure_fresh_token()
                 all_devices = await _fetch_all_devices(self.token, session)
+            except _SessionInvalidatedError:
+                stale = self.token
+                await self._relogin(stale)
+                all_devices = await _fetch_all_devices(self.token, session)
         self._creds["devices"] = all_devices
         return all_devices
 
@@ -358,11 +445,17 @@ class Client:
 
         Raises:
             IndexError: If an integer index is out of range, or no
-                devices are cached.
-            KeyError: If a serial-number string is not found.
+                devices are cached (integer lookup only).
+            KeyError: If a serial-number string is not found, or no
+                devices are cached (string lookup only).
         """
         devs = self.devices
         if not devs:
+            if isinstance(index_or_sn, str):
+                raise KeyError(
+                    f"No device with SN '{index_or_sn}': device list is empty. "
+                    "Call fetch_devices() first."
+                )
             raise IndexError("No cached device list. Call fetch_devices() first.")
         if isinstance(index_or_sn, int):
             if index_or_sn < 0 or index_or_sn >= len(devs):
@@ -393,6 +486,10 @@ class Client:
                 self._creds["tokenExp"] = 0
                 await self._ensure_fresh_token()
                 return await _fetch_device_properties(self.token, self.device_id, session)
+            except _SessionInvalidatedError:
+                stale = self.token
+                await self._relogin(stale)
+                return await _fetch_device_properties(self.token, self.device_id, session)
 
     async def get_property(self, name: str) -> tuple[Setting, object]:
         """Fetch a single property by slug or raw key.
@@ -440,7 +537,7 @@ class Client:
         method cancels the background listener.
         """
         task = asyncio.create_task(self._run_subscribe_loop(callback, on_disconnect=on_disconnect))
-        return Subscription(task)
+        return Subscription(task, self)
 
     # ------------------------------------------------------------------
     # Control (MQTT)
@@ -480,22 +577,25 @@ class Client:
         body: dict[str, object] = {setting.prop_key: int_value}
         assert setting.action_id is not None
 
-        if wait:
-            result = await self._publish_and_wait(
-                self.device_sn,
-                setting.action_id,
-                body,
-                expected_keys=set(body.keys()),
-                verbose=verbose,
-            )
-            if result is not None:
-                resp = result.get("body")
-                if isinstance(resp, dict):
-                    return resp
-            return None
-        else:
-            await self._publish_command(self.device_sn, setting.action_id, body)
-            return None
+        try:
+            if wait:
+                result = await self._publish_and_wait(
+                    self.device_sn,
+                    setting.action_id,
+                    body,
+                    expected_keys=set(body.keys()),
+                    verbose=verbose,
+                )
+                if result is not None:
+                    resp = result.get("body")
+                    if isinstance(resp, dict):
+                        return resp
+                return None
+            else:
+                await self._publish_command(self.device_sn, setting.action_id, body)
+                return None
+        except aiomqtt.MqttError as e:
+            raise MqttError(str(e)) from e
 
     # ------------------------------------------------------------------
     # Private MQTT methods
@@ -646,8 +746,14 @@ class Subscription:
     subscription ends (e.g. via cancellation or error).
     """
 
-    def __init__(self, task: asyncio.Task[None]) -> None:
+    def __init__(self, task: asyncio.Task[None], client: Client) -> None:
         self._task = task
+        self._client = client
+
+    @property
+    def is_connected(self) -> bool:
+        """True when the MQTT broker connection is currently established."""
+        return self._client._active_mqtt is not None
 
     async def stop(self) -> None:
         """Cancel the subscription and wait for cleanup."""
@@ -752,7 +858,7 @@ async def _http_login(
 
         if body.get("code") != 0:
             msg = body.get("msg", "unknown error")
-            raise RuntimeError(f"Login failed: {msg}")
+            raise AuthenticationError(f"Login failed: {msg}")
 
         data = body["data"]
         token = body["token"]
@@ -796,6 +902,9 @@ async def _fetch_all_devices(token: str, session: aiohttp.ClientSession) -> list
         dev_body = await dev_resp.json()
     if dev_body.get("code") == 10402:
         raise TokenExpiredError("Token expired (10402)")
+    if dev_body.get("code") != 0:
+        msg = dev_body.get("msg", "unknown error")
+        raise _SessionInvalidatedError(f"Device list fetch failed: {msg}")
     for d in dev_body.get("data") or []:
         all_devices.append(
             {
@@ -863,7 +972,7 @@ async def _fetch_device_properties(
         raise TokenExpiredError("Token expired (10402)")
     if body.get("code") != 0:
         msg = body.get("msg", "unknown error")
-        raise RuntimeError(f"Property fetch failed: {msg}")
+        raise _SessionInvalidatedError(f"Property fetch failed: {msg}")
     return body.get("data") or {}
 
 

socketry-0.2.0/src/socketry/__init__.py

@@ -1,6 +0,0 @@
-"""Python API and CLI for controlling Jackery portable power stations."""
-
-from socketry.client import Client, Device, Subscription
-from socketry.properties import MODEL_NAMES, PROPERTIES, Setting
-
-__all__ = ["Client", "Device", "MODEL_NAMES", "PROPERTIES", "Setting", "Subscription"]