lange-python 0.3.12__tar.gz → 0.3.13__tar.gz

{lange_python-0.3.12 → lange_python-0.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lange-python
-Version: 0.3.12
+Version: 0.3.13
 Summary: A bundeld set of tools, clients for the lange-suite of tools and more.
 Author: contact@robertlange.me
 Requires-Python: >=3.10
@@ -42,13 +42,17 @@ from lange.distribution import DistributionClient
 
 client = DistributionClient(distribution_name="desktop-app", api_key="your-api-key")
 
-update_metadata = client.update(
-    current_version="1.2.3",
-    installed_app_path=Path("/Applications/Desktop App.app"),
-)
-
-print(update_metadata["version"])
-# The caller should now shut down so the detached helper can replace the app bundle.
+latest = client.check_for_update("1.2.3")
+if latest:
+    version, artifact_path = client.download(current_version="1.2.3")
+    print(version, artifact_path)
+    update_metadata = client.update(
+        current_version="1.2.3",
+        installed_app_path=Path("/Applications/Desktop App.app"),
+        relaunch=True,
+    )
+    print(update_metadata["version"])
+    # The caller should now shut down so the detached helper can replace and relaunch the app.
 ```
 
 The distribution client also exposes `status` and `reload()` for refresh-aware integrations:
@@ -58,6 +62,7 @@ client = DistributionClient(distribution_name="desktop-app", api_key="your-api-k
 
 latest_version = client.search_for_update("1.2.3")
 print(client.status)  # connected
+print(client.update_state["can_download"])
 
 client.reload()  # repeats the last update check
 client.reload(api_key=None)  # clears authentication and marks the client unauthenticated

{lange_python-0.3.12 → lange_python-0.3.13}/README.md

@@ -24,13 +24,17 @@ from lange.distribution import DistributionClient
 
 client = DistributionClient(distribution_name="desktop-app", api_key="your-api-key")
 
-update_metadata = client.update(
-    current_version="1.2.3",
-    installed_app_path=Path("/Applications/Desktop App.app"),
-)
-
-print(update_metadata["version"])
-# The caller should now shut down so the detached helper can replace the app bundle.
+latest = client.check_for_update("1.2.3")
+if latest:
+    version, artifact_path = client.download(current_version="1.2.3")
+    print(version, artifact_path)
+    update_metadata = client.update(
+        current_version="1.2.3",
+        installed_app_path=Path("/Applications/Desktop App.app"),
+        relaunch=True,
+    )
+    print(update_metadata["version"])
+    # The caller should now shut down so the detached helper can replace and relaunch the app.
 ```
 
 The distribution client also exposes `status` and `reload()` for refresh-aware integrations:
@@ -40,6 +44,7 @@ client = DistributionClient(distribution_name="desktop-app", api_key="your-api-k
 
 latest_version = client.search_for_update("1.2.3")
 print(client.status)  # connected
+print(client.update_state["can_download"])
 
 client.reload()  # repeats the last update check
 client.reload(api_key=None)  # clears authentication and marks the client unauthenticated

{lange_python-0.3.12 → lange_python-0.3.13}/lange/distribution/_client.py

@@ -1,13 +1,19 @@
 from __future__ import annotations
 
+import hashlib
 import os
 import mimetypes
+import shutil
 from pathlib import Path
 from typing import Any
 
 import httpx
 
-from ._update_macos import extract_macos_app_from_zip, spawn_macos_update_process
+from ._update_macos import (
+    extract_macos_app_from_zip,
+    read_macos_bundle_identifier,
+    spawn_macos_update_process,
+)
 from ._util import (
     _compare_versions,
     detect_distribution_os,
@@ -46,6 +52,9 @@ class DistributionClient(BaseLangeLabsClient):
         self.timeout = timeout
         self._last_checked_version: str | None = None
         self._last_update_result: str | None = None
+        self._last_downloaded_version: str | None = None
+        self._last_downloaded_artifact_path: str | None = None
+        self._last_error: str | None = None
         normalized_distribution_name = distribution_name.strip()
 
         if not normalized_distribution_name:
@@ -55,6 +64,7 @@ class DistributionClient(BaseLangeLabsClient):
             raise ValueError("check your distribution name again. spaces are not allowed by design")
 
         self.distribution_name = normalized_distribution_name
+        self._refresh_capabilities()
 
     @property
     def status(self) -> str:
@@ -74,6 +84,22 @@ class DistributionClient(BaseLangeLabsClient):
         """
         return self._last_checked_version
 
+    @property
+    def update_state(self) -> dict[str, Any]:
+        can_check = self.api_key is not None
+        can_download = self._last_update_result is not None and can_check
+        return {
+            "status": self._status,
+            "last_checked_version": self._last_checked_version,
+            "available_version": self._last_update_result,
+            "downloaded_version": self._last_downloaded_version,
+            "downloaded_artifact_path": self._last_downloaded_artifact_path,
+            "can_check_for_update": can_check,
+            "can_download": can_download,
+            "can_update": can_download or self._last_downloaded_artifact_path is not None,
+            "last_error": self._last_error,
+        }
+
     def reload(self, api_key: str | None | object = _UNSET_API_KEY) -> None:
         """
         Reload authentication and repeat the last update check when available.
@@ -82,18 +108,24 @@ class DistributionClient(BaseLangeLabsClient):
         :returns: ``None``.
         """
         super().reload(api_key=api_key)
+        self._last_error = None
 
         if self.api_key is None:
             self._last_update_result = None
+            self._refresh_capabilities()
             return
 
         if self._last_checked_version is None:
             self._set_status("off")
+            self._refresh_capabilities()
             return
 
-        self.search_for_update(self._last_checked_version)
+        self.check_for_update(self._last_checked_version)
 
     def search_for_update(self, current_version: str) -> str | None:
+        return self.check_for_update(current_version)
+
+    def check_for_update(self, current_version: str) -> str | None:
         """
         Resolve the newest available version for the current OS when it is newer.
 
@@ -112,6 +144,8 @@ class DistributionClient(BaseLangeLabsClient):
 
         if self.api_key is None:
             self._set_status("unauthenticated")
+            self._last_error = "API key is required for this operation."
+            self._refresh_capabilities()
             raise ValueError("API key is required for this operation.")
 
         self._set_status("pending")
@@ -141,13 +175,17 @@ class DistributionClient(BaseLangeLabsClient):
                     newest_version = version
 
             self._last_update_result = newest_version
+            self._last_error = None
             self._set_status("connected")
+            self._refresh_capabilities()
             return newest_version
-        except Exception:
+        except Exception as error:
             if self.api_key is None:
                 self._set_status("unauthenticated")
             else:
                 self._set_status("failed")
+            self._last_error = str(error)
+            self._refresh_capabilities()
             raise
 
     def _build_distribution_url(self) -> str:
@@ -209,22 +247,42 @@ class DistributionClient(BaseLangeLabsClient):
         return newest_match
 
     def download_to_temp(self) -> Path:
+        version, artifact_path = self.download()
+        _ = version
+        return artifact_path
+
+    def download(self, current_version: str | None = None, target_version: str | None = None) -> tuple[str, Path]:
         """
-        Download the newest version artifact for the current OS into ``/tmp``.
+        Download one update artifact for the current OS into ``/tmp``.
 
-        :returns: Absolute path to the downloaded artifact.
+        :param current_version: Optional current installed version used to discover newer versions.
+        :param target_version: Optional explicit version to download.
+        :returns: Tuple of resolved version and downloaded artifact path.
         :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:
+        resolved_version: str | None = None
+
+        if target_version is not None:
+            resolved_version = target_version.strip()
+        elif current_version is not None:
+            resolved_version = self.check_for_update(current_version)
+        else:
+            newest_match = self._get_newest_version_artifact(current_os)
+            if newest_match is not None:
+                resolved_version = newest_match[0]
+
+        if not resolved_version:
             raise ValueError(f"No downloadable versions available for operating system: {current_os}.")
 
-        version, _artifact = newest_match
-
-        return self._download_version_artifact_to_temp(version=version, os_name=current_os)
+        artifact_path = self._download_version_artifact_to_temp(version=resolved_version, os_name=current_os)
+        self._last_downloaded_version = resolved_version
+        self._last_downloaded_artifact_path = str(artifact_path)
+        self._last_error = None
+        self._refresh_capabilities()
+        self._cleanup_old_temp_versions()
+        return resolved_version, artifact_path
 
     def update(
         self,
@@ -234,6 +292,8 @@ class DistributionClient(BaseLangeLabsClient):
         target_version: str | None = None,
         current_process_id: int | None = None,
         wait_for_exit_timeout: float = 30.0,
+        relaunch: bool = True,
+        strict_bundle_identifier: bool = True,
     ) -> dict[str, str]:
         """
         Download and stage a macOS update, then spawn a detached helper to apply it.
@@ -256,7 +316,7 @@ class DistributionClient(BaseLangeLabsClient):
             raise ValueError("current_version is required.")
 
         normalized_installed_app_path = validate_installed_macos_app_path(installed_app_path)
-        resolved_target_version = target_version.strip() if target_version is not None else self.search_for_update(
+        resolved_target_version = target_version.strip() if target_version is not None else self.check_for_update(
             normalized_current_version
         )
 
@@ -267,16 +327,37 @@ class DistributionClient(BaseLangeLabsClient):
         if artifact is None:
             raise ValueError(f"No macos artifact is available for version {resolved_target_version}.")
 
-        artifact_path = self._download_version_artifact_to_temp(version=resolved_target_version, os_name="macos")
+        artifact_path = self._download_version_artifact_to_temp(
+            version=resolved_target_version,
+            os_name="macos",
+            artifact=artifact,
+        )
         extracted_app_path = extract_macos_app_from_zip(artifact_path)
+        if strict_bundle_identifier:
+            installed_bundle_identifier = read_macos_bundle_identifier(normalized_installed_app_path)
+            extracted_bundle_identifier = read_macos_bundle_identifier(extracted_app_path)
+            if (
+                installed_bundle_identifier is not None
+                and extracted_bundle_identifier is not None
+                and installed_bundle_identifier != extracted_bundle_identifier
+            ):
+                raise ValueError(
+                    "Downloaded app bundle identifier does not match installed application bundle identifier."
+                )
         helper_process = spawn_macos_update_process(
             source_app_path=extracted_app_path,
             installed_app_path=normalized_installed_app_path,
             current_process_id=os.getpid() if current_process_id is None else current_process_id,
             workspace_path=artifact_path.parent,
             wait_for_exit_timeout=wait_for_exit_timeout,
+            relaunch=relaunch,
         )
         process_id = helper_process.get("process_id", helper_process.get("pid", ""))
+        self._last_downloaded_version = resolved_target_version
+        self._last_downloaded_artifact_path = str(artifact_path)
+        self._last_error = None
+        self._refresh_capabilities()
+        self._cleanup_old_temp_versions()
 
         return {
             "version": resolved_target_version,
@@ -288,7 +369,12 @@ class DistributionClient(BaseLangeLabsClient):
             "process_id": str(process_id),
         }
 
-    def _download_version_artifact_to_temp(self, version: str, os_name: str) -> Path:
+    def _download_version_artifact_to_temp(
+        self,
+        version: str,
+        os_name: str,
+        artifact: dict[str, Any] | None = None,
+    ) -> Path:
         """
         Download one explicit version artifact for one operating system into ``/tmp``.
 
@@ -298,12 +384,12 @@ class DistributionClient(BaseLangeLabsClient):
         :raises ValueError: If the artifact metadata is incomplete or missing.
         :raises httpx.HTTPError: If the metadata or artifact download fails.
         """
-        artifact = self._get_version_artifact(version=version, os_name=os_name)
+        resolved_artifact = artifact if artifact is not None else self._get_version_artifact(version=version, os_name=os_name)
 
-        if artifact is None:
+        if resolved_artifact is None:
             raise ValueError(f"No {os_name} artifact is available for version {version}.")
 
-        filename = str(artifact.get("filename", "")).strip()
+        filename = str(resolved_artifact.get("filename", "")).strip()
 
         if not filename:
             raise ValueError("Artifact filename is required.")
@@ -321,11 +407,40 @@ class DistributionClient(BaseLangeLabsClient):
             )
             response.raise_for_status()
             destination_path.write_bytes(response.content)
+            self._verify_downloaded_artifact(destination_path, resolved_artifact)
         finally:
             client.close()
 
         return destination_path
 
+    def _verify_downloaded_artifact(self, artifact_path: Path, artifact_payload: dict[str, Any]) -> None:
+        checksum = str(
+            artifact_payload.get("sha256")
+            or artifact_payload.get("checksumSha256")
+            or artifact_payload.get("checksum")
+            or ""
+        ).strip().lower()
+        if not checksum:
+            raise ValueError("Artifact checksum metadata is required for secure updates.")
+
+        digest = hashlib.sha256(artifact_path.read_bytes()).hexdigest()
+        if digest.lower() != checksum:
+            raise ValueError("Downloaded artifact checksum validation failed.")
+
+    def _cleanup_old_temp_versions(self, retain_count: int = 3) -> None:
+        versions_root = Path("/tmp") / self.distribution_name / "versions"
+        if not versions_root.is_dir():
+            return
+
+        version_dirs = [path for path in versions_root.iterdir() if path.is_dir()]
+        version_dirs.sort(key=lambda directory: directory.stat().st_mtime, reverse=True)
+        for stale_path in version_dirs[retain_count:]:
+            shutil.rmtree(stale_path, ignore_errors=True)
+
+    def _refresh_capabilities(self) -> None:
+        # The update_state property is computed from current fields; this method keeps callers consistent.
+        return None
+
     def _get_version_artifact(self, version: str, os_name: str) -> dict[str, Any] | None:
         """
         Resolve the downloadable artifact payload for one version and operating system.

{lange_python-0.3.12 → lange_python-0.3.13}/lange/distribution/_update_macos.py

@@ -6,6 +6,7 @@ import shutil
 import stat
 import subprocess
 import zipfile
+import plistlib
 from pathlib import Path
 from shlex import quote
 
@@ -29,18 +30,15 @@ def extract_macos_app_from_zip(archive_path: str | Path) -> Path:
     destination_path.mkdir(parents=True, exist_ok=True)
 
     with zipfile.ZipFile(normalized_archive_path) as archive:
+        app_bundle_roots = _collect_zip_app_bundle_roots(archive)
+        if len(app_bundle_roots) != 1:
+            raise ValueError("macOS update archives must contain exactly one .app bundle.")
         archive.extractall(destination_path)
 
-    app_bundles = [
-        child.resolve()
-        for child in destination_path.iterdir()
-        if child.is_dir() and child.suffix == ".app"
-    ]
-
-    if len(app_bundles) != 1:
-        raise ValueError("macOS update archives must contain exactly one top-level .app bundle.")
-
-    return app_bundles[0]
+    extracted_path = (destination_path / app_bundle_roots[0]).resolve()
+    if not extracted_path.is_dir() or extracted_path.suffix != ".app":
+        raise ValueError("macOS update archive extraction did not produce a valid .app bundle.")
+    return extracted_path
 
 
 def spawn_macos_update_process(
@@ -50,6 +48,7 @@ def spawn_macos_update_process(
     current_process_id: int,
     workspace_path: str | Path,
     wait_for_exit_timeout: float,
+    relaunch: bool = True,
 ) -> dict[str, str]:
     """
     Generate and launch the detached macOS helper process that applies the update.
@@ -77,6 +76,7 @@ def spawn_macos_update_process(
         backup_app_path=backup_app_path,
         current_process_id=current_process_id,
         wait_for_exit_timeout=wait_for_exit_timeout,
+        relaunch=relaunch,
     )
 
     script_path.write_text(script_contents, encoding="utf-8")
@@ -109,6 +109,7 @@ def _build_macos_update_script(
     backup_app_path: Path,
     current_process_id: int,
     wait_for_exit_timeout: float,
+    relaunch: bool,
 ) -> str:
     """
     Build the shell script that applies the macOS app replacement with rollback.
@@ -122,7 +123,7 @@ def _build_macos_update_script(
     """
     timeout_seconds = max(int(wait_for_exit_timeout), 0)
 
-    return f"""#!/bin/bash
+    script = f"""#!/bin/bash
 set -euo pipefail
 
 SOURCE_APP={quote(str(source_app_path))}
@@ -159,3 +160,32 @@ fi
 /usr/bin/ditto "$SOURCE_APP" "$TARGET_APP"
 rm -rf "$BACKUP_APP"
 """
+    if relaunch:
+        script += '\n/usr/bin/open "$TARGET_APP"\n'
+    return script
+
+
+def _collect_zip_app_bundle_roots(archive: zipfile.ZipFile) -> list[Path]:
+    app_bundle_roots: set[Path] = set()
+    for member_name in archive.namelist():
+        parts = Path(member_name).parts
+        for index, part in enumerate(parts):
+            if part.endswith(".app"):
+                app_bundle_roots.add(Path(*parts[: index + 1]))
+                break
+
+    return sorted(app_bundle_roots, key=lambda bundle_path: len(bundle_path.parts))
+
+
+def read_macos_bundle_identifier(app_path: str | Path) -> str | None:
+    info_plist_path = Path(app_path).expanduser().resolve() / "Contents" / "Info.plist"
+    if not info_plist_path.is_file():
+        return None
+
+    with info_plist_path.open("rb") as info_plist_file:
+        payload = plistlib.load(info_plist_file)
+
+    bundle_identifier = payload.get("CFBundleIdentifier")
+    if not isinstance(bundle_identifier, str):
+        return None
+    return bundle_identifier.strip() or None

{lange_python-0.3.12 → lange_python-0.3.13}/lange/distribution/_util.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import os
 import platform
+import re
 from pathlib import Path
 
 
@@ -52,12 +54,12 @@ def _compare_versions(left: str, right: str) -> int:
     :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))
+    left_core, left_pre = _normalize_version_parts(left)
+    right_core, right_pre = _normalize_version_parts(right)
+    max_length = max(len(left_core), len(right_core))
 
-    padded_left = left_parts + (0,) * (max_length - len(left_parts))
-    padded_right = right_parts + (0,) * (max_length - len(right_parts))
+    padded_left = left_core + (0,) * (max_length - len(left_core))
+    padded_right = right_core + (0,) * (max_length - len(right_core))
 
     if padded_left > padded_right:
         return 1
@@ -65,10 +67,41 @@ def _compare_versions(left: str, right: str) -> int:
     if padded_left < padded_right:
         return -1
 
+    if left_pre is None and right_pre is None:
+        return 0
+    if left_pre is None:
+        return 1
+    if right_pre is None:
+        return -1
+
+    max_pre_len = max(len(left_pre), len(right_pre))
+    for index in range(max_pre_len):
+        if index >= len(left_pre):
+            return -1
+        if index >= len(right_pre):
+            return 1
+
+        left_identifier = left_pre[index]
+        right_identifier = right_pre[index]
+
+        if left_identifier == right_identifier:
+            continue
+
+        left_is_number = left_identifier.isdigit()
+        right_is_number = right_identifier.isdigit()
+
+        if left_is_number and right_is_number:
+            return 1 if int(left_identifier) > int(right_identifier) else -1
+        if left_is_number and not right_is_number:
+            return -1
+        if not left_is_number and right_is_number:
+            return 1
+        return 1 if left_identifier > right_identifier else -1
+
     return 0
 
 
-def _normalize_version_parts(version: str) -> tuple[int, ...]:
+def _normalize_version_parts(version: str) -> tuple[tuple[int, ...], tuple[str, ...] | None]:
     """
     Convert a dotted numeric version string into comparable integer parts.
 
@@ -80,7 +113,9 @@ def _normalize_version_parts(version: str) -> tuple[int, ...]:
     if not normalized_version:
         raise ValueError("Version is required.")
 
-    parts = normalized_version.split(".")
+    version_without_build = normalized_version.split("+", 1)[0]
+    core_part, separator, prerelease_part = version_without_build.partition("-")
+    parts = core_part.split(".")
     normalized_parts: list[int] = []
 
     for part in parts:
@@ -89,7 +124,16 @@ def _normalize_version_parts(version: str) -> tuple[int, ...]:
 
         normalized_parts.append(int(part))
 
-    return tuple(normalized_parts)
+    prerelease_identifiers: tuple[str, ...] | None = None
+    if separator:
+        if not prerelease_part:
+            raise ValueError(f"Unsupported version format: {version}.")
+        tokens = prerelease_part.split(".")
+        if any(not token or not re.match(r"^[0-9A-Za-z-]+$", token) for token in tokens):
+            raise ValueError(f"Unsupported version format: {version}.")
+        prerelease_identifiers = tuple(tokens)
+
+    return tuple(normalized_parts), prerelease_identifiers
 
 
 def validate_installed_macos_app_path(installed_app_path: str | Path) -> Path:
@@ -108,4 +152,10 @@ def validate_installed_macos_app_path(installed_app_path: str | Path) -> Path:
     if not normalized_path.is_dir() or normalized_path.suffix != ".app":
         raise ValueError("installed_app_path must point to an existing .app bundle.")
 
+    if not os.access(normalized_path, os.W_OK):
+        raise ValueError("installed_app_path is not writable for replacement.")
+
+    if not os.access(normalized_path.parent, os.W_OK):
+        raise ValueError("installed_app_path parent directory is not writable for replacement.")
+
     return normalized_path

{lange_python-0.3.12 → lange_python-0.3.13}/pyproject.toml

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