misc.python.materialize.spawn

127class CalledProcessError(SubprocessError):
128    """Raised when run() is called with check=True and the process
129    returns a non-zero exit status.
130
131    Attributes:
132      cmd, returncode, stdout, stderr, output
133    """
134    def __init__(self, returncode, cmd, output=None, stderr=None):
135        self.returncode = returncode
136        self.cmd = cmd
137        self.output = output
138        self.stderr = stderr
139
140    def __str__(self):
141        if self.returncode and self.returncode < 0:
142            try:
143                return "Command '%s' died with %r." % (
144                        self.cmd, signal.Signals(-self.returncode))
145            except ValueError:
146                return "Command '%s' died with unknown signal %d." % (
147                        self.cmd, -self.returncode)
148        else:
149            return "Command '%s' returned non-zero exit status %d." % (
150                    self.cmd, self.returncode)
151
152    @property
153    def stdout(self):
154        """Alias for output attribute, to match stderr"""
155        return self.output
156
157    @stdout.setter
158    def stdout(self, value):
159        # There's no obvious reason to set this, but allow it anyway so
160        # .stdout is a transparent alias for .output
161        self.output = value

36def runv(
37    args: Sequence[Path | str],
38    *,
39    cwd: Path | None = None,
40    env: dict[str, str] | None = None,
41    stdin: None | int | IO[bytes] | bytes = None,
42    stdout: None | int | IO[bytes] = None,
43    stderr: None | int | IO[bytes] = None,
44) -> subprocess.CompletedProcess:
45    """Verbosely run a subprocess.
46
47    A description of the subprocess will be written to stdout before the
48    subprocess is executed.
49
50    Args:
51        args: A list of strings or paths describing the program to run and
52            the arguments to pass to it.
53        cwd: An optional directory to change into before executing the process.
54        env: A replacement environment with which to launch the process. If
55            unspecified, the current process's environment is used. Replacement
56            occurs wholesale, so use a construction like
57            `env=dict(os.environ, KEY=VAL, ...)` to instead amend the existing
58            environment.
59        stdin: An optional IO handle or byte string to use as the process's
60            stdin stream.
61        stdout: An optional IO handle to use as the process's stdout stream.
62        stderr: An optional IO handle to use as the process's stderr stream.
63
64    Raises:
65        OSError: The process cannot be executed, e.g. because the specified
66            program does not exist.
67        CalledProcessError: The process exited with a non-zero exit status.
68    """
69    print("$", ui.shell_quote(args), file=sys.stderr)
70
71    input = None
72    if isinstance(stdin, bytes):
73        input = stdin
74        stdin = None
75
76    return subprocess.run(
77        args,
78        cwd=cwd,
79        env=env,
80        input=input,
81        stdin=stdin,
82        stdout=stdout,
83        stderr=stderr,
84        check=True,
85    )

 88def capture(
 89    args: Sequence[Path | str],
 90    *,
 91    cwd: Path | None = None,
 92    env: dict[str, str] | None = None,
 93    stdin: None | int | IO[bytes] | str = None,
 94    stderr: None | int | IO[bytes] = None,
 95) -> str:
 96    """Capture the output of a subprocess.
 97
 98    Args:
 99        args: A list of strings or paths describing the program to run and
100            the arguments to pass to it.
101        cwd: An optional directory to change into before executing the process.
102        env: A replacement environment with which to launch the process. If
103            unspecified, the current process's environment is used. Replacement
104            occurs wholesale, so use a construction like
105            `env=dict(os.environ, KEY=VAL, ...)` to instead amend the existing
106            environment.
107        stdin: An optional IO handle, byte string or string to use as the process's
108            stdin stream.
109        stderr: An optional IO handle to use as the process's stderr stream.
110
111    Returns:
112        output: The verbatim output of the process as a string. Note that
113            trailing whitespace is preserved.
114
115    Raises:
116        OSError: The process cannot be executed, e.g. because the specified
117            program does not exist.
118        CalledProcessError: The process exited with a non-zero exit status.
119
120    .. tip:: Many programs produce output with a trailing newline.
121        You may want to call `strip()` on the output to remove any trailing
122        whitespace.
123    """
124    input = None
125    if isinstance(stdin, str):
126        input = stdin
127        stdin = None
128
129    return subprocess.check_output(
130        args, cwd=cwd, env=env, input=input, stdin=stdin, stderr=stderr, text=True
131    )

134def run_and_get_return_code(
135    args: Sequence[Path | str],
136    *,
137    cwd: Path | None = None,
138    env: dict[str, str] | None = None,
139) -> int:
140    """Run a subprocess and return the return code."""
141    try:
142        capture(args, cwd=cwd, env=env, stderr=subprocess.DEVNULL)
143        return 0
144    except CalledProcessError as e:
145        return e.returncode

151def run_with_retries(fn: Callable[[], T], max_duration: int = 60) -> T:
152    """Retry a function until it doesn't raise a `CalledProcessError`, uses
153    exponential backoff until `max_duration` is reached."""
154    for retry in range(math.ceil(math.log2(max_duration))):
155        try:
156            return fn()
157        except subprocess.CalledProcessError as e:
158            sleep_time = 2**retry
159            print(f"Failed: {e}, retrying in {sleep_time}s")
160            time.sleep(sleep_time)
161    return fn()