environment.py 31 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631
  1. """PM's private Python engine: tool routing, isolation and command execution.
  2. Operations own source, destination and publication. Bootstrap may inject its
  3. staged toolchain directly without recursing through the worker it is building.
  4. """
  5. from __future__ import annotations
  6. import codecs
  7. from collections.abc import Callable, Iterator, Mapping, Sequence
  8. from contextlib import contextmanager
  9. from dataclasses import dataclass, replace
  10. import io
  11. import os
  12. from pathlib import Path
  13. import shutil
  14. import subprocess
  15. import sys
  16. import tempfile
  17. import time
  18. from typing import TextIO
  19. from pm.filesystem import native
  20. from pm.package import InstallError
  21. from pm.progress import LiveTail, TextSink, verbose_output
  22. # Slow steps get a status line; unlisted quick ones (venv, export, pip check)
  23. # stay silent unless they fail.
  24. _UV_LABELS: dict[object, str] = {
  25. "sync": "Installing Python dependencies",
  26. "lock": "Resolving Python dependencies",
  27. ("pip", "install"): "Installing Python packages",
  28. "cache": "Pruning the uv cache",
  29. }
  30. # Deliberately narrow: a fetch timeout or index outage must not be misread as a
  31. # conflict — and regardless of classification, nothing here ever disables a
  32. # plugin; the caller decides. Lives here (stdlib-only imports) because the
  33. # bootstrap runner streams uv output from a pre-3.11 system python where
  34. # pm.workspace's tomllib import cannot load.
  35. _RESOLVER_MARKERS = (
  36. "no solution found",
  37. "conflicting requirements",
  38. "conflicting urls",
  39. "because only the following versions",
  40. "and your pyproject depends on",
  41. )
  42. # A package's own build ran and failed; a fetch/download failure never prints this.
  43. _BUILD_MARKERS = ("the build backend returned an error",)
  44. # The index omitted upload times (no PEP 700 metadata), so the release-age cutoff
  45. # cannot date the file. uv words it as "no solution", but the index is at fault,
  46. # not the requested set, so it must never read as a dependency conflict (#135589).
  47. # A seeded lock says "has no publish time"; a cold one only warns the date is missing
  48. # and hints the version was filtered, so that case needs both lines.
  49. _UNDATED_PIN = "has no publish time"
  50. _UNDATED_FILE = ("is missing an upload date", "was filtered by `exclude-newer")
  51. UNDATED_INDEX_HINT = ("the package index did not report upload times, which locking Hermes's "
  52. "dependencies needs for its 3-day release-age check. Use https://pypi.org/simple "
  53. "or a mirror that serves upload times (pip.conf index-url / UV_INDEX_URL), then retry.")
  54. # uv's own English diagnostic. A localized Windows tail (os error 1224) rides
  55. # along, but the marker that means "packages may be installed, only the
  56. # optional compile step failed" is this line. #124268
  57. _BYTECODE_COMPILE_MARKER = "failed to bytecode-compile"
  58. # Streamed uv output keeps only the last 2000 characters. Resolver markers are
  59. # stitched back if a later verbose flood evicts them; the bytecode marker has
  60. # to ride the same path or repair/bootstrap never sees the retry signal, and so
  61. # does the build marker: a failed native build's traceback runs far past 2000
  62. # characters, and without it the failure reads as a fetch error, not a verdict.
  63. _STREAM_TAIL_MARKERS = _RESOLVER_MARKERS + (_BYTECODE_COMPILE_MARKER, *_BUILD_MARKERS)
  64. # Retries after purging corrupt cached packages. Each round must name a package
  65. # not purged before, so this bounds a cache with several damaged entries, never
  66. # a loop on one broken wheel.
  67. _CACHE_RECOVERY_ROUNDS = 3
  68. class ResolutionConflict(InstallError):
  69. """uv's resolver proved the union has no valid solution."""
  70. class BuildFailure(InstallError):
  71. """A package's build backend ran and failed."""
  72. def _is_bytecode_compile_failure(result: subprocess.CompletedProcess) -> bool:
  73. """True when uv failed in the optional bytecode-compile step, not the install.
  74. ``--compile-bytecode`` exists so the first user-facing import does not pay
  75. compile cost (#100461). It is not required for a usable environment. Windows
  76. real-time AV can lock uv's temporary compile script (os error 1224) after
  77. the packages are already on disk (#124268).
  78. """
  79. if not result.returncode:
  80. return False
  81. text = f"{result.stderr or ''}\n{result.stdout or ''}".lower()
  82. return _BYTECODE_COMPILE_MARKER in text
  83. def classify_uv_failure(stage: str, returncode: int, output: str) -> InstallError:
  84. """Turn a failed `uv <stage>` into the right classified error.
  85. Resolver-conflict output → ResolutionConflict; a build backend that ran and
  86. failed → BuildFailure; anything else (fetch, tooling) → plain InstallError
  87. with the tail of the output.
  88. """
  89. cause = f"uv {stage} exited {returncode}: {output.strip()[-600:]}"
  90. lowered = output.lower()
  91. if _UNDATED_PIN in lowered or all(marker in lowered for marker in _UNDATED_FILE):
  92. return InstallError("venv", cause, UNDATED_INDEX_HINT)
  93. if any(marker in lowered for marker in _RESOLVER_MARKERS):
  94. return ResolutionConflict("venv", cause)
  95. if any(marker in lowered for marker in _BUILD_MARKERS):
  96. from pm.build_compilers import missing_compiler_remedy
  97. return BuildFailure("venv", cause, missing_compiler_remedy(output))
  98. return InstallError("venv", cause)
  99. def _project_name(source: Path) -> str:
  100. """``[project].name`` of *source*'s pyproject, on any Python that can run the bootstrap.
  101. tomllib is 3.11+; the bootstrap runner stages PM's runtime from a system python that may
  102. be older, so the one field this module reads is parsed with the stdlib parser when it
  103. exists and a table-scoped regex otherwise.
  104. """
  105. text = (source / "pyproject.toml").read_text(encoding="utf-8-sig")
  106. try:
  107. import tomllib
  108. except ModuleNotFoundError:
  109. import re
  110. table = re.search(r"(?ms)^\[project\]\s*$(.*?)(?=^\[)", text + "\n[")
  111. match = table and re.search(r'(?m)^name\s*=\s*"([^"]+)"', table.group(1))
  112. if not match:
  113. raise InstallError("venv", f"{source / 'pyproject.toml'} has no [project].name")
  114. return match.group(1)
  115. return tomllib.loads(text)["project"]["name"]
  116. def prune_site_pth(venv_dir: Path) -> None:
  117. """Drop .pth files that must never execute inside a shipped payload.
  118. ``uv sync`` leaves two behind: ``_virtualenv.pth`` (repoints
  119. ``sys.prefix`` at the venv) and the project's ``__editable__`` pointer
  120. (names the BUILD machine — the payload wires the repo snapshot itself,
  121. see scripts/build/launcher_wrapper.py). Bundled launchers process every
  122. other .pth with ``site.addsitedir()``; pywin32.pth is load-bearing on
  123. Windows (win32\\lib on sys.path is what makes ``import pywintypes``
  124. resolve, which portalocker/concurrent-log-handler need to write logs).
  125. """
  126. if (venv_dir / "Scripts").is_dir():
  127. sites = [venv_dir / "Lib" / "site-packages"]
  128. else:
  129. lib = venv_dir / "lib"
  130. sites = sorted(lib.glob("python*/site-packages")) if lib.is_dir() else []
  131. for site_dir in sites:
  132. if not site_dir.is_dir():
  133. continue
  134. for pth in site_dir.glob("*.pth"):
  135. if pth.name == "_virtualenv.pth" or pth.name.startswith("__editable__"):
  136. try:
  137. pth.unlink()
  138. except OSError:
  139. pass
  140. def _read_pipe(fd: int) -> bytes:
  141. size = 65536
  142. if sys.platform == "win32":
  143. import _winapi
  144. import msvcrt
  145. # Bootstrap can run on Python 3.11, before Windows os.set_blocking
  146. # exists. Peek keeps the sole reader bounded without changing pipe mode.
  147. try:
  148. available, _ = _winapi.PeekNamedPipe(msvcrt.get_osfhandle(fd), 0)
  149. except BrokenPipeError:
  150. return b""
  151. if not available:
  152. raise BlockingIOError
  153. size = min(size, available)
  154. return os.read(fd, size)
  155. def _run_streaming(command: list[str], *, cwd: Path, env: dict[str, str],
  156. timeout: int, output: TextSink) -> subprocess.CompletedProcess:
  157. """Keep CI progress live, a bounded diagnostic tail, and a wall-clock timeout."""
  158. deadline = time.monotonic() + timeout
  159. proc = subprocess.Popen(command, cwd=native(cwd), env=env, stdout=subprocess.PIPE,
  160. stderr=subprocess.STDOUT, text=True, encoding="utf-8", errors="replace", bufsize=0)
  161. pipe = proc.stdout
  162. assert isinstance(pipe, io.TextIOWrapper) # Popen was given stdout=PIPE and text=True.
  163. tail = ""
  164. conflict = ""
  165. try:
  166. # A descendant can keep stdout open after proc exits. Nonblocking reads
  167. # bound that drain without leaving a thread stuck in readline()/close().
  168. if sys.platform != "win32":
  169. os.set_blocking(pipe.fileno(), False)
  170. decoder = io.IncrementalNewlineDecoder(
  171. codecs.getincrementaldecoder(pipe.encoding)(errors="replace"), translate=True,
  172. )
  173. while True:
  174. remaining = deadline - time.monotonic()
  175. if remaining <= 0:
  176. raise subprocess.TimeoutExpired(command, timeout, stderr=tail)
  177. try:
  178. data = _read_pipe(pipe.fileno())
  179. except BlockingIOError:
  180. time.sleep(min(.05, remaining))
  181. continue
  182. text = decoder.decode(data, final=not data)
  183. if text:
  184. # Preserve an observed resolver marker even after verbose output
  185. # evicts it. Scan across read boundaries, never retain the full log.
  186. if not conflict:
  187. lowered = (tail + text).lower()
  188. conflict = next((marker for marker in _STREAM_TAIL_MARKERS if marker in lowered), "")
  189. tail = (tail + text)[-2000:]
  190. output.write(text)
  191. output.flush()
  192. if not data:
  193. break
  194. # EOF can precede process exit; it does not grant another timeout budget.
  195. try:
  196. code = proc.wait(timeout=max(0, deadline - time.monotonic()))
  197. except subprocess.TimeoutExpired:
  198. raise subprocess.TimeoutExpired(command, timeout, stderr=tail) from None
  199. except BaseException:
  200. proc.kill()
  201. proc.wait(timeout=5)
  202. raise
  203. finally:
  204. pipe.close()
  205. if conflict and conflict not in tail.lower():
  206. tail = conflict + "\n" + tail[-(2000 - len(conflict) - 1):]
  207. return subprocess.CompletedProcess(command, code, "", tail)
  208. def _base_environment(env: Mapping[str, str] | None = None) -> dict[str, str]:
  209. """Ambient UV settings never select the project, interpreter or cache.
  210. Index and transport settings are the exception (pm.index_config): without
  211. them mirrored and air-gapped networks cannot resolve anything.
  212. """
  213. from pm.index_config import bridged_index_settings, is_forwarded
  214. source = os.environ if env is None else env
  215. base = {key: value for key, value in source.items()
  216. if not key.startswith("PYTHON") and key != "VIRTUAL_ENV"
  217. and (not key.startswith("UV_") or is_forwarded(key))}
  218. if env is None:
  219. base.update(bridged_index_settings(os.environ))
  220. return base
  221. def managed_environment(destination: Path, *, python: Path | None = None,
  222. cache: Path | None = None, env: Mapping[str, str] | None = None,
  223. offline: bool = False, explicit: bool = False,
  224. output: TextIO | None = None, realize: bool = True) -> PythonEnvironment:
  225. from pm._uv import _toolchain
  226. from pm.packages import uv_cache_dir
  227. tools = _toolchain(explicit=explicit, realize=realize)
  228. if tools is None:
  229. raise InstallError("venv", "PM's pinned toolchain is unavailable")
  230. uv, pinned_python = tools
  231. python = pinned_python if python is None else python.absolute()
  232. build_env = _base_environment(env)
  233. if python.resolve() == pinned_python.resolve():
  234. # Only our interpreter: a separately selected one (e.g. Nix) keeps its own sysconfig.
  235. from pm.build_compilers import pinned_build_defaults
  236. for key, value in pinned_build_defaults(python, build_env).items():
  237. build_env.setdefault(key, value)
  238. return PythonEnvironment(
  239. uv=uv, python=python,
  240. destination=destination.absolute(), cache=uv_cache_dir() if cache is None else cache.absolute(),
  241. env=build_env, offline=offline, output=output,
  242. )
  243. @contextmanager
  244. def _fresh_build(environment: PythonEnvironment, *, sealed: bool, lock: Path | None = None) -> Iterator[None]:
  245. """Own only the output claimed by this build, including failed validation."""
  246. out = environment.destination
  247. # A concurrent creator wins intact: never enter cleanup before mkdir succeeds.
  248. out.mkdir(parents=True)
  249. try:
  250. environment.create()
  251. yield
  252. environment.check(lock)
  253. if sealed:
  254. prune_site_pth(out)
  255. except BaseException:
  256. shutil.rmtree(out, ignore_errors=True)
  257. raise
  258. @dataclass(frozen=True, kw_only=True)
  259. class PythonEnvironment:
  260. uv: Path
  261. python: Path
  262. destination: Path
  263. cache: Path
  264. env: Mapping[str, str]
  265. offline: bool = False
  266. output: TextIO | None = None
  267. no_config: bool = False
  268. @property
  269. def executable(self) -> Path:
  270. from pm.environments import venv_python
  271. return venv_python(self.destination)
  272. def _run(self, args: list[str], *, cwd: Path, timeout: int) -> subprocess.CompletedProcess:
  273. # Explicit index credentials survive, but cannot redirect the project,
  274. # interpreter or cache selected by the operation.
  275. env = _base_environment(self.env)
  276. if self.no_config:
  277. # --no-config only removes config files; the pip-mirror bridge
  278. # (pm.index_config) reaches uv as env vars. The pinned runtime
  279. # builder asked to be isolated from ambient index configuration:
  280. # re-resolving its official-index lockfile against a mirror trips
  281. # `--locked` (#124418), and a fully-pinned graph never needs a
  282. # mirror to resolve. Index-REDIRECT settings are dropped; transport
  283. # knobs (UV_NATIVE_TLS / UV_INSECURE_HOST / UV_HTTP_TIMEOUT) survive
  284. # — corporate networks need them to reach the pinned URLs at all.
  285. from pm.index_config import is_index_redirect
  286. env = {key: value for key, value in env.items() if not is_index_redirect(key)}
  287. # uv is a child: it gets the ordinary spelling of store paths (pm.filesystem.native),
  288. # or the venv it writes would record the extended-length one in pyvenv.cfg.
  289. env.update(UV_PYTHON=native(self.python), UV_PROJECT_ENVIRONMENT=native(self.destination),
  290. UV_CACHE_DIR=native(self.cache), UV_PYTHON_DOWNLOADS="never")
  291. # CMake 4 removed compatibility with cmake_minimum_required(VERSION < 3.5),
  292. # so an sdist carrying an old minimum dies at CONFIGURE time: python-olm
  293. # (mautrix[encryption], the matrix extra) vendors libolm declaring 3.4.
  294. # Every source build uv drives inherits this env; older CMake ignores
  295. # the variable, and a value the caller or user already set wins.
  296. env.setdefault("CMAKE_POLICY_VERSION_MINIMUM", "3.5")
  297. with tempfile.TemporaryDirectory(prefix="pm-uv-config-") as config:
  298. env.update(XDG_CONFIG_HOME=config, XDG_CONFIG_DIRS=config)
  299. command = [native(self.uv), *map(native, args)]
  300. if self.no_config and "--no-config" not in command:
  301. command.append("--no-config")
  302. if self.offline:
  303. command.append("--offline")
  304. try:
  305. if self.output is not None and verbose_output():
  306. # uv hides build-backend output until failure without verbose mode,
  307. # but --verbose alone is uv's DEBUG level: ~200 lines of interpreter
  308. # and cache internals on every streamed run. RUST_LOG scopes it to the
  309. # build frontend, so only the backend's own lines reach the user.
  310. command.append("--verbose")
  311. env.setdefault("RUST_LOG", "uv_build_frontend=debug")
  312. return _run_streaming(command, cwd=cwd, env=env, timeout=timeout, output=self.output)
  313. if self.output is not None:
  314. # uv prints backend output on failure anyway; interactive users see
  315. # one live status line and the captured tail only if it fails.
  316. tail = LiveTail(_UV_LABELS.get(tuple(args[:2]), _UV_LABELS.get(args[0])),
  317. self.output, indent=" ")
  318. try:
  319. result = _run_streaming(command, cwd=cwd, env=env, timeout=timeout, output=tail)
  320. except BaseException:
  321. tail.close(False)
  322. raise
  323. if "--compile-bytecode" in args and _is_bytecode_compile_failure(result):
  324. # Caller retries without the flag. A failure banner here
  325. # would report a recovered install as failed.
  326. tail.discard()
  327. else:
  328. tail.close(result.returncode == 0)
  329. return result
  330. return subprocess.run(command, cwd=native(cwd), env=env, capture_output=True,
  331. text=True, encoding="utf-8", errors="replace", timeout=timeout, check=False)
  332. except subprocess.TimeoutExpired as exc:
  333. from pm.index_config import TIMEOUT_HINT
  334. # A silent stall against an unreachable index is the #95608 shape;
  335. # name the mirror knobs instead of surfacing a raw TimeoutExpired.
  336. raise InstallError("venv", f"uv {args[0]} timed out after {timeout}s", TIMEOUT_HINT) from exc
  337. def create(self) -> None:
  338. """Create at the final destination; callers must not move a live venv."""
  339. self.destination.parent.mkdir(parents=True, exist_ok=True)
  340. result = self._run(
  341. ["venv", "--relocatable", "--no-project", "--no-config",
  342. "--python", str(self.python), str(self.destination)],
  343. cwd=self.destination.parent, timeout=120,
  344. )
  345. if result.returncode:
  346. raise InstallError("venv", f"uv venv failed: {result.stderr[-600:]}")
  347. def lock(self, source: Path, *, upgrade: bool = False, timeout: int = 1800) -> None:
  348. command = ["lock", "--python", str(self.python)]
  349. if upgrade:
  350. command.append("--upgrade")
  351. result = self._run(command, cwd=source, timeout=timeout)
  352. if result.returncode:
  353. raise classify_uv_failure("lock", result.returncode, result.stderr or result.stdout)
  354. def check_lock(self, source: Path) -> None:
  355. result = self._run(["lock", "--check", "--python", str(self.python)],
  356. cwd=source, timeout=1800)
  357. if result.returncode:
  358. raise classify_uv_failure("lock", result.returncode, result.stderr or result.stdout)
  359. def sync(self, source: Path, *, extras: Sequence[str] = (), groups: Sequence[str] = (),
  360. timeout: int = 1800, frozen: bool = True, all_extras: bool = False,
  361. no_install_project: bool = False, locked: bool = False,
  362. no_default_groups: bool = False) -> None:
  363. """Install the root and every member; resolve only in a writable workspace.
  364. ``frozen=False`` is reserved for the caller-owned generated workspace,
  365. never the original project's lock. Seed/replay policy belongs to PM.
  366. """
  367. if not frozen:
  368. self.lock(source, timeout=timeout)
  369. # Locking members alone is insufficient: plain sync only installs root deps.
  370. # uv writes no __pycache__ (pip does): without --compile-bytecode the first import
  371. # of every module in the foreground of a user request compiles it (#100461).
  372. command = ["sync", "--locked" if locked else "--frozen", "--all-packages",
  373. "--python", str(self.python), "--compile-bytecode"]
  374. if no_default_groups:
  375. command.append("--no-default-groups")
  376. if all_extras:
  377. from pm.features import opt_in_extras
  378. command.append("--all-extras")
  379. for extra in opt_in_extras(source):
  380. command += ["--no-extra", extra]
  381. if no_install_project:
  382. # --all-packages has no single selected project in uv, so
  383. # --no-install-project alone does not exclude the root. Name it
  384. # explicitly without dropping member dependencies or installations.
  385. command += ["--no-install-project", "--no-install-package", _project_name(source)]
  386. for extra in sorted(set(extras)):
  387. command += ["--extra", extra]
  388. for group in sorted(set(groups)):
  389. command += ["--group", group]
  390. result = self._with_cache_recovery(
  391. "sync", lambda: self._sync_attempt(command, cwd=source, timeout=timeout))
  392. if result.returncode:
  393. raise classify_uv_failure("sync", result.returncode, result.stderr or result.stdout)
  394. def _sync_attempt(self, command: list[str], *, cwd: Path, timeout: int) -> subprocess.CompletedProcess:
  395. result = self._run(command, cwd=cwd, timeout=timeout)
  396. if _is_bytecode_compile_failure(result):
  397. # Compile is an optimization. Retry once without the flag so a
  398. # locked temp script cannot fail pm repair/bootstrap. Imports
  399. # compile lazily on first use.
  400. if self.output is not None:
  401. self.output.write(
  402. "Bytecode compile failed; retrying the install without it. "
  403. "Modules will compile on first import.\n"
  404. )
  405. fallback = [arg for arg in command if arg != "--compile-bytecode"]
  406. result = self._run(fallback, cwd=cwd, timeout=timeout)
  407. return result
  408. def _with_cache_recovery(self, stage: str, attempt: Callable[[], subprocess.CompletedProcess],
  409. ) -> subprocess.CompletedProcess:
  410. """Run *attempt*; if a corrupt cached package failed it, purge it and retry.
  411. An install interrupted by a machine stop can leave a cache entry whose
  412. files are NUL bytes, and uv reuses it on every sync, so a plain retry
  413. never helps. Only uv's install-step corruption shapes trigger this
  414. (pm.uv_cache_health); every other failure returns untouched for the
  415. caller to classify. Each purge also takes every entry that fails the
  416. same validation, so one retry normally covers several damaged packages.
  417. uv stops at the first broken entry, though, and a dangling pointer is
  418. invisible to the scan, so a retry that trips over a DIFFERENT package
  419. purges that one too. A package that fails again after its purge ends
  420. the loop: the source itself is serving a broken wheel.
  421. """
  422. from pm.uv_cache_health import corrupt_cached_packages, failed_cached_packages
  423. purged: set[str] = set()
  424. result = attempt()
  425. for _ in range(_CACHE_RECOVERY_ROUNDS):
  426. if not result.returncode:
  427. return result
  428. failed = failed_cached_packages(f"{result.stderr or ''}\n{result.stdout or ''}")
  429. if not failed or failed <= purged:
  430. break
  431. names = sorted((failed | corrupt_cached_packages(self.cache)) - purged)
  432. if self.output is not None:
  433. self.output.write(f"The cached copy of {', '.join(names)} is corrupt; "
  434. "removing it from the uv cache and retrying the install.\n")
  435. try:
  436. self.purge_cached_packages(names)
  437. except InstallError as exc:
  438. # Keep the install failure that started this; the clean error alone hides it.
  439. original = f"{result.stderr or ''}\n{result.stdout or ''}".strip()[-600:]
  440. raise InstallError(exc.package, f"{exc.cause}; uv {stage} had failed with: {original}",
  441. exc.remedy) from exc
  442. purged.update(names)
  443. result = attempt()
  444. if not result.returncode or not purged:
  445. return result
  446. text = f"{result.stderr or ''}\n{result.stdout or ''}"
  447. cache = native(self.cache)
  448. still = failed_cached_packages(text)
  449. if still:
  450. remedy = ("the package source is serving a broken wheel; retry later or pin another version"
  451. if still <= purged else "run `hermes pm doctor --repair`, then retry")
  452. raise InstallError(
  453. "venv",
  454. f"uv {stage} exited {result.returncode}: the cached copy of {', '.join(sorted(still))} is "
  455. f"still invalid after removing {', '.join(sorted(purged))} from the uv cache at {cache}: "
  456. f"{text.strip()[-600:]}",
  457. remedy,
  458. )
  459. if self.offline:
  460. raise InstallError(
  461. "venv",
  462. f"uv {stage} exited {result.returncode}: removed the corrupt cached copy of "
  463. f"{', '.join(sorted(purged))} from {cache}, and offline mode cannot fetch it again: "
  464. f"{text.strip()[-600:]}",
  465. "retry with network access",
  466. )
  467. return result
  468. def purge_cached_packages(self, names: Sequence[str]) -> None:
  469. """Remove *names* from the uv cache.
  470. ``uv cache clean`` waits for other uv processes holding the cache, so
  471. another profile's sync never loses files it is reading. Archives it
  472. leaves behind that still fail validation are then deleted
  473. (pm.uv_cache_health.remove_corrupt_entries).
  474. """
  475. from pm.uv_cache_health import remove_corrupt_entries
  476. cache = native(self.cache)
  477. try:
  478. result = replace(self, output=None)._run(["cache", "clean", *names],
  479. cwd=self.cache.parent, timeout=900)
  480. except InstallError as exc:
  481. raise InstallError("uv", f"could not clean the uv cache at {cache}: {exc.cause}",
  482. "stop other Hermes installs and retry") from exc
  483. if result.returncode:
  484. raise InstallError("uv", f"could not remove {', '.join(names)} from the uv cache at "
  485. f"{cache}: {(result.stderr or result.stdout)[-600:]}")
  486. remove_corrupt_entries(self.cache, set(names))
  487. def export_requirements(self, source: Path, out: Path, *, extras: Sequence[str] = (),
  488. timeout: int = 1800) -> None:
  489. command = ["export", "--frozen", "--python", str(self.python), "--no-default-groups",
  490. "--no-emit-project", "--no-hashes", "--no-annotate", "--no-header",
  491. "--format", "requirements-txt", "--output-file", str(out)]
  492. for extra in sorted(set(extras)):
  493. command += ["--extra", extra]
  494. result = self._run(command, cwd=source, timeout=timeout)
  495. if result.returncode:
  496. raise classify_uv_failure("export", result.returncode, result.stderr or result.stdout)
  497. def install_requirements(self, requirements: Sequence[str], *, wheelhouse: Path | None = None,
  498. lock: Path | None = None) -> None:
  499. if not requirements:
  500. return
  501. # A file avoids command-line length limits and shell/marker quoting.
  502. with tempfile.TemporaryDirectory(prefix="pm-requirements-") as temporary:
  503. requirements_file = Path(temporary) / "requirements.txt"
  504. requirements_file.write_text("\n".join(requirements) + "\n", encoding="utf-8")
  505. self._install_requirements_file(requirements_file, wheelhouse=wheelhouse, lock=lock)
  506. def _install_requirements_file(self, requirements: Path, *, wheelhouse: Path | None = None,
  507. lock: Path | None = None, timeout: int = 1800) -> None:
  508. """Install *requirements*; *lock* is the uv.lock they were exported from.
  509. `uv pip install` re-resolves the export, so the lock's manifest overrides
  510. must come back as `--overrides` or the graph the lock resolved is rejected.
  511. """
  512. command = ["pip", "install", "--no-config", "--python", str(self.executable),
  513. "--requirements", str(requirements)]
  514. if lock is not None:
  515. from pm.pip_check import override_requirements
  516. overrides = override_requirements(lock)
  517. if overrides:
  518. overrides_file = requirements.with_name("overrides.txt")
  519. overrides_file.write_text("\n".join(overrides) + "\n", encoding="utf-8")
  520. command += ["--overrides", str(overrides_file)]
  521. if wheelhouse is not None:
  522. command += ["--no-index", "--only-binary", ":all:",
  523. "--find-links", str(wheelhouse.absolute())]
  524. result = self._with_cache_recovery(
  525. "pip", lambda: self._run(command, cwd=requirements.parent, timeout=timeout))
  526. if result.returncode:
  527. raise classify_uv_failure("pip", result.returncode, result.stderr or result.stdout)
  528. def install_wheelhouse(self, source: Path, wheelhouse: Path, *, timeout: int = 1800) -> None:
  529. """Install rebuilt wheels whose hashes the bundle manifest owns, not uv.lock."""
  530. requirements = source / "requirements.txt"
  531. self.export_requirements(source, requirements, timeout=timeout)
  532. self._install_requirements_file(requirements, wheelhouse=wheelhouse, lock=source / "uv.lock",
  533. timeout=timeout)
  534. self.check(source / "uv.lock")
  535. def prune_cache(self, *, ci: bool = False) -> None:
  536. command = ["cache", "prune", "--no-config"]
  537. if ci:
  538. command += ["--ci", "--force"]
  539. result = self._run(command, cwd=Path.cwd(), timeout=1800)
  540. if result.returncode:
  541. raise InstallError("uv", f"cache pruning failed: {result.stderr[-600:]}")
  542. def check(self, lock: Path | None = None) -> None:
  543. """`uv pip check` the environment; *lock* is the uv.lock it was installed from.
  544. Mismatches the lock's manifest overrides account for are expected (pm.pip_check).
  545. The check is a quiet step, so it runs captured even for a streaming environment:
  546. a streamed run keeps only the output's tail, which can drop the report's head.
  547. """
  548. result = replace(self, output=None)._run(
  549. # Forced colour (FORCE_COLOR/CLICOLOR_FORCE) would wrap the report in ANSI pm.pip_check cannot read.
  550. ["pip", "check", "--no-config", "--color", "never", "--python", str(self.executable)],
  551. cwd=self.destination.parent, timeout=60,
  552. )
  553. if not result.returncode:
  554. return
  555. from pm.pip_check import unexpected_incompatibilities
  556. unexpected = unexpected_incompatibilities(f"{result.stdout or ''}\n{result.stderr or ''}", lock)
  557. if unexpected is None:
  558. raise InstallError("venv", f"dependency validation failed: {result.stderr[-600:]}")
  559. if unexpected:
  560. raise InstallError("venv", "dependency validation failed: " + "\n".join(unexpected)[-600:])