lange-python 0.3.0__tar.gz → 0.3.1__tar.gz

{lange_python-0.3.0 → lange_python-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lange-python
-Version: 0.3.0
+Version: 0.3.1
 Summary: A bundeld set of tools, clients for the lange-suite of tools and more.
 Author: contact@robertlange.me
 Requires-Python: >=3.13

lange_python-0.3.1/lange/__init__.py

@@ -0,0 +1,6 @@
+"""Public package exports for lange-python."""
+
+from .distribution import DistributionClient
+from .tunnel import Tunnel
+
+__all__ = ["Tunnel", "DistributionClient"]

lange_python-0.3.1/lange/_util/__init__.py

@@ -0,0 +1,5 @@
+from ._base_client import BaseLangeLabsClient
+
+__all__ = [
+    "BaseLangeLabsClient",
+]

lange_python-0.3.1/lange/_util/_base_client.py

@@ -0,0 +1,30 @@
+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.1/lange/_util/_key_handling.py

@@ -0,0 +1,21 @@
+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."
+    )

{lange_python-0.3.0 → lange_python-0.3.1}/lange/cli/build/_command.py

@@ -20,12 +20,12 @@ from ._types import DOCKER_BUILD_SYSTEM, POETRY_BUILD_SYSTEM, BuildSystem
 
 @click.command("build")
 @click.argument("folder_name", required=False)
-@click.option("--publish", is_flag=True, help="Publish after a successful build.")
+@click.option("--push", is_flag=True, help="Publish after a successful build.")
 @click.option("--docker", "force_docker", is_flag=True, help="Force docker build.")
 @click.option("--poetry", "force_poetry", is_flag=True, help="Force poetry build.")
 def build_command(
     folder_name: str | None,
-    publish: bool,
+    push: bool,
     force_docker: bool,
     force_poetry: bool,
 ) -> None:
@@ -33,7 +33,7 @@ def build_command(
     Build a folder using docker or poetry with optional publishing.
 
     :param folder_name: Optional folder name to build.
-    :param publish: Whether publishing is enabled via flag.
+    :param push: Whether publishing is enabled via flag.
     :param force_docker: Force docker build system.
     :param force_poetry: Force poetry build system.
     :returns: ``None``.
@@ -44,7 +44,7 @@ def build_command(
         target_folder = resolve_build_folder(folder_name=folder_name, root=Path.cwd())
         _run_build_for_folder(
             folder=target_folder,
-            publish=publish,
+            publish=push,
             force_docker=force_docker,
             force_poetry=force_poetry,
             allow_prompt=True,
@@ -64,7 +64,7 @@ def build_command(
     for target_folder in target_folders:
         _run_build_for_folder(
             folder=target_folder,
-            publish=publish,
+            publish=push,
             force_docker=force_docker,
             force_poetry=force_poetry,
             allow_prompt=False,

lange_python-0.3.1/lange/distribution/__init__.py

@@ -0,0 +1,7 @@
+import logging
+
+logger = logging.getLogger("lange.distribution")
+
+from ._client import DistributionClient
+
+__all__ = ["DistributionClient"]

lange_python-0.3.1/lange/distribution/_client.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import mimetypes
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from ._util import detect_distribution_os, parse_distribution_os, _compare_versions
+from .._util import BaseLangeLabsClient
+
+
+class DistributionClient(BaseLangeLabsClient):
+    """
+    Client for querying public distribution metadata and update availability.
+
+    :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.
+    """
+
+    def __init__(self,
+                 distribution_name: str,
+                 host: str = "https://lange-labs.com",
+                 api_key: str | None = None,
+                 timeout: float = 10.0) -> None:
+        """
+        Initialize a distribution metadata client for the Lange app service.
+
+        :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.
+        :param distribution_name: Distribution name as stored by the app service.
+        :raises ValueError: If ``api_key`` is unavailable or empty.
+        """
+        super().__init__(api_key, host=host)
+        self.timeout = timeout
+        normalized_distribution_name = distribution_name.strip()
+
+        if not normalized_distribution_name:
+            raise ValueError("distribution_name is required.")
+
+        if " " in normalized_distribution_name:
+            raise ValueError("check your distribution name again. spaces are not allowed by design")
+
+        self.distribution_name = normalized_distribution_name
+
+    def search_for_update(self, current_version: str) -> str | None:
+        """
+        Resolve the newest available version for the current OS when it is newer.
+
+        :param distribution_name: Distribution name as stored by the app service.
+        :param current_version: Current installed version string.
+        :returns: Newer version string when available, otherwise ``None``.
+        :raises ValueError: If required inputs are missing.
+        :raises httpx.HTTPError: If the metadata request fails.
+        """
+        normalized_current_version = current_version.strip()
+
+        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", [])
+
+        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
+
+        return newest_version
+
+    def _build_distribution_url(self) -> str:
+        """
+        Build the public metadata endpoint URL for one distribution.
+
+        :param distribution_name: Distribution name to request.
+        :returns: Fully qualified public metadata URL.
+        """
+        return f"{self.host}/api/public/distributions/{self.distribution_name}"
+
+    def _build_artifact_download_url(self, version: str, os_name: str) -> str:
+        """
+        Build the public artifact download endpoint URL for one version and OS.
+
+        :param version: Distribution version to download.
+        :param os_name: Operating-system label accepted by the app service.
+        :returns: Fully qualified public artifact download URL.
+        """
+        return (
+            f"{self.host}/api/public/distributions/{self.distribution_name}"
+            f"/versions/{version}/artifacts/{os_name}/download"
+        )
+
+    def _build_versions_url(self) -> str:
+        """
+        Build the authenticated distribution versions endpoint URL.
+
+        :returns: Fully qualified versions collection URL.
+        """
+        return f"{self.host}/api/distributions/{self.distribution_name}/versions"
+
+    def _get_newest_version_artifact(self, os_name: str) -> tuple[str, dict[str, Any]] | None:
+        """
+        Resolve the newest downloadable artifact for one operating system.
+
+        :param os_name: Operating-system label accepted by the app service.
+        :returns: Tuple of version string and artifact payload, otherwise ``None``.
+        :raises httpx.HTTPError: If the metadata request fails.
+        """
+        payload = self._get_distribution_payload()
+        versions = payload.get("distribution", {}).get("versions", [])
+        newest_match: tuple[str, dict[str, Any]] | 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(os_name) if isinstance(artifacts, dict) else None
+
+            if not version or not isinstance(artifact, dict):
+                continue
+
+            if newest_match is None or _compare_versions(version, newest_match[0]) > 0:
+                newest_match = (version, artifact)
+
+        return newest_match
+
+    def download_to_temp(self) -> Path:
+        """
+        Download the newest version artifact for the current OS into ``/tmp``.
+
+        :returns: Absolute path to the downloaded artifact.
+        :raises ValueError: If no downloadable artifact exists for the current OS.
+        :raises httpx.HTTPError: If the metadata or artifact download fails.
+        """
+        current_os = detect_distribution_os()
+        newest_match = self._get_newest_version_artifact(current_os)
+
+        if newest_match is None:
+            raise ValueError(f"No downloadable versions available for operating system: {current_os}.")
+
+        version, artifact = newest_match
+        filename = str(artifact.get("filename", "")).strip()
+
+        if not filename:
+            raise ValueError("Artifact filename is required.")
+
+        destination_dir = Path("/tmp") / self.distribution_name / "versions" / version
+        destination_dir.mkdir(parents=True, exist_ok=True)
+        destination_path = destination_dir / filename
+
+        client = httpx.Client(timeout=self.timeout)
+
+        try:
+            response = client.get(
+                self._build_artifact_download_url(version, current_os),
+                headers=self._build_connection_headers(),
+            )
+            response.raise_for_status()
+            destination_path.write_bytes(response.content)
+        finally:
+            client.close()
+
+        return destination_path
+
+    def upload(self, path: str | Path, version_name: str, os_name: str) -> dict[str, Any]:
+        """
+        Upload one OS-specific distribution artifact for a version.
+
+        :param path: Artifact file path to upload.
+        :param version_name: Version string to associate with the artifact.
+        :param os_name: Operating-system label for the artifact.
+        :returns: Decoded JSON response payload.
+        :raises ValueError: If any input is missing, invalid, or the file does not exist.
+        :raises httpx.HTTPError: If the upload request fails.
+        """
+        artifact_path = Path(path)
+        normalized_version_name = version_name.strip()
+        normalized_os_name = parse_distribution_os(os_name)
+
+        if not normalized_version_name:
+            raise ValueError("version_name is required.")
+
+        if not artifact_path.exists():
+            raise ValueError("Artifact file does not exist.")
+
+        if not artifact_path.is_file():
+            raise ValueError("Artifact path must point to a file.")
+
+        content_type = mimetypes.guess_type(artifact_path.name)[0] or "application/octet-stream"
+        file_field_name = f"{normalized_os_name}File"
+
+        client = httpx.Client(timeout=self.timeout)
+
+        try:
+            with artifact_path.open("rb") as artifact_file:
+                response = client.post(
+                    self._build_versions_url(),
+                    headers=self._build_connection_headers(),
+                    data={"version": normalized_version_name},
+                    files={
+                        file_field_name: (
+                            artifact_path.name,
+                            artifact_file,
+                            content_type,
+                        )
+                    },
+                )
+            response.raise_for_status()
+            return response.json()
+        finally:
+            client.close()
+
+    def _get_distribution_payload(self) -> dict[str, Any]:
+        """
+        Fetch the public distribution metadata payload from the app service.
+
+        :param distribution_name: Distribution name to fetch.
+        :returns: Decoded JSON payload.
+        :raises httpx.HTTPError: If the request fails or returns invalid JSON.
+        """
+        client = httpx.Client(timeout=self.timeout)
+
+        try:
+            response = client.get(
+                self._build_distribution_url(),
+                headers=self._build_connection_headers(),
+            )
+            response.raise_for_status()
+            return response.json()
+        finally:
+            client.close()

lange_python-0.3.1/lange/distribution/_util.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import platform
+
+
+def detect_distribution_os() -> str:
+    """
+    Detect the current operating system for distribution artifact selection.
+
+    :returns: Normalized operating-system label accepted by the app service.
+    :raises ValueError: If the current platform is unsupported.
+    """
+    system_name = platform.system().strip().lower()
+
+    if system_name == "windows":
+        return "windows"
+
+    if system_name == "darwin":
+        return "macos"
+
+    if system_name == "linux":
+        return "linux"
+
+    raise ValueError(f"Unsupported operating system: {platform.system()}.")
+
+
+def parse_distribution_os(os_name: str) -> str:
+    """
+    Validate and normalize a distribution artifact operating-system label.
+
+    :param os_name: Untrusted operating-system label.
+    :returns: Normalized operating-system label accepted by the app service.
+    :raises ValueError: If the operating-system label is missing or unsupported.
+    """
+    normalized_os_name = os_name.strip().lower()
+
+    if not normalized_os_name:
+        raise ValueError("os_name is required.")
+
+    if normalized_os_name not in {"windows", "macos", "linux"}:
+        raise ValueError("os_name must be one of: windows, macos, linux.")
+
+    return normalized_os_name
+
+
+def _compare_versions(left: str, right: str) -> int:
+    """
+    Compare two dotted numeric version strings.
+
+    :param left: Left-hand version string.
+    :param right: Right-hand version string.
+    :returns: Positive when ``left`` is newer, negative when older, otherwise ``0``.
+    """
+    left_parts = _normalize_version_parts(left)
+    right_parts = _normalize_version_parts(right)
+    max_length = max(len(left_parts), len(right_parts))
+
+    padded_left = left_parts + (0,) * (max_length - len(left_parts))
+    padded_right = right_parts + (0,) * (max_length - len(right_parts))
+
+    if padded_left > padded_right:
+        return 1
+
+    if padded_left < padded_right:
+        return -1
+
+    return 0
+
+
+def _normalize_version_parts(version: str) -> tuple[int, ...]:
+    """
+    Convert a dotted numeric version string into comparable integer parts.
+
+    :param version: Version string to normalize.
+    :returns: Comparable integer tuple.
+    :raises ValueError: If the version is empty or malformed.
+    """
+    normalized_version = version.strip()
+    if not normalized_version:
+        raise ValueError("Version is required.")
+
+    parts = normalized_version.split(".")
+    normalized_parts: list[int] = []
+
+    for part in parts:
+        if not part.isdigit():
+            raise ValueError(f"Unsupported version format: {version}.")
+
+        normalized_parts.append(int(part))
+
+    return tuple(normalized_parts)

lange_python-0.3.1/lange/tunnel/__init__.py

@@ -0,0 +1,7 @@
+"""Tunnel worker client implementation for the Lange tunnel service."""
+
+
+
+from ._client import Tunnel
+
+__all__ = ["Tunnel"]

lange_python-0.3.0/lange/tunnel/__init__.py → lange_python-0.3.1/lange/tunnel/_client.py

@@ -1,12 +1,9 @@
-"""Tunnel worker client implementation for the Lange tunnel service."""
-
 from __future__ import annotations
 
 import asyncio
 import base64
 import json
 import logging
-import os
 import ssl
 import threading
 from typing import Any, Optional
@@ -15,11 +12,13 @@ from urllib.parse import urljoin
 import httpx
 import websockets
 from httpx import Timeout
+from .._util import BaseLangeLabsClient
+from ._util import _filter_hop_by_hop_headers
 
 logger = logging.getLogger("lange.tunnel")
 
 
-class Tunnel(threading.Thread):
+class Tunnel(BaseLangeLabsClient):
     """
     Thread-based tunnel worker client.
 
@@ -27,35 +26,28 @@ class Tunnel(threading.Thread):
     proxy messages to a local HTTP target.
 
     :param host: Base service URL, e.g. ``wss://example.com``.
-    :param secret_key: Bearer token used for worker authentication.
-    :param tunnel_name: Optional explicit tunnel subdomain for keys linked to multiple tunnels.
+    :param api_key: Bearer token used for worker authentication.
     :param target: Local HTTP target URL to forward tunnel traffic to.
     :param verify_ssl: Whether to verify TLS certificates for ``wss://`` hosts.
     :param max_retries: Maximum reconnect attempts, ``0`` for infinite retries.
     :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 secret key is unavailable or empty.
+    :raises ValueError: If API key is unavailable or empty.
     """
 
     def __init__(
-        self,
-        host: str = "wss://tunnel.lange-labs.com",
-        secret_key: str | None = None,
-        tunnel_name: str | None = None,
-        target: str = "http://localhost:80",
-        verify_ssl: bool = True,
-        max_retries: int = 5,
-        retry_delay: float = 5.0,
-        open_timeout: float = 20.0,
-        daemon: bool = True,
+            self,
+            host: str = "wss://tunnel.lange-labs.com",
+            api_key: str | None = None,
+            target: str = "http://localhost:80",
+            verify_ssl: bool = True,
+            max_retries: int = 5,
+            retry_delay: float = 5.0,
+            open_timeout: float = 20.0,
+            daemon: bool = True,
     ) -> None:
-        resolved_secret_key = _resolve_secret_key(secret_key)
-
-        super().__init__(daemon=daemon)
-        self.host = host.rstrip("/")
-        self.secret_key = resolved_secret_key
-        self.tunnel_name = tunnel_name.strip().lower() if tunnel_name and tunnel_name.strip() else None
+        super().__init__(api_key=api_key, daemon=daemon, host=host)
         self.target = target.rstrip("/")
         self.verify_ssl = verify_ssl
         self.max_retries = max_retries
@@ -174,24 +166,6 @@ class Tunnel(threading.Thread):
             except Exception as exc:  # pragma: no cover - best-effort close path
                 logger.debug("Failed to close websocket during reconnect: %s", exc)
 
-    def set_secret_key(self, secret_key: str, reconnect: bool = False) -> None:
-        """
-        Replace the bearer token used for future connections.
-
-        :param secret_key: New non-empty bearer token.
-        :param reconnect: Whether to reconnect immediately to apply the token.
-        :returns: ``None``.
-        :raises ValueError: If ``secret_key`` is empty.
-        """
-        if not secret_key.strip():
-            raise ValueError("A non-empty secret_key is required for tunnel worker authentication.")
-
-        with self._lock:
-            self.secret_key = secret_key.strip()
-
-        if reconnect:
-            self.reconnect()
-
     async def _run_async(self) -> None:
         """
         Run the worker connection loop with reconnect backoff.
@@ -212,11 +186,11 @@ class Tunnel(threading.Thread):
             try:
                 logger.info("Connecting to %s", tunnel_url)
                 async with websockets.connect(
-                    tunnel_url,
-                    additional_headers=headers,
-                    ssl=ssl_context,
-                    proxy=None,
-                    open_timeout=self.open_timeout,
+                        tunnel_url,
+                        additional_headers=headers,
+                        ssl=ssl_context,
+                        proxy=None,
+                        open_timeout=self.open_timeout,
                 ) as ws:
                     with self._lock:
                         self._active_ws = ws
@@ -267,9 +241,9 @@ class Tunnel(threading.Thread):
 
             wait_time = 0.0
             while (
-                wait_time < current_delay
-                and not self._stop_event.is_set()
-                and not self._reconnect_event.is_set()
+                    wait_time < current_delay
+                    and not self._stop_event.is_set()
+                    and not self._reconnect_event.is_set()
             ):
                 await asyncio.sleep(0.5)
                 wait_time += 0.5
@@ -349,7 +323,7 @@ class Tunnel(threading.Thread):
         body = base64.b64decode(body_b64) if body_b64 else None
 
         url = urljoin(f"{self.target}/", path.lstrip("/"))
-        filtered_headers = self._filter_hop_by_hop_headers(headers)
+        filtered_headers = _filter_hop_by_hop_headers(headers)
 
         try:
             response = await client.request(
@@ -383,26 +357,13 @@ class Tunnel(threading.Thread):
         """
         return f"{self.host}/api/tunnels/connection"
 
-    def _build_connection_headers(self) -> dict[str, str]:
-        """
-        Build outbound handshake headers.
-
-        :returns: Header dictionary with bearer authorization and optional tunnel name.
-        """
-        with self._lock:
-            headers = {"Authorization": f"Bearer {self.secret_key}"}
-            if self.tunnel_name is not None:
-                headers["X-Tunnel-Name"] = self.tunnel_name
-
-            return headers
-
     def _set_connected(
-        self,
-        value: bool,
-        remote_address: Optional[str] = None,
-        remote_address_roundrobin: Optional[str] = None,
-        worker_index: int = -1,
-        pool_size: int = 0,
+            self,
+            value: bool,
+            remote_address: Optional[str] = None,
+            remote_address_roundrobin: Optional[str] = None,
+            worker_index: int = -1,
+            pool_size: int = 0,
     ) -> None:
         """
         Update connection state atomically.
@@ -439,42 +400,3 @@ class Tunnel(threading.Thread):
         ssl_context.check_hostname = False
         ssl_context.verify_mode = ssl.CERT_NONE
         return ssl_context
-
-    @staticmethod
-    def _filter_hop_by_hop_headers(headers: Any) -> dict[str, str]:
-        """
-        Remove hop-by-hop headers before forwarding to the local target.
-
-        :param headers: Request header mapping.
-        :returns: Filtered header mapping.
-        """
-        if not isinstance(headers, dict):
-            return {}
-
-        hop_by_hop = {"connection", "keep-alive", "transfer-encoding", "upgrade"}
-        return {
-            str(key): str(value)
-            for key, value in headers.items()
-            if str(key).lower() not in hop_by_hop
-        }
-
-
-def _resolve_secret_key(secret_key: str | None) -> str:
-    """
-    Resolve secret key from argument or environment.
-
-    :param secret_key: Optional direct secret key value.
-    :returns: Sanitized non-empty secret key.
-    :raises ValueError: If no non-empty secret key is available.
-    """
-    if secret_key is not None and secret_key.strip():
-        return secret_key.strip()
-
-    env_secret_key = os.getenv("LANGE_SECRET_KEY", "")
-    if env_secret_key.strip():
-        return env_secret_key.strip()
-
-    raise ValueError(
-        "A non-empty secret_key is required. "
-        "Pass secret_key directly or set LANGE_SECRET_KEY."
-    )

lange_python-0.3.1/lange/tunnel/_util.py

@@ -0,0 +1,18 @@
+from typing import Any
+
+def _filter_hop_by_hop_headers(headers: Any) -> dict[str, str]:
+    """
+    Remove hop-by-hop headers before forwarding to the local target.
+
+    :param headers: Request header mapping.
+    :returns: Filtered header mapping.
+    """
+    if not isinstance(headers, dict):
+        return {}
+
+    hop_by_hop = {"connection", "keep-alive", "transfer-encoding", "upgrade"}
+    return {
+        str(key): str(value)
+        for key, value in headers.items()
+        if str(key).lower() not in hop_by_hop
+    }

{lange_python-0.3.0 → lange_python-0.3.1}/pyproject.toml

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

lange_python-0.3.0/lange/__init__.py

@@ -1,5 +0,0 @@
-"""Public package exports for lange-python."""
-
-from .tunnel import Tunnel
-
-__all__ = ["Tunnel"]