pybluetti 0.2.0__tar.gz → 0.2.2__tar.gz

{pybluetti-0.2.0 → pybluetti-0.2.2}/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 0.2.2
+
+- `ApplicationRuntimeException`'s `msgCode` is now included in `str(exc)` itself (e.g. `[500] server error`), not just the separate `.msgCode` attribute - every existing caller that logs or displays this exception (notably `bluetti-home-assistant`'s own websocket-error Repair issue, which shows `str(err)` directly to the end user) now surfaces the code with no changes needed on its end. Prompted by a real user hitting an unrecognized code with no way to report which one it was short of digging through a raw STOMP frame dump (bluetti-community/bluetti-home-assistant#35). `.message` is unchanged - still the plain, code-free text.
+
+# 0.2.1rc1 (pre-release)
+
+- Fixed `_run()` leaving the abandoned connection open on every path except a token-expiry (msgCode 805): an `ApplicationRuntimeException`, a plain ERROR/CLOSE message, or an unexpected crash all left `close()` uncalled on the old connection. 0.2.0's heartbeat-task cancellation in `connect()` was only a partial fix - the still-open connection let a concurrently-running heartbeat send slip past its own is-it-closed check and fail against the transport before aiohttp itself noticed the remote side had already closed, reported as "Failed to send heartbeat: Cannot write to closing transport" repeating on every reconnect cycle in production (real-world confirmation: bluetti-official/bluetti-home-assistant#145). `_run()` now closes the connection itself as soon as it decides to abandon it, closing that race instead of just narrowing it.
+
 # 0.2.0
 
 - **Breaking**: `StompClient.__init__`'s `handler`, `on_auth_expired`, and the new `on_error` are now keyword-only (`session`/`url`/`access_token` stay positional). Update any call passing `handler` positionally to `handler=...`.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pybluetti
-Version: 0.2.0
+Version: 0.2.2
 Summary: Async Python client for the BLUETTI cloud API - device discovery, state, and control.
 Project-URL: Homepage, https://github.com/bluetti-community/pybluetti
 Project-URL: Used by, https://github.com/bluetti-community/bluetti-home-assistant

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pybluetti"
-version = "0.2.0"
+version = "0.2.2"
 description = "Async Python client for the BLUETTI cloud API - device discovery, state, and control."
 readme = "README.md"
 license = "MIT"

pybluetti-0.2.2/src/pybluetti/exceptions.py

@@ -0,0 +1,35 @@
+"""Exceptions raised by the pybluetti client."""
+
+from typing import Any
+
+
+class ApplicationRuntimeException(Exception):
+    """Raised when a BLUETTI cloud API call fails."""
+
+    message: str = "An unknown error has occurred."
+    msgCode: int
+    data: dict[str, Any] | str | None = None
+
+    def __init__(
+        self, msgCode: int, data: dict[str, Any] | str | None = None, errMessage: str | None = None
+    ) -> None:
+        self.msgCode = msgCode
+        self.data = data
+
+        if errMessage is not None:
+            self.message = errMessage
+
+        # msgCode is folded into str(self) (not just kept as the separate
+        # .msgCode attribute) because it's the one piece of information
+        # every existing caller that logs or displays this exception
+        # already shows without any changes on their end - notably
+        # bluetti-home-assistant's own websocket-error Repair issue, which
+        # surfaces str(err) directly to the end user (see that repo's
+        # __init__.py, ISSUE_ID_WEBSOCKET_ERROR). Without it, a real user
+        # hitting an unrecognized error code had no way to report which one
+        # they got short of enabling debug logging and finding the raw STOMP
+        # frame themselves (see bluetti-community/bluetti-home-assistant#35,
+        # where exactly that happened - the code was never surfaced anywhere
+        # a person actually looks by default). .message stays the plain,
+        # code-free text for any caller that only wants that.
+        super().__init__(f"[{msgCode}] {self.message}")

{pybluetti-0.2.0 → pybluetti-0.2.2}/src/pybluetti/websocket.py

@@ -190,6 +190,20 @@ class StompClient:
         except Exception:
             __LOGGER__.exception("BLUETTI WebSocket task crashed")
 
+        # Only the msgCode-805 path (handled inline above, not via this
+        # except block) closes ws itself. Every other way out of the loop
+        # above - an ERROR/CLOSE message, a raised ApplicationRuntimeException,
+        # or an unexpected crash - leaves it open from our own side. The
+        # heartbeat task's own is-it-closed check races against however long
+        # aiohttp takes to notice the remote already closed its end, so it
+        # can still slip through and fail the write instead of cleanly
+        # breaking - closing it decisively here, as soon as we've decided to
+        # abandon this connection, is what actually closes that window
+        # (connect()'s heartbeat-task cancellation below is the remaining,
+        # much narrower backstop: mid-send at this exact instant).
+        if not ws.closed:
+            await ws.close()
+
         if self.running:
             await self.reconnect()
 

pybluetti-0.2.2/tests/test_exceptions.py

@@ -0,0 +1,28 @@
+"""Tests for exceptions.py."""
+
+from pybluetti.exceptions import ApplicationRuntimeException
+
+
+def test_str_includes_msg_code_and_custom_message() -> None:
+    # The msgCode must be visible in str(exc) itself, not just the .msgCode
+    # attribute - see this file's own docstring in exceptions.py for why
+    # (bluetti-community/bluetti-home-assistant#35: a real user had no way
+    # to report which error code they got, since nothing that logs or
+    # displays this exception showed it).
+    err = ApplicationRuntimeException(msgCode=1234, errMessage="Upgrade required.")
+
+    assert str(err) == "[1234] Upgrade required."
+    assert err.message == "Upgrade required."
+    assert err.msgCode == 1234
+
+
+def test_str_includes_msg_code_with_default_message() -> None:
+    err = ApplicationRuntimeException(msgCode=500)
+
+    assert str(err) == "[500] An unknown error has occurred."
+
+
+def test_data_is_stored_unchanged() -> None:
+    err = ApplicationRuntimeException(msgCode=401, data="unauthorized")
+
+    assert err.data == "unauthorized"

{pybluetti-0.2.0 → pybluetti-0.2.2}/tests/test_websocket.py

@@ -273,6 +273,7 @@ async def test_run_breaks_on_error_message_type_and_reconnects_if_running():
 
     await client._run()
 
+    assert ws.close_called is True
     client.reconnect.assert_awaited_once()
 
 
@@ -289,6 +290,9 @@ async def test_run_breaks_on_close_message_type_and_skips_reconnect_when_stopped
 
 async def test_run_catches_unexpected_exception_and_reconnects():
     class _BrokenWebSocket:
+        def __init__(self):
+            self.closed = False
+
         def __aiter__(self):
             return self
 
@@ -296,12 +300,18 @@ async def test_run_catches_unexpected_exception_and_reconnects():
             msg = "boom"
             raise RuntimeError(msg)
 
-    client, _session, _on_auth_expired = _client(_BrokenWebSocket())
+        async def close(self):
+            self.closed = True
+
+    ws = _BrokenWebSocket()
+    client, _session, _on_auth_expired = _client(ws)
     client.running = True
     client.reconnect = AsyncMock()
 
     await client._run()
 
+    assert ws.closed is True
+
     client.reconnect.assert_awaited_once()
 
 
@@ -331,7 +341,13 @@ async def test_run_catches_application_runtime_exception_logs_full_and_calls_on_
     assert "BLUETTI WebSocket task crashed (repeat): %s" not in debug_messages
     on_error.assert_called_once()
     assert on_error.call_args[0][0].msgCode == 500
-    assert client._last_error_message == "server error"
+    assert client._last_error_message == "[500] server error"
+    # The real bug this guards against: _run() used to leave the abandoned
+    # connection open on this exact path (only msgCode 805 closed it), so a
+    # concurrently-running heartbeat task could still be mid-send against it
+    # by the time it actually finished closing - "Cannot write to closing
+    # transport", repeating on every retry cycle in production.
+    assert ws.close_called is True
     client.reconnect.assert_awaited_once()
 
 
@@ -341,7 +357,7 @@ async def test_run_downgrades_repeated_identical_application_runtime_exception()
     client = StompClient(session, GATEWAY_WS_URL, "token")
     client._ws = ws
     client.running = True
-    client._last_error_message = "server error"  # already logged once, on a previous retry
+    client._last_error_message = "[500] server error"  # already logged once, on a previous retry
     client.reconnect = AsyncMock()
 
     with patch("pybluetti.websocket.__LOGGER__") as logger:
@@ -358,14 +374,14 @@ async def test_run_relogs_in_full_once_the_error_message_changes():
     client = StompClient(session, GATEWAY_WS_URL, "token")
     client._ws = ws
     client.running = True
-    client._last_error_message = "server error"
+    client._last_error_message = "[500] server error"
     client.reconnect = AsyncMock()
 
     with patch("pybluetti.websocket.__LOGGER__") as logger:
         await client._run()
 
     logger.exception.assert_called_once_with("BLUETTI WebSocket task crashed")
-    assert client._last_error_message == "a different error"
+    assert client._last_error_message == "[500] a different error"
 
 
 async def test_run_application_runtime_exception_without_on_error_does_not_raise():

pybluetti-0.2.0/src/pybluetti/exceptions.py

@@ -1,22 +0,0 @@
-"""Exceptions raised by the pybluetti client."""
-
-from typing import Any
-
-
-class ApplicationRuntimeException(Exception):
-    """Raised when a BLUETTI cloud API call fails."""
-
-    message: str = "An unknown error has occurred."
-    msgCode: int
-    data: dict[str, Any] | str | None = None
-
-    def __init__(
-        self, msgCode: int, data: dict[str, Any] | str | None = None, errMessage: str | None = None
-    ) -> None:
-        self.msgCode = msgCode
-        self.data = data
-
-        if errMessage is not None:
-            self.message = errMessage
-
-        super().__init__(self.message)