lange-python 0.3.8__tar.gz → 0.3.9__tar.gz

{lange_python-0.3.8 → lange_python-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lange-python
-Version: 0.3.8
+Version: 0.3.9
 Summary: A bundeld set of tools, clients for the lange-suite of tools and more.
 Author: contact@robertlange.me
 Requires-Python: >=3.10
@@ -51,6 +51,18 @@ print(update_metadata["version"])
 # The caller should now shut down so the detached helper can replace the app bundle.
 ```
 
+The distribution client also exposes `status` and `reload()` for refresh-aware integrations:
+
+```python
+client = DistributionClient(distribution_name="desktop-app", api_key="your-api-key")
+
+latest_version = client.search_for_update("1.2.3")
+print(client.status)  # connected
+
+client.reload()  # repeats the last update check
+client.reload(api_key=None)  # clears authentication and marks the client unauthenticated
+```
+
 ## Tunnel worker
 
 ```python
@@ -64,6 +76,11 @@ tunnel = Tunnel(
 
 tunnel.start()
 # ...
+tunnel.reload()  # restarts the connection flow with the current API key
+tunnel.reload(api_key=None)  # clears authentication and leaves the client unauthenticated
 tunnel.stop()
 ```
 
+Tunnel clients also expose a `status` property with one of:
+`"unauthenticated"`, `"off"`, `"pending"`, `"connected"`, or `"failed"`.
+

{lange_python-0.3.8 → lange_python-0.3.9}/README.md

@@ -33,6 +33,18 @@ print(update_metadata["version"])
 # The caller should now shut down so the detached helper can replace the app bundle.
 ```
 
+The distribution client also exposes `status` and `reload()` for refresh-aware integrations:
+
+```python
+client = DistributionClient(distribution_name="desktop-app", api_key="your-api-key")
+
+latest_version = client.search_for_update("1.2.3")
+print(client.status)  # connected
+
+client.reload()  # repeats the last update check
+client.reload(api_key=None)  # clears authentication and marks the client unauthenticated
+```
+
 ## Tunnel worker
 
 ```python
@@ -46,5 +58,10 @@ tunnel = Tunnel(
 
 tunnel.start()
 # ...
+tunnel.reload()  # restarts the connection flow with the current API key
+tunnel.reload(api_key=None)  # clears authentication and leaves the client unauthenticated
 tunnel.stop()
 ```
+
+Tunnel clients also expose a `status` property with one of:
+`"unauthenticated"`, `"off"`, `"pending"`, `"connected"`, or `"failed"`.

lange_python-0.3.9/lange/_util/_base_client.py

@@ -0,0 +1,78 @@
+from threading import Thread
+from typing import Literal
+
+from ._key_handling import _resolve_api_key
+
+ClientStatus = Literal["unauthenticated", "off", "pending", "connected", "failed"]
+_UNSET_API_KEY = object()
+
+
+class BaseLangeLabsClient(Thread):
+    """Shared thread-based Lange Labs client base class."""
+
+    def __init__(self,
+                 api_key: str | None = None,
+                 daemon: bool = True,
+                 host: str | None = None,
+                 ) -> None:
+        """
+        Initialize a thread-based Lange Labs client with shared connection settings.
+
+        :param api_key: Optional API key supplied directly or resolved from the environment.
+        :param daemon: Whether the client thread should run as a daemon thread.
+        :param host: Base service URL used for outbound requests.
+        :raises ValueError: If ``api_key`` is provided but empty.
+        """
+        super().__init__(daemon=daemon)
+        self.api_key = _resolve_api_key(api_key)
+        self.host = host.rstrip("/") if host is not None else ""
+        self._status: ClientStatus = self._status_for_auth()
+
+    def reload(self, api_key: str | None | object = _UNSET_API_KEY) -> None:
+        """
+        Reload shared client configuration.
+
+        :param api_key: Optional replacement API key. Pass ``None`` explicitly to clear authentication.
+        :returns: ``None``.
+        :raises ValueError: If ``api_key`` is provided but empty.
+        """
+        if api_key is _UNSET_API_KEY:
+            pass
+        elif api_key is None:
+            self.api_key = None
+        else:
+            self.api_key = _resolve_api_key(api_key)
+
+        self._status = self._status_for_auth()
+
+    def _build_connection_headers(self) -> dict[str, str]:
+        """
+        Build outbound handshake headers.
+
+        :returns: Header dictionary with bearer authorization.
+        :raises ValueError: If the client is unauthenticated.
+        """
+        if self.api_key is None:
+            raise ValueError("API key is required for this operation.")
+
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    def _set_status(self, status: ClientStatus) -> None:
+        """
+        Store the current client status.
+
+        :param status: New shared client status value.
+        :returns: ``None``.
+        """
+        self._status = status
+
+    def _status_for_auth(self) -> ClientStatus:
+        """
+        Resolve the default status from the configured authentication state.
+
+        :returns: ``\"unauthenticated\"`` when no key is set, otherwise ``\"off\"``.
+        """
+        if self.api_key is None:
+            return "unauthenticated"
+
+        return "off"

lange_python-0.3.9/lange/_util/_key_handling.py

@@ -0,0 +1,22 @@
+import os
+
+
+def _resolve_api_key(api_key: str | None) -> str | None:
+    """
+    Resolve API key from argument or environment.
+
+    :param api_key: Optional direct API key value.
+    :returns: Sanitized API key or ``None`` when no key is configured.
+    :raises ValueError: If the provided API key is empty or whitespace-only.
+    """
+    if api_key is not None:
+        normalized_api_key = api_key.strip()
+        if not normalized_api_key:
+            raise ValueError("api_key cannot be empty.")
+        return normalized_api_key
+
+    env_api_key = os.getenv("LANGE_LABS_API_KEY", "")
+    if env_api_key.strip():
+        return env_api_key.strip()
+
+    return None

{lange_python-0.3.8 → lange_python-0.3.9}/lange/distribution/_client.py

@@ -15,6 +15,7 @@ from ._util import (
     validate_installed_macos_app_path,
 )
 from .._util import BaseLangeLabsClient
+from .._util._base_client import _UNSET_API_KEY
 
 
 class DistributionClient(BaseLangeLabsClient):
@@ -24,7 +25,7 @@ class DistributionClient(BaseLangeLabsClient):
     :param host: Base app-service URL, e.g. ``https://lange-labs.com``.
     :param api_key: Optional API key supplied directly or resolved from the environment.
     :param timeout: HTTP timeout in seconds for metadata requests.
-    :raises ValueError: If ``api_key`` is unavailable or empty.
+    :raises ValueError: If ``api_key`` is provided but empty.
     """
 
     def __init__(self,
@@ -39,10 +40,12 @@ class DistributionClient(BaseLangeLabsClient):
         :param api_key: Optional API key supplied directly or resolved from the environment.
         :param timeout: HTTP timeout in seconds for metadata requests.
         :param distribution_name: Distribution name as stored by the app service.
-        :raises ValueError: If ``api_key`` is unavailable or empty.
+        :raises ValueError: If ``api_key`` is provided but empty.
         """
         super().__init__(api_key, host=host)
         self.timeout = timeout
+        self._last_checked_version: str | None = None
+        self._last_update_result: str | None = None
         normalized_distribution_name = distribution_name.strip()
 
         if not normalized_distribution_name:
@@ -53,6 +56,43 @@ class DistributionClient(BaseLangeLabsClient):
 
         self.distribution_name = normalized_distribution_name
 
+    @property
+    def status(self) -> str:
+        """
+        Get the current distribution client status.
+
+        :returns: Shared client status string.
+        """
+        return self._status
+
+    @property
+    def last_checked_version(self) -> str | None:
+        """
+        Get the version used for the most recent update check.
+
+        :returns: Last checked version string or ``None``.
+        """
+        return self._last_checked_version
+
+    def reload(self, api_key: str | None | object = _UNSET_API_KEY) -> None:
+        """
+        Reload authentication and repeat the last update check when available.
+
+        :param api_key: Optional replacement API key. Pass ``None`` explicitly to clear authentication.
+        :returns: ``None``.
+        """
+        super().reload(api_key=api_key)
+
+        if self.api_key is None:
+            self._last_update_result = None
+            return
+
+        if self._last_checked_version is None:
+            self._set_status("off")
+            return
+
+        self.search_for_update(self._last_checked_version)
+
     def search_for_update(self, current_version: str) -> str | None:
         """
         Resolve the newest available version for the current OS when it is newer.
@@ -68,30 +108,47 @@ class DistributionClient(BaseLangeLabsClient):
         if not normalized_current_version:
             raise ValueError("current_version is required.")
 
-        current_os = detect_distribution_os()
-        payload = self._get_distribution_payload()
-        versions = payload.get("distribution", {}).get("versions", [])
+        self._last_checked_version = normalized_current_version
 
-        newest_version: str | None = None
+        if self.api_key is None:
+            self._set_status("unauthenticated")
+            raise ValueError("API key is required for this operation.")
 
-        for version_entry in versions:
-            if not isinstance(version_entry, dict):
-                continue
+        self._set_status("pending")
 
-            version = str(version_entry.get("version", "")).strip()
-            artifacts = version_entry.get("artifacts", {})
-            artifact = artifacts.get(current_os) if isinstance(artifacts, dict) else None
-
-            if not version or artifact is None:
-                continue
-
-            if _compare_versions(version, normalized_current_version) <= 0:
-                continue
-
-            if newest_version is None or _compare_versions(version, newest_version) > 0:
-                newest_version = version
-
-        return newest_version
+        try:
+            current_os = detect_distribution_os()
+            payload = self._get_distribution_payload()
+            versions = payload.get("distribution", {}).get("versions", [])
+
+            newest_version: str | None = None
+
+            for version_entry in versions:
+                if not isinstance(version_entry, dict):
+                    continue
+
+                version = str(version_entry.get("version", "")).strip()
+                artifacts = version_entry.get("artifacts", {})
+                artifact = artifacts.get(current_os) if isinstance(artifacts, dict) else None
+
+                if not version or artifact is None:
+                    continue
+
+                if _compare_versions(version, normalized_current_version) <= 0:
+                    continue
+
+                if newest_version is None or _compare_versions(version, newest_version) > 0:
+                    newest_version = version
+
+            self._last_update_result = newest_version
+            self._set_status("connected")
+            return newest_version
+        except Exception:
+            if self.api_key is None:
+                self._set_status("unauthenticated")
+            else:
+                self._set_status("failed")
+            raise
 
     def _build_distribution_url(self) -> str:
         """

{lange_python-0.3.8 → lange_python-0.3.9}/lange/tunnel/_client.py

@@ -13,6 +13,7 @@ import httpx
 import websockets
 from httpx import Timeout
 from .._util import BaseLangeLabsClient
+from .._util._base_client import _UNSET_API_KEY
 from ._util import _filter_hop_by_hop_headers
 
 logger = logging.getLogger("lange.tunnel")
@@ -33,7 +34,7 @@ class Tunnel(BaseLangeLabsClient):
     :param retry_delay: Initial reconnect delay in seconds.
     :param open_timeout: Timeout in seconds for the WebSocket opening handshake.
     :param daemon: Whether the worker thread is daemonized.
-    :raises ValueError: If API key is unavailable or empty.
+    :raises ValueError: If API key is provided but empty.
     """
 
     def __init__(
@@ -77,6 +78,16 @@ class Tunnel(BaseLangeLabsClient):
         with self._lock:
             return self._connected
 
+    @property
+    def status(self) -> str:
+        """
+        Get the current tunnel lifecycle status.
+
+        :returns: Shared client status string.
+        """
+        with self._lock:
+            return self._status
+
     @property
     def remote_address(self) -> Optional[str]:
         """
@@ -149,22 +160,23 @@ class Tunnel(BaseLangeLabsClient):
 
         :returns: ``None``.
         """
+        self._request_reconnect()
+
+    def reload(self, api_key: str | None | object = _UNSET_API_KEY) -> None:
+        """
+        Reload tunnel authentication and restart the connection flow when running.
+
+        :param api_key: Optional replacement API key. Pass ``None`` explicitly to clear authentication.
+        :returns: ``None``.
+        """
+        super().reload(api_key=api_key)
         self._set_connected(False)
-        with self._lock:
-            self._reconnect_count = 0
-            ws = self._active_ws
-            loop = self._loop
-        self._reconnect_event.set()
 
-        if ws is not None and loop is not None and loop.is_running():
-            try:
-                future = asyncio.run_coroutine_threadsafe(
-                    ws.close(code=1012, reason="Client reconnect"),
-                    loop,
-                )
-                future.result(timeout=2)
-            except Exception as exc:  # pragma: no cover - best-effort close path
-                logger.debug("Failed to close websocket during reconnect: %s", exc)
+        if self.is_alive() or self._loop is not None:
+            self._request_reconnect()
+            return
+
+        self._set_status(self._status_for_auth())
 
     async def _run_async(self) -> None:
         """
@@ -181,6 +193,13 @@ class Tunnel(BaseLangeLabsClient):
         current_delay = self.retry_delay
 
         while not self._stop_event.is_set():
+            if self.api_key is None:
+                self._set_connected(False)
+                self._set_status("unauthenticated")
+                await self._wait_for_reconnect_signal()
+                continue
+
+            self._set_status("pending")
             headers = self._build_connection_headers()
 
             try:
@@ -209,9 +228,11 @@ class Tunnel(BaseLangeLabsClient):
                         self._set_connected(False)
             except websockets.exceptions.ConnectionClosed as exc:
                 self._set_connected(False)
+                self._set_status("failed")
                 logger.warning("Connection closed: %s", exc)
             except Exception as exc:  # pragma: no cover - network error path
                 self._set_connected(False)
+                self._set_status("failed")
                 logger.error("Connection error: %s", exc)
             finally:
                 with self._lock:
@@ -226,6 +247,7 @@ class Tunnel(BaseLangeLabsClient):
                     self._reconnect_count = 0
                 self._reconnect_event.clear()
                 current_delay = self.retry_delay
+                self._set_status(self._status_for_auth())
                 logger.info("Manual reconnect requested. Reconnecting now.")
                 continue
 
@@ -234,6 +256,7 @@ class Tunnel(BaseLangeLabsClient):
                 attempt = self._reconnect_count
 
             if self.max_retries > 0 and attempt > self.max_retries:
+                self._set_status("failed")
                 logger.error("Max reconnection attempts (%s) reached. Giving up.", self.max_retries)
                 break
 
@@ -256,6 +279,8 @@ class Tunnel(BaseLangeLabsClient):
         with self._lock:
             self._active_ws = None
             self._loop = None
+            if self._status in {"connected", "pending"}:
+                self._status = self._status_for_auth()
 
         logger.info("Disconnected from server.")
 
@@ -381,6 +406,56 @@ class Tunnel(BaseLangeLabsClient):
             self._remote_address_roundrobin = remote_address_roundrobin if value else None
             self._worker_index = worker_index if value else -1
             self._pool_size = pool_size if value else 0
+            if value:
+                self._status = "connected"
+            elif self.api_key is None:
+                self._status = "unauthenticated"
+
+    def _set_status(self, status: str) -> None:
+        """
+        Store the current tunnel lifecycle status.
+
+        :param status: New lifecycle status.
+        :returns: ``None``.
+        """
+        with self._lock:
+            self._status = status
+
+    def _request_reconnect(self) -> None:
+        """
+        Trigger a reconnect cycle and close the active websocket when needed.
+
+        :returns: ``None``.
+        """
+        self._set_connected(False)
+        with self._lock:
+            self._reconnect_count = 0
+            ws = self._active_ws
+            loop = self._loop
+            self._status = self._status_for_auth()
+        self._reconnect_event.set()
+
+        if ws is not None and loop is not None and loop.is_running():
+            try:
+                future = asyncio.run_coroutine_threadsafe(
+                    ws.close(code=1012, reason="Client reconnect"),
+                    loop,
+                )
+                future.result(timeout=2)
+            except Exception as exc:  # pragma: no cover - best-effort close path
+                logger.debug("Failed to close websocket during reconnect: %s", exc)
+
+    async def _wait_for_reconnect_signal(self) -> None:
+        """
+        Wait until the client is reloaded, stopped, or resumed from an unauthenticated state.
+
+        :returns: ``None``.
+        """
+        while not self._stop_event.is_set() and not self._reconnect_event.is_set():
+            await asyncio.sleep(0.5)
+
+        if self._reconnect_event.is_set():
+            self._reconnect_event.clear()
 
     def _build_ssl_context(self, tunnel_url: str) -> Optional[ssl.SSLContext]:
         """

{lange_python-0.3.8 → lange_python-0.3.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lange-python"
-version = "0.3.8"
+version = "0.3.9"
 description = "A bundeld set of tools, clients for the lange-suite of tools and more."
 authors = [
     {name = "contact@robertlange.me"}

lange_python-0.3.8/lange/_util/_base_client.py

@@ -1,30 +0,0 @@
-from threading import Thread
-from ._key_handling import _resolve_api_key
-
-
-class BaseLangeLabsClient(Thread):
-
-    def __init__(self,
-                 api_key: str | None = None,
-                 daemon: bool = True,
-                 host: str | None = None,
-                 ) -> None:
-        """
-        Initialize a thread-based Lange Labs client with shared connection settings.
-
-        :param api_key: Optional API key supplied directly or resolved from the environment.
-        :param daemon: Whether the client thread should run as a daemon thread.
-        :param host: Base service URL used for outbound requests.
-        :raises ValueError: If ``api_key`` is unavailable or empty.
-        """
-        super().__init__(daemon=daemon)
-        self.api_key = _resolve_api_key(api_key)
-        self.host = host.rstrip("/")
-
-    def _build_connection_headers(self) -> dict[str, str]:
-        """
-        Build outbound handshake headers.
-
-        :returns: Header dictionary with bearer authorization.
-        """
-        return {"Authorization": f"Bearer {self.api_key}"}

lange_python-0.3.8/lange/_util/_key_handling.py

@@ -1,21 +0,0 @@
-import os
-
-def _resolve_api_key(api_key: str | None) -> str:
-    """
-    Resolve API key from argument or environment.
-
-    :param api_key: Optional direct API key value.
-    :returns: Sanitized non-empty API key.
-    :raises ValueError: If no non-empty API key is available.
-    """
-    if api_key is not None and api_key.strip():
-        return api_key.strip()
-
-    env_api_key = os.getenv("LANGE_LABS_API_KEY", "")
-    if env_api_key.strip():
-        return env_api_key.strip()
-
-    raise ValueError(
-        "A non-empty api_key is required. "
-        "Pass api_key directly or set LANGE_LABS_API_KEY."
-    )