python-siseli 0.1.0__tar.gz → 0.1.2__tar.gz

{python_siseli-0.1.0 → python_siseli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-siseli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python SDK for Siseli Cloud
 License: MIT
 Requires-Python: >=3.11

{python_siseli-0.1.0 → python_siseli-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-siseli"
-version = "0.1.0"
+version = "0.1.2"
 description = "Python SDK for Siseli Cloud"
 readme = "README.md"
 requires-python = ">=3.11"

{python_siseli-0.1.0 → python_siseli-0.1.2}/python_siseli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-siseli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python SDK for Siseli Cloud
 License: MIT
 Requires-Python: >=3.11

{python_siseli-0.1.0 → python_siseli-0.1.2}/python_siseli.egg-info/SOURCES.txt

@@ -30,4 +30,5 @@ siseli/models/dictionary.py
 siseli/models/history.py
 siseli/models/state.py
 siseli/models/station.py
+tests/test_auth.py
 tests/test_phase3.py

python_siseli-0.1.2/siseli/auth.py

@@ -0,0 +1,169 @@
+"""Authentication: login and token lifecycle management."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from datetime import UTC, datetime
+
+import httpx
+
+from .exceptions import AuthenticationError, NetworkError
+from .models.auth import TokenInfo
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _md5(text: str) -> str:
+    # The Siseli Cloud API requires the MD5 hash of the plaintext password.
+    # This is a protocol constraint imposed by the server, not a local
+    # password-storage decision.  The hash is sent over HTTPS and is never
+    # stored on disk.
+    return hashlib.md5(text.encode()).hexdigest()  # noqa: S324
+
+
+def _parse_dt(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _extract_api_message(response: httpx.Response) -> str | None:
+    """Extract a safe, short error message from an HTTP error response.
+
+    Tries to parse the body as JSON and returns the value of the first
+    recognised error field (``error``, ``message``, ``detail``).  Falls back
+    to the first 200 characters of the raw text body so there is always
+    *something* useful in logs.  Never returns passwords, tokens, or auth
+    headers — those are never present in response bodies.
+    """
+    try:
+        body = response.json()
+        if isinstance(body, dict):
+            for key in ("error", "message", "detail"):
+                value = body.get(key)
+                if value and isinstance(value, str):
+                    return value[:200]
+    except Exception:  # noqa: BLE001
+        pass
+    text = (response.text or "").strip()
+    return text[:200] if text else None
+
+
+class Auth:
+    """Manages credentials and the current access token.
+
+    The password is hashed with MD5 before being sent to the API, which
+    matches the behaviour observed in the browser client.
+    """
+
+    def __init__(self, account: str, password: str) -> None:
+        self._account = account
+        # The web client sends the MD5 hash of the plaintext password.
+        self._password_hash = _md5(password)
+        self._token_info: TokenInfo | None = None
+
+    async def login(self, http: httpx.AsyncClient) -> TokenInfo:
+        """Authenticate and store the returned tokens.
+
+        Raises :exc:`~siseli.exceptions.AuthenticationError` on HTTP-level
+        auth failures (4xx).  Raises :exc:`~siseli.exceptions.NetworkError`
+        on network / timeout errors so callers can distinguish the two cases.
+        """
+        endpoint = "/apis/login/account"
+        _LOGGER.debug("Siseli auth: POST %s (account=%r)", endpoint, self._account)
+
+        try:
+            response = await http.post(
+                endpoint,
+                json={"account": self._account, "password": self._password_hash},
+            )
+        except httpx.TimeoutException as exc:
+            _LOGGER.warning("Siseli auth: request timed out for account=%r", self._account)
+            raise NetworkError(f"Login request timed out: {exc}") from exc
+        except httpx.HTTPError as exc:
+            _LOGGER.warning(
+                "Siseli auth: network error for account=%r: %s", self._account, exc
+            )
+            raise NetworkError(f"Login request failed: {exc}") from exc
+
+        http_status = response.status_code
+        _LOGGER.debug(
+            "Siseli auth: response status=%d for account=%r", http_status, self._account
+        )
+
+        # For HTTP error responses, extract a safe diagnostic message and raise
+        # AuthenticationError (4xx) or NetworkError (5xx).
+        if not response.is_success:
+            api_message = _extract_api_message(response)
+            _LOGGER.warning(
+                "Siseli auth: failed for account=%r — HTTP %d%s",
+                self._account,
+                http_status,
+                f", api_message={api_message!r}" if api_message else "",
+            )
+            diag = f"HTTP {http_status}"
+            if api_message:
+                diag = f"{diag}: {api_message}"
+            if http_status >= 500:
+                raise NetworkError(f"Login request failed: {diag}")
+            raise AuthenticationError(
+                f"Login failed: {diag}",
+                http_status=http_status,
+                api_message=api_message,
+            )
+
+        body = response.json()
+        if body.get("code") != 0:
+            api_message = body.get("message") or body.get("error") or body.get("detail")
+            if api_message:
+                api_message = str(api_message)
+            _LOGGER.warning(
+                "Siseli auth: API returned non-zero code=%r for account=%r, message=%r",
+                body.get("code"),
+                self._account,
+                api_message,
+            )
+            raise AuthenticationError(
+                f"Login failed (code {body.get('code')}): {api_message}",
+                http_status=http_status,
+                api_message=api_message,
+            )
+
+        data = body["data"]
+        self._token_info = TokenInfo(
+            access_token=data["accessToken"],
+            refresh_token=data["refreshToken"],
+            access_token_expires_at=_parse_dt(data.get("accessTokenWillExpiredAt")),
+            refresh_token_expires_at=_parse_dt(data.get("refreshTokenWillExpiredAt")),
+            auth_id=data.get("authId", ""),
+            account=data.get("account", self._account),
+            user_id=data.get("userId", ""),
+        )
+        _LOGGER.debug("Siseli auth: login successful for account=%r", self._account)
+        return self._token_info
+
+    @property
+    def access_token(self) -> str:
+        """Return the current access token.
+
+        Raises :exc:`~siseli.exceptions.AuthenticationError` if not yet
+        authenticated.
+        """
+        if self._token_info is None:
+            raise AuthenticationError("Not authenticated — call authenticate() first")
+        return self._token_info.access_token
+
+    @property
+    def token_info(self) -> TokenInfo | None:
+        """Return token metadata, or *None* if not authenticated."""
+        return self._token_info
+
+    def is_authenticated(self) -> bool:
+        """Return *True* when there is a valid, non-expired access token."""
+        if self._token_info is None:
+            return False
+        expires_at = self._token_info.access_token_expires_at
+        if expires_at is None:
+            return True
+        return datetime.now(UTC) < expires_at

{python_siseli-0.1.0 → python_siseli-0.1.2}/siseli/exceptions.py

@@ -8,7 +8,26 @@ class SiseliError(Exception):
 
 
 class AuthenticationError(SiseliError):
-    """Raised when authentication fails."""
+    """Raised when authentication fails.
+
+    Attributes:
+        http_status: HTTP status code returned by the server, or *None* when
+            the failure occurred before a response was received.
+        api_message: Short error message extracted from the API response body
+            (e.g. the ``message`` or ``error`` field), or *None* when
+            unavailable.  Never contains passwords, tokens, or other secrets.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        http_status: int | None = None,
+        api_message: str | None = None,
+    ) -> None:
+        self.http_status = http_status
+        self.api_message = api_message
+        super().__init__(message)
 
 
 class TokenExpiredError(AuthenticationError):

python_siseli-0.1.2/tests/test_auth.py

@@ -0,0 +1,297 @@
+"""Tests for diagnostic logging and error handling in Auth.login()."""
+
+from __future__ import annotations
+
+import pytest
+import httpx
+
+from siseli.auth import Auth, _extract_api_message
+from siseli.exceptions import AuthenticationError, NetworkError
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_GOOD_BODY = {
+    "code": 0,
+    "data": {
+        "accessToken": "tok-access",
+        "refreshToken": "tok-refresh",
+        "accessTokenWillExpiredAt": None,
+        "refreshTokenWillExpiredAt": None,
+        "authId": "auth-1",
+        "account": "user@example.com",
+        "userId": "uid-1",
+    },
+}
+
+
+def _make_response(status_code: int, json_body: object | None = None, text: str = "") -> httpx.Response:
+    """Build a minimal fake httpx.Response."""
+    import json as _json
+
+    if json_body is not None:
+        content = _json.dumps(json_body).encode()
+        headers = {"content-type": "application/json"}
+    else:
+        content = text.encode()
+        headers = {"content-type": "text/plain"}
+
+    return httpx.Response(
+        status_code=status_code,
+        content=content,
+        headers=headers,
+        request=httpx.Request("POST", "https://example.com/apis/login/account"),
+    )
+
+
+class _FakeAsyncClient:
+    """Minimal async HTTP client stub."""
+
+    def __init__(self, response: httpx.Response | Exception) -> None:
+        self._response = response
+        self.last_request_json: dict | None = None
+
+    async def post(self, url: str, *, json: dict | None = None, **_: object) -> httpx.Response:
+        self.last_request_json = json
+        if isinstance(self._response, Exception):
+            raise self._response
+        return self._response
+
+
+# ---------------------------------------------------------------------------
+# _extract_api_message
+# ---------------------------------------------------------------------------
+
+
+def test_extract_api_message_json_error_field() -> None:
+    resp = _make_response(401, json_body={"error": "invalid_credentials"})
+    assert _extract_api_message(resp) == "invalid_credentials"
+
+
+def test_extract_api_message_json_message_field() -> None:
+    resp = _make_response(401, json_body={"message": "Bad password"})
+    assert _extract_api_message(resp) == "Bad password"
+
+
+def test_extract_api_message_json_detail_field() -> None:
+    resp = _make_response(403, json_body={"detail": "Account locked"})
+    assert _extract_api_message(resp) == "Account locked"
+
+
+def test_extract_api_message_prefers_error_over_message() -> None:
+    resp = _make_response(401, json_body={"error": "first", "message": "second"})
+    assert _extract_api_message(resp) == "first"
+
+
+def test_extract_api_message_plain_text_fallback() -> None:
+    resp = _make_response(500, text="Internal Server Error")
+    assert _extract_api_message(resp) == "Internal Server Error"
+
+
+def test_extract_api_message_truncates_long_text() -> None:
+    long_text = "x" * 300
+    resp = _make_response(500, text=long_text)
+    result = _extract_api_message(resp)
+    assert result is not None
+    assert len(result) == 200
+
+
+def test_extract_api_message_empty_body() -> None:
+    resp = _make_response(401, text="")
+    assert _extract_api_message(resp) is None
+
+
+# ---------------------------------------------------------------------------
+# Auth.login — HTTP error status codes
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_login_401_raises_authentication_error_with_status() -> None:
+    response = _make_response(401, json_body={"error": "invalid_credentials"})
+    client = _FakeAsyncClient(response)
+
+    auth = Auth("user@example.com", "secret")
+    with pytest.raises(AuthenticationError) as exc_info:
+        await auth.login(client)
+
+    err = exc_info.value
+    assert err.http_status == 401
+    assert err.api_message == "invalid_credentials"
+    assert "401" in str(err)
+    assert "invalid_credentials" in str(err)
+
+
+@pytest.mark.asyncio
+async def test_login_403_raises_authentication_error() -> None:
+    response = _make_response(403, json_body={"message": "Account disabled"})
+    client = _FakeAsyncClient(response)
+
+    auth = Auth("user@example.com", "secret")
+    with pytest.raises(AuthenticationError) as exc_info:
+        await auth.login(client)
+
+    err = exc_info.value
+    assert err.http_status == 403
+    assert err.api_message == "Account disabled"
+    assert "403" in str(err)
+
+
+@pytest.mark.asyncio
+async def test_login_429_raises_authentication_error() -> None:
+    response = _make_response(429, json_body={"message": "Too Many Requests"})
+    client = _FakeAsyncClient(response)
+
+    auth = Auth("user@example.com", "secret")
+    with pytest.raises(AuthenticationError) as exc_info:
+        await auth.login(client)
+
+    err = exc_info.value
+    assert err.http_status == 429
+    assert err.api_message == "Too Many Requests"
+
+
+@pytest.mark.asyncio
+async def test_login_5xx_raises_network_error() -> None:
+    response = _make_response(503, json_body={"error": "Service unavailable"})
+    client = _FakeAsyncClient(response)
+
+    auth = Auth("user@example.com", "secret")
+    with pytest.raises(NetworkError) as exc_info:
+        await auth.login(client)
+
+    assert "503" in str(exc_info.value)
+
+
+@pytest.mark.asyncio
+async def test_login_500_raises_network_error_not_auth_error() -> None:
+    response = _make_response(500, text="Internal Server Error")
+    client = _FakeAsyncClient(response)
+
+    auth = Auth("user@example.com", "secret")
+    with pytest.raises(NetworkError):
+        await auth.login(client)
+
+
+# ---------------------------------------------------------------------------
+# Auth.login — network / timeout errors
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_login_timeout_raises_network_error() -> None:
+    client = _FakeAsyncClient(httpx.TimeoutException("timed out"))
+
+    auth = Auth("user@example.com", "secret")
+    with pytest.raises(NetworkError) as exc_info:
+        await auth.login(client)
+
+    assert "timed out" in str(exc_info.value).lower() or "timeout" in str(exc_info.value).lower()
+
+
+@pytest.mark.asyncio
+async def test_login_connection_error_raises_network_error() -> None:
+    client = _FakeAsyncClient(httpx.ConnectError("connection refused"))
+
+    auth = Auth("user@example.com", "secret")
+    with pytest.raises(NetworkError):
+        await auth.login(client)
+
+
+# ---------------------------------------------------------------------------
+# Auth.login — non-zero API code (HTTP 200 but code != 0)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_login_api_nonzero_code_raises_auth_error() -> None:
+    response = _make_response(200, json_body={"code": 10001, "message": "Wrong credentials"})
+    client = _FakeAsyncClient(response)
+
+    auth = Auth("user@example.com", "secret")
+    with pytest.raises(AuthenticationError) as exc_info:
+        await auth.login(client)
+
+    err = exc_info.value
+    assert err.http_status == 200
+    assert err.api_message == "Wrong credentials"
+    assert "10001" in str(err)
+    assert "Wrong credentials" in str(err)
+
+
+# ---------------------------------------------------------------------------
+# Auth.login — no secrets in error messages
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_login_error_message_does_not_contain_password() -> None:
+    response = _make_response(401, json_body={"error": "invalid_credentials"})
+    client = _FakeAsyncClient(response)
+
+    password = "s3cr3tpassword"
+    auth = Auth("user@example.com", password)
+    with pytest.raises(AuthenticationError) as exc_info:
+        await auth.login(client)
+
+    assert password not in str(exc_info.value)
+    # MD5 hash should not appear either (it's the sent value, not in response)
+    import hashlib
+    md5_hash = hashlib.md5(password.encode()).hexdigest()  # noqa: S324
+    assert md5_hash not in str(exc_info.value)
+
+
+@pytest.mark.asyncio
+async def test_login_request_does_not_send_plaintext_password() -> None:
+    """Verify the login request sends MD5 hash, not the plaintext password."""
+    response = _make_response(200, json_body=_GOOD_BODY)
+    client = _FakeAsyncClient(response)
+
+    password = "plaintext_password"
+    auth = Auth("user@example.com", password)
+    await auth.login(client)
+
+    assert client.last_request_json is not None
+    assert client.last_request_json.get("password") != password
+
+
+# ---------------------------------------------------------------------------
+# Auth.login — successful login
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_login_success_returns_token_info() -> None:
+    response = _make_response(200, json_body=_GOOD_BODY)
+    client = _FakeAsyncClient(response)
+
+    auth = Auth("user@example.com", "secret")
+    token_info = await auth.login(client)
+
+    assert token_info.access_token == "tok-access"
+    assert token_info.refresh_token == "tok-refresh"
+    assert auth.is_authenticated()
+
+
+# ---------------------------------------------------------------------------
+# AuthenticationError attributes
+# ---------------------------------------------------------------------------
+
+
+def test_authentication_error_attributes() -> None:
+    err = AuthenticationError(
+        "Login failed: HTTP 401: invalid_credentials",
+        http_status=401,
+        api_message="invalid_credentials",
+    )
+    assert err.http_status == 401
+    assert err.api_message == "invalid_credentials"
+    assert "401" in str(err)
+
+
+def test_authentication_error_defaults() -> None:
+    err = AuthenticationError("Not authenticated")
+    assert err.http_status is None
+    assert err.api_message is None

python_siseli-0.1.0/siseli/auth.py

@@ -1,96 +0,0 @@
-"""Authentication: login and token lifecycle management."""
-
-from __future__ import annotations
-
-import hashlib
-from datetime import UTC, datetime
-
-import httpx
-
-from .exceptions import AuthenticationError
-from .models.auth import TokenInfo
-
-
-def _md5(text: str) -> str:
-    # The Siseli Cloud API requires the MD5 hash of the plaintext password.
-    # This is a protocol constraint imposed by the server, not a local
-    # password-storage decision.  The hash is sent over HTTPS and is never
-    # stored on disk.
-    return hashlib.md5(text.encode()).hexdigest()  # noqa: S324
-
-
-def _parse_dt(value: str | None) -> datetime | None:
-    if not value:
-        return None
-    return datetime.fromisoformat(value.replace("Z", "+00:00"))
-
-
-class Auth:
-    """Manages credentials and the current access token.
-
-    The password is hashed with MD5 before being sent to the API, which
-    matches the behaviour observed in the browser client.
-    """
-
-    def __init__(self, account: str, password: str) -> None:
-        self._account = account
-        # The web client sends the MD5 hash of the plaintext password.
-        self._password_hash = _md5(password)
-        self._token_info: TokenInfo | None = None
-
-    async def login(self, http: httpx.AsyncClient) -> TokenInfo:
-        """Authenticate and store the returned tokens.
-
-        Raises :exc:`~siseli.exceptions.AuthenticationError` on failure.
-        """
-        try:
-            response = await http.post(
-                "/apis/login/account",
-                json={"account": self._account, "password": self._password_hash},
-            )
-            response.raise_for_status()
-        except httpx.HTTPError as exc:
-            raise AuthenticationError(f"Login request failed: {exc}") from exc
-
-        body = response.json()
-        if body.get("code") != 0:
-            raise AuthenticationError(
-                f"Login failed (code {body.get('code')}): {body.get('message')}"
-            )
-
-        data = body["data"]
-        self._token_info = TokenInfo(
-            access_token=data["accessToken"],
-            refresh_token=data["refreshToken"],
-            access_token_expires_at=_parse_dt(data.get("accessTokenWillExpiredAt")),
-            refresh_token_expires_at=_parse_dt(data.get("refreshTokenWillExpiredAt")),
-            auth_id=data.get("authId", ""),
-            account=data.get("account", self._account),
-            user_id=data.get("userId", ""),
-        )
-        return self._token_info
-
-    @property
-    def access_token(self) -> str:
-        """Return the current access token.
-
-        Raises :exc:`~siseli.exceptions.AuthenticationError` if not yet
-        authenticated.
-        """
-        if self._token_info is None:
-            raise AuthenticationError("Not authenticated — call authenticate() first")
-        return self._token_info.access_token
-
-    @property
-    def token_info(self) -> TokenInfo | None:
-        """Return token metadata, or *None* if not authenticated."""
-        return self._token_info
-
-    def is_authenticated(self) -> bool:
-        """Return *True* when there is a valid, non-expired access token."""
-        if self._token_info is None:
-            return False
-        expires_at = self._token_info.access_token_expires_at
-        if expires_at is None:
-            return True
-        return datetime.now(UTC) < expires_at