lange-python 0.3.5__tar.gz → 0.3.7__tar.gz

{lange_python-0.3.5 → lange_python-0.3.7}/PKG-INFO

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: lange-python
-Version: 0.3.5
+Version: 0.3.7
 Summary: A bundeld set of tools, clients for the lange-suite of tools and more.
 Author: contact@robertlange.me
-Requires-Python: >=3.13
+Requires-Python: >=3.10
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: click (>=8.3.1,<9.0.0)
@@ -30,6 +33,24 @@ lange distribution publish \
   --os macos
 ```
 
+Apply a macOS app update after downloading the published zip artifact:
+
+```python
+from pathlib import Path
+
+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.
+```
+
 ## Tunnel worker
 
 ```python

{lange_python-0.3.5 → lange_python-0.3.7}/README.md

@@ -15,6 +15,24 @@ lange distribution publish \
   --os macos
 ```
 
+Apply a macOS app update after downloading the published zip artifact:
+
+```python
+from pathlib import Path
+
+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.
+```
+
 ## Tunnel worker
 
 ```python

{lange_python-0.3.5 → lange_python-0.3.7}/lange/distribution/_client.py

@@ -1,12 +1,19 @@
 from __future__ import annotations
 
+import os
 import mimetypes
 from pathlib import Path
 from typing import Any
 
 import httpx
 
-from ._util import detect_distribution_os, parse_distribution_os, _compare_versions
+from ._update_macos import extract_macos_app_from_zip, spawn_macos_update_process
+from ._util import (
+    _compare_versions,
+    detect_distribution_os,
+    parse_distribution_os,
+    validate_installed_macos_app_path,
+)
 from .._util import BaseLangeLabsClient
 
 
@@ -158,7 +165,87 @@ class DistributionClient(BaseLangeLabsClient):
         if newest_match is None:
             raise ValueError(f"No downloadable versions available for operating system: {current_os}.")
 
-        version, artifact = newest_match
+        version, _artifact = newest_match
+
+        return self._download_version_artifact_to_temp(version=version, os_name=current_os)
+
+    def update(
+        self,
+        *,
+        current_version: str,
+        installed_app_path: str | Path,
+        target_version: str | None = None,
+        current_process_id: int | None = None,
+        wait_for_exit_timeout: float = 30.0,
+    ) -> dict[str, str]:
+        """
+        Download and stage a macOS update, then spawn a detached helper to apply it.
+
+        :param current_version: Current installed version string.
+        :param installed_app_path: Path to the installed macOS ``.app`` bundle to replace.
+        :param target_version: Explicit target version to install. When omitted, the newest newer version is used.
+        :param current_process_id: PID that must exit before replacement begins. Defaults to the current process.
+        :param wait_for_exit_timeout: Maximum seconds the helper waits for the current process to exit.
+        :returns: Metadata describing the staged update and spawned helper process.
+        :raises ValueError: If the platform, app path, or artifact layout is invalid.
+        :raises RuntimeError: If the detached helper process could not be launched.
+        """
+        current_os = detect_distribution_os()
+        if current_os != "macos":
+            raise ValueError(f"macOS updates are not implemented for operating system: {current_os}.")
+
+        normalized_current_version = current_version.strip()
+        if not normalized_current_version:
+            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(
+            normalized_current_version
+        )
+
+        if not resolved_target_version:
+            raise ValueError("No newer update is available for the current macOS installation.")
+
+        artifact = self._get_version_artifact(version=resolved_target_version, os_name="macos")
+        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")
+        extracted_app_path = extract_macos_app_from_zip(artifact_path)
+        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,
+        )
+        process_id = helper_process.get("process_id", helper_process.get("pid", ""))
+
+        return {
+            "version": resolved_target_version,
+            "artifact_path": str(artifact_path),
+            "installed_app_path": str(normalized_installed_app_path),
+            "extracted_app_path": str(extracted_app_path),
+            "script_path": helper_process["script_path"],
+            "log_path": helper_process["log_path"],
+            "process_id": str(process_id),
+        }
+
+    def _download_version_artifact_to_temp(self, version: str, os_name: str) -> Path:
+        """
+        Download one explicit version artifact for one operating system into ``/tmp``.
+
+        :param version: Distribution version to download.
+        :param os_name: Operating-system label accepted by the app service.
+        :returns: Absolute path to the downloaded artifact.
+        :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)
+
+        if artifact is None:
+            raise ValueError(f"No {os_name} artifact is available for version {version}.")
+
         filename = str(artifact.get("filename", "")).strip()
 
         if not filename:
@@ -172,7 +259,7 @@ class DistributionClient(BaseLangeLabsClient):
 
         try:
             response = client.get(
-                self._build_artifact_download_url(version, current_os),
+                self._build_artifact_download_url(version, os_name),
                 headers=self._build_connection_headers(),
             )
             response.raise_for_status()
@@ -182,6 +269,40 @@ class DistributionClient(BaseLangeLabsClient):
 
         return destination_path
 
+    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.
+
+        :param version: Distribution version to inspect.
+        :param os_name: Operating-system label accepted by the app service.
+        :returns: Artifact metadata for the version and OS, otherwise ``None``.
+        :raises ValueError: If the version is missing.
+        :raises httpx.HTTPError: If the metadata request fails.
+        """
+        normalized_version = version.strip()
+        normalized_os_name = parse_distribution_os(os_name)
+
+        if not normalized_version:
+            raise ValueError("version is required.")
+
+        payload = self._get_distribution_payload()
+        versions = payload.get("distribution", {}).get("versions", [])
+
+        for version_entry in versions:
+            if not isinstance(version_entry, dict):
+                continue
+
+            if str(version_entry.get("version", "")).strip() != normalized_version:
+                continue
+
+            artifacts = version_entry.get("artifacts", {})
+            artifact = artifacts.get(normalized_os_name) if isinstance(artifacts, dict) else None
+            if isinstance(artifact, dict):
+                return artifact
+            return None
+
+        return None
+
     def upload(self, path: str | Path, version_name: str, os_name: str) -> dict[str, Any]:
         """
         Upload one OS-specific distribution artifact for a version.

lange_python-0.3.7/lange/distribution/_update_macos.py

@@ -0,0 +1,161 @@
+"""macOS-specific helpers for the distribution update workflow."""
+
+from __future__ import annotations
+
+import shutil
+import stat
+import subprocess
+import zipfile
+from pathlib import Path
+from shlex import quote
+
+
+def extract_macos_app_from_zip(archive_path: str | Path) -> Path:
+    """
+    Extract a macOS update archive and return the only top-level ``.app`` bundle.
+
+    :param archive_path: Path to the downloaded zip archive.
+    :returns: Absolute path to the extracted ``.app`` bundle.
+    :raises ValueError: If the archive is not a zip or does not contain exactly one top-level app bundle.
+    """
+    normalized_archive_path = Path(archive_path).expanduser().resolve()
+
+    if normalized_archive_path.suffix.lower() != ".zip":
+        raise ValueError("macOS update artifacts must be .zip files.")
+
+    destination_path = normalized_archive_path.parent / "extracted"
+    if destination_path.exists():
+        shutil.rmtree(destination_path)
+    destination_path.mkdir(parents=True, exist_ok=True)
+
+    with zipfile.ZipFile(normalized_archive_path) as archive:
+        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]
+
+
+def spawn_macos_update_process(
+    *,
+    source_app_path: str | Path,
+    installed_app_path: str | Path,
+    current_process_id: int,
+    workspace_path: str | Path,
+    wait_for_exit_timeout: float,
+) -> dict[str, str]:
+    """
+    Generate and launch the detached macOS helper process that applies the update.
+
+    :param source_app_path: Extracted replacement app bundle.
+    :param installed_app_path: Installed app bundle that should be replaced.
+    :param current_process_id: PID that must exit before replacement begins.
+    :param workspace_path: Temporary workspace for helper files and logs.
+    :param wait_for_exit_timeout: Maximum number of seconds to wait for the PID to exit.
+    :returns: Metadata about the spawned helper process and generated files.
+    :raises RuntimeError: If the helper process could not be launched.
+    """
+    normalized_source_app_path = Path(source_app_path).expanduser().resolve()
+    normalized_installed_app_path = Path(installed_app_path).expanduser().resolve()
+    normalized_workspace_path = Path(workspace_path).expanduser().resolve()
+
+    normalized_workspace_path.mkdir(parents=True, exist_ok=True)
+
+    backup_app_path = normalized_installed_app_path.parent / f"{normalized_installed_app_path.name}.previous"
+    script_path = normalized_workspace_path / "apply-update.sh"
+    log_path = normalized_workspace_path / "apply-update.log"
+    script_contents = _build_macos_update_script(
+        source_app_path=normalized_source_app_path,
+        installed_app_path=normalized_installed_app_path,
+        backup_app_path=backup_app_path,
+        current_process_id=current_process_id,
+        wait_for_exit_timeout=wait_for_exit_timeout,
+    )
+
+    script_path.write_text(script_contents, encoding="utf-8")
+    current_mode = script_path.stat().st_mode
+    script_path.chmod(current_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    with log_path.open("ab") as log_file:
+        try:
+            process = subprocess.Popen(
+                ["/bin/bash", str(script_path)],
+                stdout=log_file,
+                stderr=subprocess.STDOUT,
+                stdin=subprocess.DEVNULL,
+                start_new_session=True,
+            )
+        except OSError as error:
+            raise RuntimeError(f"Failed to launch the macOS updater helper process: {error}") from error
+
+    return {
+        "script_path": str(script_path),
+        "log_path": str(log_path),
+        "process_id": str(process.pid),
+    }
+
+
+def _build_macos_update_script(
+    *,
+    source_app_path: Path,
+    installed_app_path: Path,
+    backup_app_path: Path,
+    current_process_id: int,
+    wait_for_exit_timeout: float,
+) -> str:
+    """
+    Build the shell script that applies the macOS app replacement with rollback.
+
+    :param source_app_path: Extracted replacement app bundle.
+    :param installed_app_path: Installed app bundle that should be replaced.
+    :param backup_app_path: Temporary backup location used for rollback.
+    :param current_process_id: PID that must exit before replacement begins.
+    :param wait_for_exit_timeout: Maximum number of seconds to wait for the PID to exit.
+    :returns: Shell script source code.
+    """
+    timeout_seconds = max(int(wait_for_exit_timeout), 0)
+
+    return f"""#!/bin/bash
+set -euo pipefail
+
+SOURCE_APP={quote(str(source_app_path))}
+TARGET_APP={quote(str(installed_app_path))}
+BACKUP_APP={quote(str(backup_app_path))}
+TARGET_PID={int(current_process_id)}
+TIMEOUT_SECONDS={timeout_seconds}
+WAITED_SECONDS=0
+
+restore_backup() {{
+  if [ -d "$BACKUP_APP" ]; then
+    rm -rf "$TARGET_APP"
+    mv "$BACKUP_APP" "$TARGET_APP"
+  fi
+}}
+
+while kill -0 "$TARGET_PID" 2>/dev/null; do
+  if [ "$WAITED_SECONDS" -ge "$TIMEOUT_SECONDS" ]; then
+    echo "Timed out waiting for process $TARGET_PID to exit."
+    exit 1
+  fi
+  sleep 1
+  WAITED_SECONDS=$((WAITED_SECONDS + 1))
+done
+
+rm -rf "$BACKUP_APP"
+
+trap 'restore_backup' ERR
+
+if [ -d "$TARGET_APP" ]; then
+  mv "$TARGET_APP" "$BACKUP_APP"
+fi
+
+/usr/bin/ditto "$SOURCE_APP" "$TARGET_APP"
+rm -rf "$BACKUP_APP"
+"""

{lange_python-0.3.5 → lange_python-0.3.7}/lange/distribution/_util.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import platform
+from pathlib import Path
 
 
 def detect_distribution_os() -> str:
@@ -89,3 +90,22 @@ def _normalize_version_parts(version: str) -> tuple[int, ...]:
         normalized_parts.append(int(part))
 
     return tuple(normalized_parts)
+
+
+def validate_installed_macos_app_path(installed_app_path: str | Path) -> Path:
+    """
+    Validate and normalize the macOS app bundle path that should be replaced.
+
+    :param installed_app_path: Untrusted path to the installed ``.app`` bundle.
+    :returns: Absolute path to the installed ``.app`` bundle.
+    :raises ValueError: If the path is missing, does not exist, or is not a ``.app`` directory.
+    """
+    normalized_path = Path(installed_app_path).expanduser().resolve()
+
+    if not normalized_path.exists():
+        raise ValueError("installed_app_path must point to an existing .app bundle.")
+
+    if not normalized_path.is_dir() or normalized_path.suffix != ".app":
+        raise ValueError("installed_app_path must point to an existing .app bundle.")
+
+    return normalized_path

{lange_python-0.3.5 → lange_python-0.3.7}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "lange-python"
-version = "0.3.5"
+version = "0.3.7"
 description = "A bundeld set of tools, clients for the lange-suite of tools and more."
 authors = [
     {name = "contact@robertlange.me"}
 ]
 readme = "README.md"
-requires-python = ">=3.13"
+requires-python = ">=3.10"
 dependencies = [
     "httpx (>=0.28.1,<0.29.0)",
     "websockets (>=12.0,<20.0)",