pySmartHashtag 0.8.2__tar.gz → 0.9.0__tar.gz

pysmarthashtag-0.9.0/.devcontainer.json

@@ -0,0 +1,27 @@
+{
+  "name": "pySmartHashtag",
+  "image": "mcr.microsoft.com/devcontainers/python:dev-3.14-bookworm",
+  "postCreateCommand": "pip install -r requirements.txt && pip install -r requirements-test.txt && pip install -e .",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "charliermarsh.ruff",
+        "github.vscode-pull-request-github",
+        "ryanluker.vscode-coverage-gutters",
+        "ms-python.vscode-pylance"
+      ],
+      "settings": {
+        "files.eol": "\n",
+        "editor.tabSize": 4,
+        "python.analysis.autoSearchPaths": false,
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnPaste": false,
+        "editor.formatOnSave": true,
+        "editor.formatOnType": true,
+        "files.trimTrailingWhitespace": true
+      }
+    }
+  },
+  "remoteUser": "vscode"
+}

{pysmarthashtag-0.8.2 → pysmarthashtag-0.9.0}/.github/workflows/python-package.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4.1.1
@@ -47,6 +47,7 @@ jobs:
           pytest --cov=pysmarthashtag --cov-report=xml --cov-report=term-missing --cov-fail-under=80 pysmarthashtag/tests/
       - name: Pytest coverage comment
         id: coverageComment
+        if: github.event_name != 'pull_request'
         uses: MishaKav/pytest-coverage-comment@main
         with:
           pytest-xml-coverage-path: ./coverage.xml

{pysmarthashtag-0.8.2/pySmartHashtag.egg-info → pysmarthashtag-0.9.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pySmartHashtag
-Version: 0.8.2
-Summary: A python library to get information from Smart #1 and #3 web API
+Version: 0.9.0
+Summary: A python library to get information from Smart #1, #3 and #5 web API
 Home-page: https://github.com/dasBasti/pySmartHashtag
 Author: dasBasti
 Author-email: Bastian Neumann <neumann.bastian@gmail.com>
@@ -52,7 +52,7 @@ Dynamic: license-file
 [![CodeQL Validation][codeql-shield]][codeql]
 [![Dependency Validation][tests-shield]][tests]
 
-API wrapper for Smart #1 and #3 Cloud Service
+API wrapper for Smart #1, #3 and #5 Cloud Service
 
 Regard this to be kind of stable. This library is used in custom [Homeassistant](https://homeassistant.io) component [Smart Hashtag](https://github.com/DasBasti/SmartHashtag)
 

{pysmarthashtag-0.8.2 → pysmarthashtag-0.9.0}/README.md

@@ -5,7 +5,7 @@
 [![CodeQL Validation][codeql-shield]][codeql]
 [![Dependency Validation][tests-shield]][tests]
 
-API wrapper for Smart #1 and #3 Cloud Service
+API wrapper for Smart #1, #3 and #5 Cloud Service
 
 Regard this to be kind of stable. This library is used in custom [Homeassistant](https://homeassistant.io) component [Smart Hashtag](https://github.com/DasBasti/SmartHashtag)
 

{pysmarthashtag-0.8.2 → pysmarthashtag-0.9.0/pySmartHashtag.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pySmartHashtag
-Version: 0.8.2
-Summary: A python library to get information from Smart #1 and #3 web API
+Version: 0.9.0
+Summary: A python library to get information from Smart #1, #3 and #5 web API
 Home-page: https://github.com/dasBasti/pySmartHashtag
 Author: dasBasti
 Author-email: Bastian Neumann <neumann.bastian@gmail.com>
@@ -52,7 +52,7 @@ Dynamic: license-file
 [![CodeQL Validation][codeql-shield]][codeql]
 [![Dependency Validation][tests-shield]][tests]
 
-API wrapper for Smart #1 and #3 Cloud Service
+API wrapper for Smart #1, #3 and #5 Cloud Service
 
 Regard this to be kind of stable. This library is used in custom [Homeassistant](https://homeassistant.io) component [Smart Hashtag](https://github.com/DasBasti/SmartHashtag)
 

{pysmarthashtag-0.8.2 → pysmarthashtag-0.9.0}/pySmartHashtag.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+.devcontainer.json
 .gitignore
 .pre-commit-config.yaml
 AUTHORS
@@ -42,6 +43,7 @@ pysmarthashtag/tests/common.py
 pysmarthashtag/tests/conftest.py
 pysmarthashtag/tests/test_account.py
 pysmarthashtag/tests/test_actions.py
+pysmarthashtag/tests/test_authentication_backoff.py
 pysmarthashtag/tests/test_charging.py
 pysmarthashtag/tests/test_dc_charging.py
 pysmarthashtag/tests/test_endpoint_urls.py

{pysmarthashtag-0.8.2 → pysmarthashtag-0.9.0}/pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 authors = [
     {"name" = "Bastian Neumann", "email" = "neumann.bastian@gmail.com"},
 ]
-description = "A python library to get information from Smart #1 and #3 web API"
+description = "A python library to get information from Smart #1, #3 and #5 web API"
 license = {file = "LICENSE"}
 readme = "README.md"
 requires-python = ">=3.9"

pysmarthashtag-0.9.0/pysmarthashtag/__init__.py

@@ -0,0 +1,9 @@
+"""Library to read data from the Smart API."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+try:
+    __version__ = version("pySmartHashtag")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

{pysmarthashtag-0.8.2 → pysmarthashtag-0.9.0}/pysmarthashtag/api/authentication.py

@@ -28,9 +28,34 @@ EXPIRES_AT_OFFSET = datetime.timedelta(seconds=HTTPX_TIMEOUT * 2)
 _LOGGER = logging.getLogger(__name__)
 
 
+# PATCH: shared breaker state so HA's config_entries retry storm (which
+# creates fresh SmartAuthentication instances) cannot bypass the quiet
+# window. Keyed by username — state persists for the lifetime of the
+# Python process.
+class _BackoffState:
+    __slots__ = ("backoff", "quiet_until")
+
+    def __init__(self, backoff: datetime.timedelta) -> None:
+        self.backoff: datetime.timedelta = backoff
+        self.quiet_until: Optional[datetime.datetime] = None
+
+
+_BACKOFF_REGISTRY: dict[str, _BackoffState] = {}
+
+
 class SmartAuthentication(httpx.Auth):
     """Authentication and Retry Handler for the Smart API."""
 
+    # PATCH: Adaptive rate-limit backoff (AIMD).
+    # On rate-limit failure (HTTP 403/429), multiply current backoff by GROW (capped at CAP).
+    # On success, subtract SHRINK (floored at FLOOR). On non-rate-limit failure,
+    # use a fixed short backoff so transient blips don't grow the window.
+    _BACKOFF_FLOOR = datetime.timedelta(minutes=2)
+    _BACKOFF_CAP = datetime.timedelta(minutes=90)
+    _BACKOFF_GROW = 1.5
+    _BACKOFF_SHRINK = datetime.timedelta(minutes=1)
+    _OTHER_FAILURE_BACKOFF = datetime.timedelta(seconds=60)
+
     def __init__(
         self,
         username: str,
@@ -53,6 +78,13 @@ class SmartAuthentication(httpx.Auth):
         self.api_user_id: Optional[str] = None
         self.ssl_context: Optional[ssl.SSLContext] = ssl_context
         self.endpoint_urls: EndpointUrls = endpoint_urls if endpoint_urls is not None else EndpointUrls()
+        # PATCH: shared adaptive-backoff state (per username, module-scoped).
+        # Sharing across instances is essential because HA's config_entries
+        # retry mechanism creates fresh SmartAuthentication instances on
+        # every retry — per-instance state would never accumulate.
+        if username not in _BACKOFF_REGISTRY:
+            _BACKOFF_REGISTRY[username] = _BackoffState(self._BACKOFF_FLOOR)
+        self._state: _BackoffState = _BACKOFF_REGISTRY[username]
         _LOGGER.debug("Device ID initialized")
 
     async def get_ssl_context(self) -> ssl.SSLContext:
@@ -167,8 +199,87 @@ class SmartAuthentication(httpx.Auth):
             _LOGGER.debug("Refreshing access token failed. Logging in again")
             return {}
 
-    async def _login(self):
-        """Login to Smart web services."""
+    async def _login(self) -> dict:
+        """Login to Smart web services with adaptive rate-limit backoff (PATCH).
+
+        Wraps the original login flow (now ``_do_login``) with:
+          * an in-memory circuit breaker (shared per-username) that suppresses
+            calls while inside an adaptive quiet window, and
+          * AIMD backoff: rate-limit failures grow the window geometrically,
+            successes shrink it additively.
+        """
+        now = datetime.datetime.now(datetime.timezone.utc)
+        if self._state.quiet_until is not None and now < self._state.quiet_until:
+            wait_s = int((self._state.quiet_until - now).total_seconds())
+            raise SmartAPIError(
+                "Smart API in adaptive quiet window for another "
+                f"{wait_s}s (until "
+                f"{self._state.quiet_until.isoformat(timespec='seconds')}, "
+                f"backoff={self._state.backoff})"
+            )
+        try:
+            result = await self._do_login()
+        except (SmartAPIError, httpx.HTTPStatusError) as exc:
+            self._on_login_failure(exc)
+            raise
+        else:
+            self._on_login_success()
+            return result
+
+    def _on_login_failure(self, exc: Exception) -> None:
+        """Update backoff state after a failed login attempt (PATCH)."""
+        now = datetime.datetime.now(datetime.timezone.utc)
+        if self._is_rate_limit_error(exc):
+            new_backoff = min(
+                self._state.backoff * self._BACKOFF_GROW, self._BACKOFF_CAP
+            )
+            self._state.backoff = new_backoff
+            self._state.quiet_until = now + new_backoff
+            _LOGGER.warning(
+                "Smart API rate-limit detected (%s). Adaptive quiet window: "
+                "%s, until %s",
+                exc, new_backoff,
+                self._state.quiet_until.isoformat(timespec='seconds'),
+            )
+        else:
+            self._state.quiet_until = now + self._OTHER_FAILURE_BACKOFF
+            _LOGGER.info(
+                "Smart API login failed (%s). Short retry-suppress until %s",
+                exc, self._state.quiet_until.isoformat(timespec='seconds'),
+            )
+
+    def _on_login_success(self) -> None:
+        """Update backoff state after a successful login (PATCH)."""
+        prev = self._state.backoff
+        new_backoff = max(
+            self._state.backoff - self._BACKOFF_SHRINK, self._BACKOFF_FLOOR
+        )
+        self._state.backoff = new_backoff
+        self._state.quiet_until = None
+        if prev > self._BACKOFF_FLOOR:
+            _LOGGER.info(
+                "Smart API login succeeded; backoff %s -> %s", prev, new_backoff
+            )
+
+    @staticmethod
+    def _is_rate_limit_error(exc: Exception) -> bool:
+        """Heuristic: was *exc* caused by Smart's WAF / rate-limiter."""
+        if isinstance(exc, httpx.HTTPStatusError):
+            return exc.response.status_code in (403, 429)
+        text = str(exc).lower()
+        # Match the embellished error messages from _do_login below, plus
+        # explicit Smart strings ("Api Rate limit exceeded").
+        return (
+            "rate limit" in text
+            or "rate-limit" in text
+            or "quota" in text
+            or "http 403" in text
+            or "http 429" in text
+            or "forbidden" in text
+        )
+
+    async def _do_login(self):
+        """Original login flow (extracted by PATCH)."""
         ssl_ctx = await self.get_ssl_context()
         async with SmartLoginClient(ssl_context=ssl_ctx) as client:
             _LOGGER.info("Acquiring access token.")
@@ -189,8 +300,14 @@ class SmartAuthentication(httpx.Auth):
             try:
                 context = r_context.url.params["context"]
                 _LOGGER.debug("Context: %s", context)
-            except KeyError:
-                raise SmartAPIError("Could not get context from login page")
+            except KeyError as err:
+                # PATCH: include status + body so the breaker can classify (rate-limit vs other).
+                # Body is run through sanitize_log_data() so any tokens/PII are masked.
+                raise SmartAPIError(
+                    "Could not get context from login page "
+                    f"(HTTP {r_context.status_code}, "
+                    f"body={sanitize_log_data(r_context.text[:200])!r})"
+                ) from err
 
             # Get login token from Smart API
             r_login = await client.post(
@@ -228,8 +345,14 @@ class SmartAuthentication(httpx.Auth):
                 expires_at = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(
                     seconds=int(login_result["sessionInfo"]["expires_in"])
                 )
-            except (KeyError, ValueError):
-                raise SmartAPIError("Could not get login token from login page")
+            except (KeyError, ValueError) as err:
+                # PATCH: include status + body so the breaker can classify.
+                # Body is run through sanitize_log_data() so any tokens/PII are masked.
+                raise SmartAPIError(
+                    "Could not get login token from login page "
+                    f"(HTTP {r_login.status_code}, "
+                    f"body={sanitize_log_data(r_login.text[:200])!r})"
+                ) from err
 
             auth_url = self.endpoint_urls.get_auth_url() + "?context=" + context + "&login_token=" + login_token
             cookie = f"gmid=gmid.ver4.AcbHPqUK5Q.xOaWPhRTb7gy-6-GUW6cxQVf_t7LhbmeabBNXqqqsT6dpLJLOWCGWZM07EkmfM4j.u2AMsCQ9ZsKc6ugOIoVwCgryB2KJNCnbBrlY6pq0W2Ww7sxSkUa9_WTPBIwAufhCQYkb7gA2eUbb6EIZjrl5mQ.sc3; ucid=hPzasmkDyTeHN0DinLRGvw; hasGmid=ver4; gig_bootstrap_3_L94eyQ-wvJhWm7Afp1oBhfTGXZArUfSHHW9p9Pncg513hZELXsxCfMWHrF8f5P5a=auth_ver4; glt_3_L94eyQ-wvJhWm7Afp1oBhfTGXZArUfSHHW9p9Pncg513hZELXsxCfMWHrF8f5P5a={login_token}"  # noqa: E501

pysmarthashtag-0.9.0/pysmarthashtag/tests/test_authentication_backoff.py

@@ -0,0 +1,193 @@
+"""Tests for the adaptive rate-limit backoff in ``SmartAuthentication``.
+
+These tests stub ``_do_login`` so no network calls happen and exercise:
+
+* AIMD growth on rate-limit failures (HTTP 403/429)
+* Circuit-breaker suppression while the quiet window is active
+* Multiplicative shrink on successful login
+* Fixed short suppress (no growth) on non-rate-limit failures
+* Floor invariant after many successes
+* Module-level state shared across ``SmartAuthentication`` instances
+  for the same username
+"""
+
+from __future__ import annotations
+
+import datetime
+from unittest.mock import patch
+
+import httpx
+import pytest
+
+from pysmarthashtag.api.authentication import (
+    _BACKOFF_REGISTRY,
+    SmartAPIError,
+    SmartAuthentication,
+)
+
+
+def _make_auth(username: str = "user@example.com") -> SmartAuthentication:
+    """Reset shared backoff state for ``username`` and return a fresh auth."""
+    _BACKOFF_REGISTRY.pop(username, None)
+    return SmartAuthentication(username=username, password="p")
+
+
+def _http_403() -> httpx.HTTPStatusError:
+    req = httpx.Request("GET", "https://example/")
+    resp = httpx.Response(403, request=req, content=b'{"message":"Forbidden"}')
+    return httpx.HTTPStatusError("forbidden", request=req, response=resp)
+
+
+def _login_ok() -> dict:
+    return {
+        "access_token": "a",
+        "refresh_token": "r",
+        "api_access_token": "x",
+        "api_refresh_token": "y",
+        "api_user_id": "z",
+        "expires_at": datetime.datetime.now(datetime.timezone.utc)
+        + datetime.timedelta(hours=1),
+    }
+
+
+class TestAdaptiveBackoff:
+    """Adaptive AIMD rate-limit backoff."""
+
+    @pytest.mark.asyncio
+    async def test_grow_on_rate_limit(self):
+        """Each rate-limit hit grows the backoff up to ``_BACKOFF_CAP``."""
+        auth = _make_auth()
+        floor_min = auth._BACKOFF_FLOOR.total_seconds() / 60
+        cap_min = auth._BACKOFF_CAP.total_seconds() / 60
+        grow = auth._BACKOFF_GROW
+
+        expected: list[float] = []
+        v = floor_min
+        for _ in range(11):
+            v = min(v * grow, cap_min)
+            expected.append(round(v, 6))
+
+        async def boom():
+            raise _http_403()
+
+        seen: list[float] = []
+        with patch.object(auth, "_do_login", boom):
+            for _ in expected:
+                # Pretend the previous quiet window has just elapsed so
+                # this probe is allowed through to ``_do_login``.
+                auth._state.quiet_until = None
+                with pytest.raises((SmartAPIError, httpx.HTTPStatusError)):
+                    await auth._login()
+                seen.append(round(auth._state.backoff.total_seconds() / 60, 6))
+
+        assert seen == expected
+        assert auth._state.backoff <= auth._BACKOFF_CAP
+
+    @pytest.mark.asyncio
+    async def test_breaker_blocks_during_quiet_window(self):
+        """During the quiet window the breaker must skip ``_do_login``."""
+        auth = _make_auth()
+
+        async def boom():
+            raise _http_403()
+
+        with patch.object(auth, "_do_login", boom):
+            with pytest.raises((SmartAPIError, httpx.HTTPStatusError)):
+                await auth._login()
+
+            calls = {"n": 0}
+
+            async def count_calls():
+                calls["n"] += 1
+                raise _http_403()
+
+            with patch.object(auth, "_do_login", count_calls):
+                with pytest.raises(SmartAPIError) as excinfo:
+                    await auth._login()
+
+        assert calls["n"] == 0, "breaker did not suppress the second probe"
+        assert "quiet window" in str(excinfo.value)
+
+    @pytest.mark.asyncio
+    async def test_shrink_on_success(self):
+        """Success shrinks the backoff and clears the quiet window."""
+        auth = _make_auth()
+        auth._state.backoff = datetime.timedelta(minutes=30)
+        auth._state.quiet_until = None
+
+        async def ok():
+            return _login_ok()
+
+        with patch.object(auth, "_do_login", ok):
+            await auth._login()
+
+        assert auth._state.backoff == datetime.timedelta(minutes=29)
+        assert auth._state.quiet_until is None
+
+    @pytest.mark.asyncio
+    async def test_other_failure_uses_fixed_suppress_no_grow(self):
+        """Non-rate-limit failures only set a short suppress, no grow."""
+        auth = _make_auth()
+        before = auth._state.backoff
+
+        async def boom():
+            raise SmartAPIError("Could not get access token from auth page")
+
+        with patch.object(auth, "_do_login", boom):
+            with pytest.raises(SmartAPIError):
+                await auth._login()
+
+        assert auth._state.backoff == before, "backoff grew on non-rate-limit failure"
+        assert auth._state.quiet_until is not None
+
+        delta = auth._state.quiet_until - datetime.datetime.now(datetime.timezone.utc)
+        # Allow a small clock-skew tolerance below the configured suppress window.
+        lower_bound = auth._OTHER_FAILURE_BACKOFF - datetime.timedelta(seconds=5)
+        assert lower_bound < delta <= auth._OTHER_FAILURE_BACKOFF
+
+    @pytest.mark.asyncio
+    async def test_floor_invariant(self):
+        """Repeated successes never push the backoff below the floor."""
+        auth = _make_auth()
+
+        async def ok():
+            return _login_ok()
+
+        with patch.object(auth, "_do_login", ok):
+            for _ in range(20):
+                await auth._login()
+
+        assert auth._state.backoff == auth._BACKOFF_FLOOR
+
+    @pytest.mark.asyncio
+    async def test_state_shared_across_instances_same_user(self):
+        """Two ``SmartAuthentication`` objects for the same user share state."""
+        a1 = _make_auth("shared_user")
+
+        async def boom():
+            raise _http_403()
+
+        with patch.object(a1, "_do_login", boom):
+            a1._state.quiet_until = None
+            with pytest.raises((SmartAPIError, httpx.HTTPStatusError)):
+                await a1._login()
+
+        grew_to = a1._state.backoff
+        assert grew_to > a1._BACKOFF_FLOOR
+
+        # New instance for the same username — must reuse the same state.
+        a2 = SmartAuthentication(username="shared_user", password="p")
+        assert a2._state is a1._state
+        assert a2._state.backoff == grew_to
+
+        calls = {"n": 0}
+
+        async def count_calls():
+            calls["n"] += 1
+            raise _http_403()
+
+        with patch.object(a2, "_do_login", count_calls):
+            with pytest.raises(SmartAPIError):
+                await a2._login()
+
+        assert calls["n"] == 0, "shared quiet window did not suppress second instance"

{pysmarthashtag-0.8.2 → pysmarthashtag-0.9.0}/requirements-test.txt

@@ -10,4 +10,4 @@ pbr
 time_machine<2.20.0
 pre-commit
 backports.zoneinfo;python_version<"3.9"
-ruff==0.14.14
+ruff==0.15.12

pysmarthashtag-0.8.2/pysmarthashtag/__init__.py

@@ -1,5 +0,0 @@
-"""Library to read data from the Smart API."""
-
-from importlib.metadata import version
-
-__version__ = version("pySmartHashtag")