dexverse-cli 0.1.4__tar.gz → 0.1.4.post1__tar.gz

{dexverse_cli-0.1.4 → dexverse_cli-0.1.4.post1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dexverse-cli
-Version: 0.1.4
+Version: 0.1.4.post1
 Summary: Download DexVerse dataset manifests and unpack HDF5 sessions
 Requires-Python: >=3.10
 Requires-Dist: av<17,>=14
@@ -39,8 +39,15 @@ falls back to the source this machine's pip is configured with (`pip.conf`,
   `python -m pip install --upgrade dexverse-cli` from the source that answered,
   and then exits with status **20**. Run the same command again; the rerun uses
   the new version.
-- The check times out, pip is missing, no source answers, or the upgrade fails:
-  one line is printed and the requested command still runs.
+- The check times out, pip is missing, no source answers, the environment is not
+  writable (a system Python), or the upgrade fails: one line is printed and the
+  requested command still runs. A directory pip cannot write is refused before
+  pip starts, so a failed upgrade never leaves a half-installed package behind.
+- On Windows, when the command was started from the installed `dexverse-dl.exe`,
+  the upgrade runs in the background: pip cannot replace that file while it is
+  the running program, so the CLI starts a helper that waits for this process to
+  exit and then upgrades. Run the command again shortly. Linux and macOS upgrade
+  in place, before the command continues.
 
 The switch is on by default. Turn the check off for one command, or permanently:
 

{dexverse_cli-0.1.4 → dexverse_cli-0.1.4.post1}/src/dexverse_cli/README.md

@@ -24,8 +24,15 @@ falls back to the source this machine's pip is configured with (`pip.conf`,
   `python -m pip install --upgrade dexverse-cli` from the source that answered,
   and then exits with status **20**. Run the same command again; the rerun uses
   the new version.
-- The check times out, pip is missing, no source answers, or the upgrade fails:
-  one line is printed and the requested command still runs.
+- The check times out, pip is missing, no source answers, the environment is not
+  writable (a system Python), or the upgrade fails: one line is printed and the
+  requested command still runs. A directory pip cannot write is refused before
+  pip starts, so a failed upgrade never leaves a half-installed package behind.
+- On Windows, when the command was started from the installed `dexverse-dl.exe`,
+  the upgrade runs in the background: pip cannot replace that file while it is
+  the running program, so the CLI starts a helper that waits for this process to
+  exit and then upgrades. Run the command again shortly. Linux and macOS upgrade
+  in place, before the command continues.
 
 The switch is on by default. Turn the check off for one command, or permanently:
 

dexverse_cli-0.1.4.post1/src/dexverse_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.4.post1"

{dexverse_cli-0.1.4 → dexverse_cli-0.1.4.post1}/src/dexverse_cli/update/gate.py

@@ -55,18 +55,46 @@ def upgrade_failure_message(result: upgrade.UpgradeOutcome) -> str:
             "`python -m pip install --force-reinstall dexverse-cli`. Continuing with the requested command."
         )
     return (
-        f"Automatic upgrade to {result.version} failed ({result.status}: {result.detail}); "
-        "run `python -m pip install --upgrade dexverse-cli` yourself if needed. "
+        f"Automatic upgrade to {result.version} failed ({result.detail}); "
+        "if the next command reports a missing dexverse_cli module, repair it with "
+        "`python -m pip install --force-reinstall --upgrade dexverse-cli`. "
         "Continuing with the requested command."
     )
 
 
+def background_upgrade(observed: check.CheckOutcome) -> None:
+    """@brief Upgrade from a detached helper when this process locks its own launcher.
+    @param observed Release observation that selected the target version.
+    @throws SystemExit With 20 once the helper owns the upgrade.
+    """
+    if upgrade.upgrade_pending():
+        print("An upgrade is already running in the background; run the command again shortly.", file=sys.stderr)
+        raise SystemExit(RERUN_EXIT_CODE)
+    target = str(observed.latest)
+    with contextlib.suppress(OSError, ValueError):
+        upgrade.mark_pending(target)
+    if upgrade.start_detached(target, check.prerelease_allowed(), observed.source):
+        print(
+            f"dexverse-cli {target} is available; upgrading in the background because the running launcher "
+            "cannot be replaced while it runs. Run the command again shortly.",
+            file=sys.stderr,
+        )
+        raise SystemExit(RERUN_EXIT_CODE)
+    upgrade.clear_pending()
+    print(
+        "Automatic upgrade needs this launcher to exit first; run "
+        "`python -m pip install --upgrade dexverse-cli` yourself. Continuing with the requested command.",
+        file=sys.stderr,
+    )
+
+
 def update_gate(*, check_enabled: bool = True, index_url: str | None = None) -> None:
     """@brief Run before any business import, stdin read, or file access.
     @param check_enabled False when the caller passed --no-update-check.
     @param index_url Optional release index for this command; publishing it as the
         environment variable keeps the check and the upgrade on one source.
-    @throws SystemExit With 20 only after a verified in-place upgrade.
+    @throws SystemExit With 20 after a verified upgrade, or once a background
+        upgrade owns the environment.
     """
     if not check_enabled:
         return
@@ -74,6 +102,9 @@ def update_gate(*, check_enabled: bool = True, index_url: str | None = None) ->
         os.environ[check.INDEX_ENVIRONMENT] = index_url
     observed = check.check_for_update()
     if observed.status == check.STATUS_OUTDATED:
+        if upgrade.console_script_locked():
+            background_upgrade(observed)
+            return
         print(
             f"dexverse-cli {observed.latest} is available (running {observed.installed}); upgrading...",
             file=sys.stderr,

dexverse_cli-0.1.4.post1/src/dexverse_cli/update/helper.py

@@ -0,0 +1,56 @@
+"""Background upgrade helper: replaces the package once the caller has exited."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+import time
+from datetime import datetime, timezone
+from uuid import uuid4
+
+from dexverse_cli import __version__
+from dexverse_cli.update import check, observation, upgrade
+
+STARTUP_GRACE_S = 3.0
+
+
+def record(outcome: upgrade.UpgradeOutcome, target: str) -> None:
+    """@brief Persist what the background upgrade actually did.
+    @param outcome Result of the retrying upgrade.
+    @param target Version the helper was asked to install.
+    """
+    succeeded = outcome.status == upgrade.STATUS_UPGRADED
+    operation = observation.UpdateOperation(
+        str(uuid4()),
+        "succeeded" if succeeded else "failed",
+        "upgraded" if succeeded else "upgrading",
+        __version__,
+        target,
+        datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "" if succeeded else outcome.status,
+    )
+    with contextlib.suppress(OSError, ValueError):
+        observation.record_operation(check.install_mode(), __version__, operation)
+
+
+def main(arguments: list[str] | None = None) -> int:
+    """@brief Upgrade this environment after the caller released its launcher.
+    @param arguments Optional argument vector for tests; defaults to the command line.
+    @return Zero when an upgrade was verified, otherwise one.
+    """
+    values = sys.argv[1:] if arguments is None else arguments
+    if len(values) < 2:
+        return 2
+    version, flag = values[0], values[1]
+    source = tuple(values[2:])
+    # The caller must be gone before pip may delete its launcher, and everything
+    # this process needs is already imported, so the sleep is safe here.
+    time.sleep(STARTUP_GRACE_S)
+    outcome = upgrade.retry_upgrade(version, flag == "1", source=source)
+    upgrade.clear_pending()
+    record(outcome, version)
+    return 0 if outcome.status == upgrade.STATUS_UPGRADED else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{dexverse_cli-0.1.4 → dexverse_cli-0.1.4.post1}/src/dexverse_cli/update/upgrade.py

@@ -7,16 +7,28 @@ import importlib.metadata
 import os
 import subprocess
 import sys
+import tempfile
+import time
 from collections.abc import Callable, Iterator, Mapping, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
+import dexverse_cli
 from dexverse_cli.update.check import PACKAGE, source_arguments
 from dexverse_cli.update.observation import update_state_path
 
 UPGRADE_TIMEOUT_S = 300.0
 LOCK_NAME = "upgrade.lock"
-MAX_DETAIL_CHARS = 200
+PENDING_NAME = "upgrade.pending.json"
+PENDING_TTL_S = 300.0
+RETRY_ATTEMPTS = 10
+RETRY_DELAY_S = 2.0
+MAX_DETAIL_CHARS = 320
+DETAIL_TAIL_LINES = 3
+
+# Failure reasons that may only mean the launcher was still running, so one more
+# attempt after the caller exits can still succeed.
+LOCK_REASONS = ("denied", "permission", "--user", "did not change")
 
 STATUS_UPGRADED = "upgraded"
 STATUS_BUSY = "busy"
@@ -161,15 +173,42 @@ def installed_version() -> str | None:
 
 
 def failure_detail(completed: subprocess.CompletedProcess[str]) -> str:
-    """@brief Summarize pip output into one bounded line for the user.
+    """@brief Summarize pip output into one bounded line that names the real blocker.
     @param completed Finished pip process.
-    @return Last non-empty output line, truncated.
+    @return Tail of pip's output, truncated; pip puts its reason before its advice.
     """
     text = (completed.stderr or "").strip() or (completed.stdout or "").strip()
     lines = [line.strip() for line in text.splitlines() if line.strip()]
     if not lines:
         return f"pip exited with {completed.returncode}"
-    return lines[-1][:MAX_DETAIL_CHARS]
+    # pip ends a failure with generic advice ("Consider using the --user option"),
+    # so keep the lines before it: they name the file or the reason.
+    return " | ".join(lines[-DETAIL_TAIL_LINES:])[:MAX_DETAIL_CHARS]
+
+
+def install_target() -> Path | None:
+    """@brief Locate the directory pip has to write to replace this package.
+    @return Package parent directory, or None when it cannot be determined.
+    """
+    module = getattr(dexverse_cli, "__file__", None)
+    if not module:
+        return None
+    return Path(module).resolve().parent.parent
+
+
+def writable_target() -> bool:
+    """@brief Prove pip can write there before it is allowed to touch anything.
+    @return True when a probe file could be created and removed.
+    """
+    target = install_target()
+    if target is None or not target.is_dir():
+        return False
+    try:
+        with tempfile.NamedTemporaryFile(dir=target, prefix=".dexverse-write-probe-", delete=True):
+            pass
+    except OSError:
+        return False
+    return True
 
 
 def run_upgrade(
@@ -188,6 +227,14 @@ def run_upgrade(
     with update_lock() as owned:
         if not owned:
             return UpgradeOutcome(STATUS_BUSY, version, "another dexverse-cli process is upgrading")
+        # A pip run that cannot finish still removes the old files first, which
+        # leaves a half-installed package behind. Refuse it up front instead.
+        if not writable_target():
+            return UpgradeOutcome(
+                STATUS_UNAVAILABLE,
+                version,
+                "installation directory is not writable; run `python -m pip install --user --upgrade dexverse-cli`",
+            )
         try:
             completed = (runner or run_pip)(upgrade_arguments(prerelease, source), UPGRADE_TIMEOUT_S)
         except subprocess.TimeoutExpired:
@@ -201,3 +248,103 @@ def run_upgrade(
     if installed_version() != version:
         return UpgradeOutcome(STATUS_FAILED, version, "installed version did not change")
     return UpgradeOutcome(STATUS_UPGRADED, version)
+
+
+def console_script_locked(platform: str | None = None, launched: str | None = None) -> bool:
+    """@brief Detect the Windows case where pip cannot replace the running launcher.
+    @param platform Optional platform name for deterministic tests.
+    @param launched Optional launched path for deterministic tests.
+    @return True when this process is its own environment's console script.
+    """
+    if (platform or os.name) != "nt":
+        return False
+    executable = Path(launched if launched is not None else (sys.argv[0] or "")).resolve()
+    if executable.suffix.lower() != ".exe":
+        return False
+    return executable.parent == (Path(sys.prefix) / "Scripts").resolve()
+
+
+def pending_path() -> Path:
+    """@brief Resolve the marker that fences a background upgrade.
+    @return Absolute marker path.
+    @throws ValueError When the configured state directory is not absolute.
+    """
+    return update_state_path().with_name(PENDING_NAME)
+
+
+def upgrade_pending() -> bool:
+    """@brief Tell whether a background upgrade is still expected to settle.
+    @return True while a fresh marker exists.
+    """
+    try:
+        path = pending_path()
+        return time.time() - path.stat().st_mtime < PENDING_TTL_S
+    except (OSError, ValueError):
+        return False
+
+
+def mark_pending(target: str) -> None:
+    """@brief Publish the marker before a background helper is started.
+    @param target Version the helper is expected to install.
+    @throws OSError When the marker cannot be written.
+    """
+    path = pending_path()
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    path.write_text(target, encoding="utf-8")
+
+
+def clear_pending() -> None:
+    """@brief Remove the marker once a background upgrade settled."""
+    with contextlib.suppress(OSError, ValueError):
+        pending_path().unlink(missing_ok=True)
+
+
+def start_detached(version: str, prerelease: bool, source: Sequence[str] | None = None) -> bool:
+    """@brief Start the helper outside this process so the launcher is released.
+    @param version Version the helper must install.
+    @param prerelease Whether pre-releases are allowed.
+    @param source Pip source arguments answered by the check.
+    @return True when the helper process was started.
+    """
+    command = [sys.executable, "-m", "dexverse_cli.update.helper", version, "1" if prerelease else "0"]
+    command += list(source or ())
+    flags = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0
+    try:
+        subprocess.Popen(
+            command,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            creationflags=flags,
+        )
+    except OSError:
+        return False
+    return True
+
+
+def retry_upgrade(
+    version: str,
+    prerelease: bool,
+    source: Sequence[str] | None = None,
+    runner: Runner | None = None,
+    attempts: int = RETRY_ATTEMPTS,
+    delay: float = RETRY_DELAY_S,
+) -> UpgradeOutcome:
+    """@brief Retry an upgrade that a still-exiting launcher blocked.
+    @param version Version to install.
+    @param prerelease Whether pre-releases are allowed.
+    @param source Pip source arguments answered by the check.
+    @param runner Optional process runner for deterministic tests.
+    @param attempts Maximum number of pip runs.
+    @param delay Seconds to wait between attempts.
+    @return The last outcome.
+    """
+    outcome = run_upgrade(version, prerelease, runner=runner, source=source)
+    for _ in range(max(attempts - 1, 0)):
+        if outcome.status == STATUS_UPGRADED:
+            return outcome
+        if not any(reason in outcome.detail.lower() for reason in LOCK_REASONS):
+            return outcome
+        time.sleep(delay)
+        outcome = run_upgrade(version, prerelease, runner=runner, source=source)
+    return outcome

dexverse_cli-0.1.4/src/dexverse_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.4"