progress.py 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186
  1. """One output policy for long child processes: verbose in CI, contained elsewhere.
  2. CI logs are the only record of a remote failure, so CI (``CI`` /
  3. ``GITHUB_ACTIONS``) or ``HERMES_VERBOSE=1`` streams child output unchanged.
  4. Everywhere else a child collapses into one status line: on a terminal it is
  5. rewritten in place with the child's latest line, off a terminal only the
  6. start and finish are printed. A failure always prints the captured tail, so
  7. containment never hides an error. ``HERMES_VERBOSE=0`` forces containment.
  8. Stdlib-only: the bootstrap runner imports this from a pre-3.11 system Python.
  9. """
  10. from __future__ import annotations
  11. from collections import deque
  12. import os
  13. import re
  14. import shutil
  15. import subprocess
  16. import sys
  17. import time
  18. from typing import IO, Callable, Mapping, Optional, Protocol, Sequence
  19. TAIL_LINES = 80
  20. # A child that never prints a newline (a bare progress stream, a binary blob) must not
  21. # grow memory without bound; the end of an over-long line is the informative part.
  22. MAX_LINE = 4096
  23. _TRUE = {"1", "true", "yes", "on"}
  24. _FALSE = {"0", "false", "no", "off"}
  25. _ANSI = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
  26. # A redraw per child line would dominate a fast install's runtime on slow terminals.
  27. _REDRAW_INTERVAL = 0.05
  28. class TextSink(Protocol):
  29. def write(self, text: str, /) -> int: ...
  30. def flush(self) -> None: ...
  31. def verbose_output(env: Optional[Mapping[str, str]] = None) -> bool:
  32. """Whether child output streams unchanged instead of being contained."""
  33. source = os.environ if env is None else env
  34. explicit = source.get("HERMES_VERBOSE", "").strip().lower()
  35. if explicit in _TRUE:
  36. return True
  37. if explicit in _FALSE:
  38. return False
  39. return any(source.get(key, "").strip().lower() not in ("", *_FALSE) for key in ("CI", "GITHUB_ACTIONS"))
  40. def _is_terminal(stream: IO[str]) -> bool:
  41. try:
  42. return stream.isatty()
  43. except (AttributeError, ValueError):
  44. return False
  45. class LiveTail:
  46. """A text sink that contains a child's output behind one status line.
  47. ``label=None`` runs silently and speaks only on failure, for steps too
  48. quick to deserve a line of their own.
  49. """
  50. def __init__(self, label: Optional[str], stream: Optional[IO[str]] = None, *,
  51. hide: Optional[Callable[[str], bool]] = None, indent: str = "") -> None:
  52. self.label = label
  53. self.stream = sys.stdout if stream is None else stream
  54. self.hide = hide
  55. self.indent = indent
  56. self.live = label is not None and _is_terminal(self.stream)
  57. self.tail: deque[str] = deque(maxlen=TAIL_LINES)
  58. self._partial = ""
  59. self._drawn = 0
  60. self._last_draw = 0.0
  61. if label is not None:
  62. if self.live:
  63. self._draw(f"{indent}→ {label}…")
  64. else:
  65. self._emit(f"{indent}→ {label}…\n")
  66. def write(self, text: str) -> int:
  67. # npm and uv redraw with bare CRs; each redraw is a line of progress.
  68. lines = (self._partial + text).replace("\r\n", "\n").replace("\r", "\n").split("\n")
  69. self._partial = lines.pop()[-MAX_LINE:]
  70. for line in lines:
  71. self._line(line)
  72. return len(text)
  73. def flush(self) -> None:
  74. return None
  75. def discard(self) -> None:
  76. """Clear the status line without a success or failure verdict.
  77. Used when a bytecode-compile failure will be retried. Closing as a
  78. failure here would report a recovered install as failed.
  79. """
  80. if self._partial:
  81. self._line(self._partial)
  82. self._partial = ""
  83. if self.live:
  84. self._draw("")
  85. self._emit("\r")
  86. def close(self, ok: bool) -> None:
  87. if self._partial:
  88. self._line(self._partial)
  89. self._partial = ""
  90. if self.live:
  91. self._draw("")
  92. self._emit("\r")
  93. if ok:
  94. if self.label is not None:
  95. self._emit(f"{self.indent}✓ {self.label}\n")
  96. return
  97. name = self.label or "command"
  98. if not self.tail:
  99. self._emit(f"{self.indent}✗ {name} failed\n")
  100. return
  101. self._emit(f"{self.indent}✗ {name} failed; last {len(self.tail)} lines of output:\n")
  102. self._emit("".join(f"{self.indent} {line}\n" for line in self.tail))
  103. def _line(self, line: str) -> None:
  104. line = _ANSI.sub("", line[-MAX_LINE:]).rstrip()
  105. if not line.strip():
  106. return
  107. self.tail.append(line)
  108. if not self.live or (self.hide is not None and self.hide(line)):
  109. return
  110. now = time.monotonic()
  111. if now - self._last_draw < _REDRAW_INTERVAL:
  112. return
  113. self._last_draw = now
  114. self._draw(f"{self.indent}→ {self.label}… {line.strip()}")
  115. def _draw(self, text: str) -> None:
  116. # Pad instead of an ANSI erase: a bare CR works on every Windows console.
  117. width = max(20, shutil.get_terminal_size().columns - 1)
  118. text = text[:width]
  119. self._emit("\r" + text + " " * max(0, self._drawn - len(text)))
  120. self._drawn = len(text)
  121. def _emit(self, text: str) -> None:
  122. self.stream.write(text)
  123. self.stream.flush()
  124. def run_contained(command: Sequence[str], label: str, *, stream: Optional[IO[str]] = None,
  125. hide: Optional[Callable[[str], bool]] = None, indent: str = "",
  126. **kwargs) -> subprocess.CompletedProcess:
  127. """``subprocess.run(check=True)`` under the output policy."""
  128. if verbose_output():
  129. out = sys.stdout if stream is None else stream
  130. out.write(f"{indent}→ {label}…\n")
  131. out.flush()
  132. return subprocess.run(command, check=True, **kwargs)
  133. tail = LiveTail(label, stream, hide=hide, indent=indent)
  134. captured = dict(stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
  135. encoding="utf-8", errors="replace")
  136. if not tail.live:
  137. try:
  138. result = subprocess.run(command, check=True, **captured, **kwargs)
  139. except subprocess.CalledProcessError as exc:
  140. tail.write(exc.output or "")
  141. tail.close(False)
  142. raise
  143. except BaseException:
  144. tail.close(False)
  145. raise
  146. tail.close(True)
  147. return result
  148. try:
  149. with subprocess.Popen(command, **captured, **kwargs) as proc:
  150. assert proc.stdout is not None # stdout=PIPE above.
  151. for line in proc.stdout:
  152. tail.write(line)
  153. code = proc.wait()
  154. except BaseException:
  155. tail.close(False)
  156. raise
  157. tail.close(code == 0)
  158. output = "\n".join(tail.tail)
  159. if code:
  160. raise subprocess.CalledProcessError(code, list(command), output=output)
  161. return subprocess.CompletedProcess(list(command), code, output, None)