uppercut-subprocess-runner 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- uppercut_subprocess_runner/__init__.py +15 -0
- uppercut_subprocess_runner/_kill.py +184 -0
- uppercut_subprocess_runner/_runner.py +304 -0
- uppercut_subprocess_runner/py.typed +0 -0
- uppercut_subprocess_runner-0.1.0.dist-info/METADATA +107 -0
- uppercut_subprocess_runner-0.1.0.dist-info/RECORD +7 -0
- uppercut_subprocess_runner-0.1.0.dist-info/WHEEL +4 -0
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"""Run a subprocess with a timeout, an output cap and cancellation, and kill its whole process tree."""
|
|
2
|
+
|
|
3
|
+
from ._kill import KillInfo, kill_tree, popen_group, popen_group_kwargs
|
|
4
|
+
from ._runner import CommandError, RunResult, run
|
|
5
|
+
|
|
6
|
+
__all__ = [
|
|
7
|
+
"CommandError",
|
|
8
|
+
"KillInfo",
|
|
9
|
+
"RunResult",
|
|
10
|
+
"kill_tree",
|
|
11
|
+
"popen_group",
|
|
12
|
+
"popen_group_kwargs",
|
|
13
|
+
"run",
|
|
14
|
+
]
|
|
15
|
+
__version__ = "0.1.0"
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
"""Kill a process together with everything it started."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import signal
|
|
7
|
+
import subprocess
|
|
8
|
+
import time
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from typing import Any, Union
|
|
11
|
+
|
|
12
|
+
IS_WINDOWS = os.name == "nt"
|
|
13
|
+
|
|
14
|
+
_POLL = 0.02
|
|
15
|
+
|
|
16
|
+
Target = Union["subprocess.Popen[Any]", int]
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass(frozen=True)
|
|
20
|
+
class KillInfo:
|
|
21
|
+
"""What `kill_tree` did.
|
|
22
|
+
|
|
23
|
+
method: "killpg" (POSIX process group), "taskkill" (Windows), "terminate" (leader only) or "none" when
|
|
24
|
+
nothing was left to kill.
|
|
25
|
+
already_exited: the tree was already gone when the call started.
|
|
26
|
+
graceful: the soft signal was enough and no forced kill was needed.
|
|
27
|
+
forced: SIGKILL (POSIX) or taskkill /F (Windows) was used.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
method: str
|
|
31
|
+
already_exited: bool = False
|
|
32
|
+
graceful: bool = False
|
|
33
|
+
forced: bool = False
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def popen_group_kwargs(*, no_window: bool = False) -> dict[str, Any]:
|
|
37
|
+
"""Popen keyword arguments that put the child in its own session or process group.
|
|
38
|
+
|
|
39
|
+
A child started this way can be killed together with its descendants by `kill_tree`.
|
|
40
|
+
`no_window` adds CREATE_NO_WINDOW on Windows and is ignored elsewhere.
|
|
41
|
+
"""
|
|
42
|
+
if IS_WINDOWS:
|
|
43
|
+
flags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
|
|
44
|
+
if no_window:
|
|
45
|
+
flags |= getattr(subprocess, "CREATE_NO_WINDOW", 0)
|
|
46
|
+
return {"creationflags": flags}
|
|
47
|
+
return {"start_new_session": True}
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def popen_group(argv: Any, *, no_window: bool = False, **kwargs: Any) -> "subprocess.Popen[Any]":
|
|
51
|
+
"""`subprocess.Popen` with `popen_group_kwargs` applied."""
|
|
52
|
+
kwargs.update(popen_group_kwargs(no_window=no_window))
|
|
53
|
+
return subprocess.Popen(argv, **kwargs) # noqa: S603
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def kill_tree(target: Target, *, grace: float = 5.0) -> KillInfo:
|
|
57
|
+
"""Stop a process and all of its descendants.
|
|
58
|
+
|
|
59
|
+
POSIX: sends SIGTERM to the process group, waits up to `grace` seconds for the group to empty, then sends
|
|
60
|
+
SIGKILL. The target must lead its own group (start it with `popen_group` or `start_new_session=True`).
|
|
61
|
+
The calling process's own group is never signalled; a target in it raises ValueError.
|
|
62
|
+
|
|
63
|
+
Windows: sends CTRL_BREAK_EVENT to a `Popen` started in a new process group, waits up to `grace` seconds,
|
|
64
|
+
then runs `taskkill /F /T`. Descendants of a leader that exited during the grace period are not reached.
|
|
65
|
+
|
|
66
|
+
A `Popen` target is reaped. An integer pid is only signalled. `grace=0` skips the soft step.
|
|
67
|
+
"""
|
|
68
|
+
if grace < 0:
|
|
69
|
+
raise ValueError("grace must be zero or positive")
|
|
70
|
+
if IS_WINDOWS:
|
|
71
|
+
return _kill_windows(target, grace)
|
|
72
|
+
return _kill_posix(target, grace)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _pid_of(target: Target) -> "tuple[int, subprocess.Popen[Any] | None]":
|
|
76
|
+
if isinstance(target, subprocess.Popen):
|
|
77
|
+
return target.pid, target
|
|
78
|
+
return int(target), None
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _group_exists(pgid: int) -> bool:
|
|
82
|
+
try:
|
|
83
|
+
os.killpg(pgid, 0)
|
|
84
|
+
except ProcessLookupError:
|
|
85
|
+
return False
|
|
86
|
+
except PermissionError:
|
|
87
|
+
# Members we cannot signal (or zombies on some systems): nothing more we can do.
|
|
88
|
+
return False
|
|
89
|
+
return True
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _signal_group(pgid: int, sig: int) -> None:
|
|
93
|
+
try:
|
|
94
|
+
os.killpg(pgid, sig)
|
|
95
|
+
except (ProcessLookupError, PermissionError):
|
|
96
|
+
pass
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def _reap(proc: "subprocess.Popen[Any]") -> None:
|
|
100
|
+
try:
|
|
101
|
+
proc.wait(timeout=5)
|
|
102
|
+
except subprocess.TimeoutExpired:
|
|
103
|
+
pass
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def _kill_posix(target: Target, grace: float) -> KillInfo:
|
|
107
|
+
pid, proc = _pid_of(target)
|
|
108
|
+
try:
|
|
109
|
+
pgid = os.getpgid(pid)
|
|
110
|
+
except ProcessLookupError:
|
|
111
|
+
# The leader is already gone; its group id stays the same while any member lives.
|
|
112
|
+
pgid = pid
|
|
113
|
+
if pgid == os.getpgrp():
|
|
114
|
+
raise ValueError(
|
|
115
|
+
"refusing to kill the calling process's own process group; start the child with popen_group()"
|
|
116
|
+
)
|
|
117
|
+
if proc is not None:
|
|
118
|
+
proc.poll()
|
|
119
|
+
if not _group_exists(pgid):
|
|
120
|
+
if proc is not None:
|
|
121
|
+
_reap(proc)
|
|
122
|
+
return KillInfo(method="none", already_exited=True)
|
|
123
|
+
|
|
124
|
+
if grace > 0:
|
|
125
|
+
_signal_group(pgid, signal.SIGTERM)
|
|
126
|
+
end = time.monotonic() + grace
|
|
127
|
+
while True:
|
|
128
|
+
if proc is not None:
|
|
129
|
+
proc.poll()
|
|
130
|
+
if not _group_exists(pgid):
|
|
131
|
+
if proc is not None:
|
|
132
|
+
_reap(proc)
|
|
133
|
+
return KillInfo(method="killpg", graceful=True)
|
|
134
|
+
if time.monotonic() >= end:
|
|
135
|
+
break
|
|
136
|
+
time.sleep(_POLL)
|
|
137
|
+
_signal_group(pgid, signal.SIGKILL)
|
|
138
|
+
if proc is not None:
|
|
139
|
+
_reap(proc)
|
|
140
|
+
end = time.monotonic() + 2.0
|
|
141
|
+
while _group_exists(pgid) and time.monotonic() < end:
|
|
142
|
+
time.sleep(_POLL)
|
|
143
|
+
return KillInfo(method="killpg", forced=True)
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def _taskkill(pid: int) -> bool:
|
|
147
|
+
flags = getattr(subprocess, "CREATE_NO_WINDOW", 0)
|
|
148
|
+
try:
|
|
149
|
+
done = subprocess.run( # noqa: S603
|
|
150
|
+
["taskkill", "/F", "/T", "/PID", str(pid)],
|
|
151
|
+
stdin=subprocess.DEVNULL,
|
|
152
|
+
stdout=subprocess.DEVNULL,
|
|
153
|
+
stderr=subprocess.DEVNULL,
|
|
154
|
+
timeout=15,
|
|
155
|
+
creationflags=flags,
|
|
156
|
+
)
|
|
157
|
+
except (OSError, subprocess.SubprocessError):
|
|
158
|
+
return False
|
|
159
|
+
return done.returncode == 0
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _kill_windows(target: Target, grace: float) -> KillInfo:
|
|
163
|
+
pid, proc = _pid_of(target)
|
|
164
|
+
if proc is not None and proc.poll() is not None:
|
|
165
|
+
return KillInfo(method="none", already_exited=True)
|
|
166
|
+
if proc is not None and grace > 0:
|
|
167
|
+
try:
|
|
168
|
+
proc.send_signal(signal.CTRL_BREAK_EVENT) # type: ignore[attr-defined]
|
|
169
|
+
except (OSError, ValueError, AttributeError):
|
|
170
|
+
pass
|
|
171
|
+
try:
|
|
172
|
+
proc.wait(timeout=grace)
|
|
173
|
+
_taskkill(pid) # sweeps any descendants that are still reachable
|
|
174
|
+
return KillInfo(method="taskkill", graceful=True)
|
|
175
|
+
except subprocess.TimeoutExpired:
|
|
176
|
+
pass
|
|
177
|
+
if not _taskkill(pid) and proc is not None:
|
|
178
|
+
try:
|
|
179
|
+
proc.kill()
|
|
180
|
+
except OSError:
|
|
181
|
+
pass
|
|
182
|
+
if proc is not None:
|
|
183
|
+
_reap(proc)
|
|
184
|
+
return KillInfo(method="taskkill", forced=True)
|
|
@@ -0,0 +1,304 @@
|
|
|
1
|
+
"""Run one command with a timeout, an output cap and cancellation."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import subprocess
|
|
7
|
+
import threading
|
|
8
|
+
import time
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from typing import Any, Callable, Mapping, Sequence
|
|
11
|
+
|
|
12
|
+
from ._kill import KillInfo, kill_tree, popen_group_kwargs
|
|
13
|
+
|
|
14
|
+
OnOutput = Callable[[str, bytes], None]
|
|
15
|
+
|
|
16
|
+
_POLL = 0.02
|
|
17
|
+
_READ = 65536
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class CommandError(RuntimeError):
|
|
21
|
+
"""Raised by `run(check=True)` and `RunResult.check_returncode()`. The result is in `.result`."""
|
|
22
|
+
|
|
23
|
+
def __init__(self, message: str, result: "RunResult") -> None:
|
|
24
|
+
super().__init__(message)
|
|
25
|
+
self.result = result
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass(frozen=True)
|
|
29
|
+
class RunResult:
|
|
30
|
+
"""Outcome of `run`.
|
|
31
|
+
|
|
32
|
+
stop_reason is one of "exited", "timeout", "cancelled", "output-limit" or "spawn-failed".
|
|
33
|
+
stdout and stderr hold at most `max_output` bytes from the start of each stream. The tails hold the last
|
|
34
|
+
`tail_bytes` bytes of each stream, even when the stream was longer than `max_output`.
|
|
35
|
+
exit_code is None when the command never started; after a kill on POSIX it is the negative signal number.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
argv: tuple[str, ...]
|
|
39
|
+
exit_code: int | None
|
|
40
|
+
stop_reason: str
|
|
41
|
+
duration: float
|
|
42
|
+
stdout: bytes
|
|
43
|
+
stderr: bytes
|
|
44
|
+
stdout_tail: bytes
|
|
45
|
+
stderr_tail: bytes
|
|
46
|
+
truncated: bool
|
|
47
|
+
pid: int | None
|
|
48
|
+
kill: KillInfo | None = None
|
|
49
|
+
error: str | None = None
|
|
50
|
+
|
|
51
|
+
@property
|
|
52
|
+
def timed_out(self) -> bool:
|
|
53
|
+
return self.stop_reason == "timeout"
|
|
54
|
+
|
|
55
|
+
@property
|
|
56
|
+
def cancelled(self) -> bool:
|
|
57
|
+
return self.stop_reason == "cancelled"
|
|
58
|
+
|
|
59
|
+
@property
|
|
60
|
+
def ok(self) -> bool:
|
|
61
|
+
"""The command ran to the end by itself and exited with code 0."""
|
|
62
|
+
return self.stop_reason == "exited" and self.exit_code == 0
|
|
63
|
+
|
|
64
|
+
@property
|
|
65
|
+
def stdout_text(self) -> str:
|
|
66
|
+
return self.stdout.decode("utf-8", "replace")
|
|
67
|
+
|
|
68
|
+
@property
|
|
69
|
+
def stderr_text(self) -> str:
|
|
70
|
+
return self.stderr.decode("utf-8", "replace")
|
|
71
|
+
|
|
72
|
+
def error_tail(self, limit: int = 2000) -> str:
|
|
73
|
+
"""The last `limit` characters of stderr, or of stdout when stderr is empty."""
|
|
74
|
+
data = self.stderr_tail or self.stdout_tail
|
|
75
|
+
return data.decode("utf-8", "replace")[-limit:]
|
|
76
|
+
|
|
77
|
+
def check_returncode(self, *, tail: int = 2000) -> "RunResult":
|
|
78
|
+
"""Return self when `ok`, otherwise raise CommandError with the tail of the output."""
|
|
79
|
+
if self.ok:
|
|
80
|
+
return self
|
|
81
|
+
name = self.argv[0] if self.argv else "command"
|
|
82
|
+
if self.stop_reason == "exited":
|
|
83
|
+
what = "exited with code %s" % self.exit_code
|
|
84
|
+
elif self.stop_reason == "spawn-failed":
|
|
85
|
+
what = "could not start (%s)" % (self.error or "unknown error")
|
|
86
|
+
else:
|
|
87
|
+
what = "stopped: %s" % self.stop_reason
|
|
88
|
+
text = self.error_tail(tail).strip()
|
|
89
|
+
message = "%s %s" % (name, what) + (":\n" + text if text else "")
|
|
90
|
+
raise CommandError(message, self)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
class _Stream:
|
|
94
|
+
"""Reads one pipe on a thread, keeping the head up to a cap and a rolling tail."""
|
|
95
|
+
|
|
96
|
+
def __init__(
|
|
97
|
+
self,
|
|
98
|
+
name: str,
|
|
99
|
+
pipe: Any,
|
|
100
|
+
max_bytes: int | None,
|
|
101
|
+
tail_bytes: int,
|
|
102
|
+
stop_on_limit: bool,
|
|
103
|
+
limit_event: threading.Event,
|
|
104
|
+
on_output: OnOutput | None,
|
|
105
|
+
) -> None:
|
|
106
|
+
self.name = name
|
|
107
|
+
self.head = bytearray()
|
|
108
|
+
self.tail = bytearray()
|
|
109
|
+
self.truncated = False
|
|
110
|
+
self._pipe = pipe
|
|
111
|
+
self._max = max_bytes
|
|
112
|
+
self._tail_bytes = tail_bytes
|
|
113
|
+
self._stop_on_limit = stop_on_limit
|
|
114
|
+
self._limit_event = limit_event
|
|
115
|
+
self._on_output = on_output
|
|
116
|
+
self.thread = threading.Thread(target=self._pump, daemon=True)
|
|
117
|
+
self.thread.start()
|
|
118
|
+
|
|
119
|
+
def _pump(self) -> None:
|
|
120
|
+
try:
|
|
121
|
+
while True:
|
|
122
|
+
chunk = self._pipe.read(_READ)
|
|
123
|
+
if not chunk:
|
|
124
|
+
return
|
|
125
|
+
self._feed(chunk)
|
|
126
|
+
except (OSError, ValueError):
|
|
127
|
+
return
|
|
128
|
+
|
|
129
|
+
def _feed(self, chunk: bytes) -> None:
|
|
130
|
+
if self._max is None:
|
|
131
|
+
self.head += chunk
|
|
132
|
+
else:
|
|
133
|
+
room = self._max - len(self.head)
|
|
134
|
+
if room > 0:
|
|
135
|
+
self.head += chunk[:room]
|
|
136
|
+
if len(chunk) > max(room, 0):
|
|
137
|
+
self.truncated = True
|
|
138
|
+
if self._stop_on_limit:
|
|
139
|
+
self._limit_event.set()
|
|
140
|
+
if self._tail_bytes > 0:
|
|
141
|
+
self.tail += chunk
|
|
142
|
+
if len(self.tail) > 2 * self._tail_bytes:
|
|
143
|
+
del self.tail[: -self._tail_bytes]
|
|
144
|
+
if self._on_output is not None:
|
|
145
|
+
try:
|
|
146
|
+
self._on_output(self.name, bytes(chunk))
|
|
147
|
+
except Exception: # a broken callback must not stop the capture
|
|
148
|
+
pass
|
|
149
|
+
|
|
150
|
+
def final_tail(self) -> bytes:
|
|
151
|
+
return bytes(self.tail[-self._tail_bytes :]) if self._tail_bytes > 0 else b""
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def _feed_stdin(pipe: Any, data: bytes) -> None:
|
|
155
|
+
try:
|
|
156
|
+
pipe.write(data)
|
|
157
|
+
except (OSError, ValueError):
|
|
158
|
+
pass
|
|
159
|
+
finally:
|
|
160
|
+
try:
|
|
161
|
+
pipe.close()
|
|
162
|
+
except (OSError, ValueError):
|
|
163
|
+
pass
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def _stop_leader_only(proc: "subprocess.Popen[Any]", grace: float) -> KillInfo:
|
|
167
|
+
if proc.poll() is not None:
|
|
168
|
+
return KillInfo(method="none", already_exited=True)
|
|
169
|
+
proc.terminate()
|
|
170
|
+
try:
|
|
171
|
+
proc.wait(timeout=grace)
|
|
172
|
+
return KillInfo(method="terminate", graceful=True)
|
|
173
|
+
except subprocess.TimeoutExpired:
|
|
174
|
+
proc.kill()
|
|
175
|
+
return KillInfo(method="terminate", forced=True)
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def run(
|
|
179
|
+
argv: "Sequence[str | os.PathLike[str]]",
|
|
180
|
+
*,
|
|
181
|
+
cwd: "str | os.PathLike[str] | None" = None,
|
|
182
|
+
env: Mapping[str, str] | None = None,
|
|
183
|
+
input: bytes | None = None,
|
|
184
|
+
timeout: float | None = None,
|
|
185
|
+
max_output: int | None = 10_000_000,
|
|
186
|
+
tail_bytes: int = 8192,
|
|
187
|
+
stop_on_output_limit: bool = True,
|
|
188
|
+
grace: float = 5.0,
|
|
189
|
+
cancel: threading.Event | None = None,
|
|
190
|
+
on_output: OnOutput | None = None,
|
|
191
|
+
kill_process_tree: bool = True,
|
|
192
|
+
drain_timeout: float = 1.0,
|
|
193
|
+
no_window: bool = False,
|
|
194
|
+
check: bool = False,
|
|
195
|
+
) -> RunResult:
|
|
196
|
+
"""Run `argv` (no shell) and return a `RunResult`. Never raises for a failing command unless `check` is set.
|
|
197
|
+
|
|
198
|
+
The child starts in its own session (POSIX) or process group (Windows). It is stopped, together with its
|
|
199
|
+
descendants, when `timeout` seconds pass, when `cancel` is set, or when one output stream exceeds
|
|
200
|
+
`max_output` bytes (unless `stop_on_output_limit` is False, which keeps draining and discards the excess).
|
|
201
|
+
Stopping sends a soft signal, waits `grace` seconds, then forces the kill.
|
|
202
|
+
|
|
203
|
+
stdin is closed unless `input` is given. If the command exits but a descendant keeps its pipes open, the
|
|
204
|
+
tree is killed after `drain_timeout` seconds so the call returns.
|
|
205
|
+
"""
|
|
206
|
+
args = tuple(os.fspath(a) for a in argv)
|
|
207
|
+
if not args:
|
|
208
|
+
raise ValueError("argv must not be empty")
|
|
209
|
+
if timeout is not None and timeout <= 0:
|
|
210
|
+
raise ValueError("timeout must be positive")
|
|
211
|
+
if max_output is not None and max_output <= 0:
|
|
212
|
+
raise ValueError("max_output must be positive")
|
|
213
|
+
if tail_bytes < 0:
|
|
214
|
+
raise ValueError("tail_bytes must not be negative")
|
|
215
|
+
if grace < 0:
|
|
216
|
+
raise ValueError("grace must be zero or positive")
|
|
217
|
+
|
|
218
|
+
start = time.monotonic()
|
|
219
|
+
try:
|
|
220
|
+
proc = subprocess.Popen( # noqa: S603
|
|
221
|
+
list(args),
|
|
222
|
+
cwd=os.fspath(cwd) if cwd is not None else None,
|
|
223
|
+
env=dict(env) if env is not None else None,
|
|
224
|
+
stdin=subprocess.PIPE if input is not None else subprocess.DEVNULL,
|
|
225
|
+
stdout=subprocess.PIPE,
|
|
226
|
+
stderr=subprocess.PIPE,
|
|
227
|
+
bufsize=0,
|
|
228
|
+
shell=False,
|
|
229
|
+
**popen_group_kwargs(no_window=no_window),
|
|
230
|
+
)
|
|
231
|
+
except (OSError, ValueError) as exc:
|
|
232
|
+
failed = RunResult(
|
|
233
|
+
argv=args,
|
|
234
|
+
exit_code=None,
|
|
235
|
+
stop_reason="spawn-failed",
|
|
236
|
+
duration=time.monotonic() - start,
|
|
237
|
+
stdout=b"",
|
|
238
|
+
stderr=b"",
|
|
239
|
+
stdout_tail=b"",
|
|
240
|
+
stderr_tail=b"",
|
|
241
|
+
truncated=False,
|
|
242
|
+
pid=None,
|
|
243
|
+
error=str(exc),
|
|
244
|
+
)
|
|
245
|
+
return failed.check_returncode() if check else failed
|
|
246
|
+
|
|
247
|
+
limit_event = threading.Event()
|
|
248
|
+
streams = [
|
|
249
|
+
_Stream(name, pipe, max_output, tail_bytes, stop_on_output_limit, limit_event, on_output)
|
|
250
|
+
for name, pipe in (("stdout", proc.stdout), ("stderr", proc.stderr))
|
|
251
|
+
]
|
|
252
|
+
if input is not None:
|
|
253
|
+
threading.Thread(target=_feed_stdin, args=(proc.stdin, input), daemon=True).start()
|
|
254
|
+
|
|
255
|
+
deadline = start + timeout if timeout is not None else None
|
|
256
|
+
reason = "exited"
|
|
257
|
+
while proc.poll() is None:
|
|
258
|
+
if cancel is not None and cancel.is_set():
|
|
259
|
+
reason = "cancelled"
|
|
260
|
+
elif limit_event.is_set():
|
|
261
|
+
reason = "output-limit"
|
|
262
|
+
elif deadline is not None and time.monotonic() >= deadline:
|
|
263
|
+
reason = "timeout"
|
|
264
|
+
if reason != "exited":
|
|
265
|
+
break
|
|
266
|
+
try:
|
|
267
|
+
proc.wait(timeout=_POLL)
|
|
268
|
+
except subprocess.TimeoutExpired:
|
|
269
|
+
pass
|
|
270
|
+
|
|
271
|
+
kill: KillInfo | None = None
|
|
272
|
+
if reason != "exited":
|
|
273
|
+
kill = kill_tree(proc, grace=grace) if kill_process_tree else _stop_leader_only(proc, grace)
|
|
274
|
+
proc.wait()
|
|
275
|
+
|
|
276
|
+
for stream in streams:
|
|
277
|
+
stream.thread.join(drain_timeout)
|
|
278
|
+
if any(s.thread.is_alive() for s in streams):
|
|
279
|
+
# A descendant still holds the pipes open.
|
|
280
|
+
if kill_process_tree:
|
|
281
|
+
late = kill_tree(proc, grace=0)
|
|
282
|
+
kill = kill or late
|
|
283
|
+
for stream in streams:
|
|
284
|
+
stream.thread.join(1.0)
|
|
285
|
+
for pipe in (proc.stdout, proc.stderr):
|
|
286
|
+
try:
|
|
287
|
+
pipe.close()
|
|
288
|
+
except (OSError, ValueError):
|
|
289
|
+
pass
|
|
290
|
+
|
|
291
|
+
result = RunResult(
|
|
292
|
+
argv=args,
|
|
293
|
+
exit_code=proc.returncode,
|
|
294
|
+
stop_reason=reason,
|
|
295
|
+
duration=time.monotonic() - start,
|
|
296
|
+
stdout=bytes(streams[0].head),
|
|
297
|
+
stderr=bytes(streams[1].head),
|
|
298
|
+
stdout_tail=streams[0].final_tail(),
|
|
299
|
+
stderr_tail=streams[1].final_tail(),
|
|
300
|
+
truncated=any(s.truncated for s in streams),
|
|
301
|
+
pid=proc.pid,
|
|
302
|
+
kill=kill,
|
|
303
|
+
)
|
|
304
|
+
return result.check_returncode() if check else result
|
|
File without changes
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: uppercut-subprocess-runner
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Run a subprocess with a timeout, an output cap and cancellation, and kill its whole process tree.
|
|
5
|
+
Project-URL: Source, https://github.com/uppercut-labs/py-kit/tree/main/packages/uppercut-subprocess-runner
|
|
6
|
+
Author-email: Uppercut Labs <packages@uppercut-labs.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Keywords: kill,process-tree,sigterm,subprocess,taskkill,timeout
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Operating System :: MacOS
|
|
12
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
13
|
+
Classifier: Operating System :: POSIX
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# uppercut-subprocess-runner
|
|
24
|
+
|
|
25
|
+
Runs a command with a timeout, an output cap and cancellation, and returns a result object with the exit code, the captured output, the last bytes of each stream and how the run ended. When it has to stop the command it kills the whole process tree: the process group on macOS and Linux, a process-group break followed by `taskkill /F /T` on Windows. It sends a soft signal first, waits a grace period, then forces the kill. Standard library only.
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
pip install uppercut-subprocess-runner
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
```python
|
|
32
|
+
import threading
|
|
33
|
+
from uppercut_subprocess_runner import run
|
|
34
|
+
|
|
35
|
+
cancel = threading.Event() # call cancel.set() from another thread to stop the run
|
|
36
|
+
|
|
37
|
+
result = run(
|
|
38
|
+
["python", "build.py", "--fast"],
|
|
39
|
+
cwd="project",
|
|
40
|
+
timeout=120,
|
|
41
|
+
max_output=2_000_000,
|
|
42
|
+
grace=5,
|
|
43
|
+
cancel=cancel,
|
|
44
|
+
)
|
|
45
|
+
|
|
46
|
+
if result.timed_out:
|
|
47
|
+
print("gave up after", round(result.duration), "seconds")
|
|
48
|
+
elif not result.ok:
|
|
49
|
+
print(result.error_tail())
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Use `check=True` to raise `CommandError` instead, with the tail of the output in the message and the full result in `error.result`.
|
|
53
|
+
|
|
54
|
+
## Functions
|
|
55
|
+
|
|
56
|
+
| Function | Returns |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| `run(argv, **options)` | `RunResult` |
|
|
59
|
+
| `kill_tree(process_or_pid, grace=5.0)` | `KillInfo` |
|
|
60
|
+
| `popen_group(argv, **popen_options)` | a `subprocess.Popen` started in its own session or process group |
|
|
61
|
+
| `popen_group_kwargs(no_window=False)` | the `Popen` keyword arguments that `popen_group` adds |
|
|
62
|
+
|
|
63
|
+
## Options for `run`
|
|
64
|
+
|
|
65
|
+
| Option | Default | Meaning |
|
|
66
|
+
| --- | --- | --- |
|
|
67
|
+
| `cwd`, `env` | inherited | Working directory and environment of the command |
|
|
68
|
+
| `input` | none | Bytes written to stdin. Without it stdin is closed |
|
|
69
|
+
| `timeout` | none | Seconds before the run is stopped with `stop_reason == "timeout"` |
|
|
70
|
+
| `max_output` | `10_000_000` | Bytes kept from the start of each stream. `None` keeps everything |
|
|
71
|
+
| `stop_on_output_limit` | `True` | Stop the command when a stream passes `max_output`. `False` keeps reading and drops the excess |
|
|
72
|
+
| `tail_bytes` | `8192` | Bytes kept from the end of each stream, even past `max_output` |
|
|
73
|
+
| `grace` | `5.0` | Seconds between the soft signal and the forced kill |
|
|
74
|
+
| `cancel` | none | A `threading.Event`. Setting it stops the run with `stop_reason == "cancelled"` |
|
|
75
|
+
| `on_output` | none | Called as `on_output("stdout" or "stderr", chunk)` from reader threads. Exceptions it raises are ignored |
|
|
76
|
+
| `kill_process_tree` | `True` | `False` signals only the command itself and leaves its descendants running |
|
|
77
|
+
| `drain_timeout` | `1.0` | Seconds to wait for the pipes to close after the command exits. If a descendant still holds them, the tree is killed |
|
|
78
|
+
| `no_window` | `False` | Windows only: start the command without a console window |
|
|
79
|
+
| `check` | `False` | Raise `CommandError` unless the command exits with code 0 |
|
|
80
|
+
|
|
81
|
+
## RunResult
|
|
82
|
+
|
|
83
|
+
| Field | Meaning |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| `argv` | The command that ran |
|
|
86
|
+
| `exit_code` | Exit code. `None` if it never started. Negative signal number after a kill on macOS and Linux |
|
|
87
|
+
| `stop_reason` | `"exited"`, `"timeout"`, `"cancelled"`, `"output-limit"` or `"spawn-failed"` |
|
|
88
|
+
| `timed_out`, `cancelled`, `ok` | Shortcuts. `ok` means it exited by itself with code 0 |
|
|
89
|
+
| `truncated` | A stream produced more than `max_output` bytes |
|
|
90
|
+
| `duration` | Seconds from start to finish |
|
|
91
|
+
| `stdout`, `stderr` | Captured bytes, at most `max_output` each. `stdout_text` and `stderr_text` decode them |
|
|
92
|
+
| `stdout_tail`, `stderr_tail` | The last `tail_bytes` of each stream. `error_tail(limit)` returns the stderr tail as text, or the stdout tail if stderr is empty |
|
|
93
|
+
| `pid` | Process id of the command |
|
|
94
|
+
| `kill` | A `KillInfo` when the run was stopped, otherwise `None` |
|
|
95
|
+
| `error` | The operating system's message when `stop_reason == "spawn-failed"` |
|
|
96
|
+
|
|
97
|
+
`KillInfo` has `method`, `already_exited`, `graceful` (the soft signal was enough) and `forced` (SIGKILL or `taskkill /F` was needed).
|
|
98
|
+
|
|
99
|
+
## Notes
|
|
100
|
+
|
|
101
|
+
- `kill_tree` on macOS and Linux needs the target to lead its own process group. Processes started by `run` and `popen_group` do. It raises `ValueError` rather than signal the calling process's own group.
|
|
102
|
+
- On Windows the soft step is `CTRL_BREAK_EVENT`, which ends most console programs. Descendants of a command that exits during the grace period cannot be found afterwards and keep running.
|
|
103
|
+
- Error messages from `check=True` name the program but not its arguments.
|
|
104
|
+
|
|
105
|
+
## License
|
|
106
|
+
|
|
107
|
+
MIT
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
uppercut_subprocess_runner/__init__.py,sha256=92IWcPhSTttIGEdUKXs9sUSBS-avITuT6JfUlVDSUeM,390
|
|
2
|
+
uppercut_subprocess_runner/_kill.py,sha256=fAclH91fQcf49yaya_5P4u6tFKPDcM5pkyTU43nR3W4,6091
|
|
3
|
+
uppercut_subprocess_runner/_runner.py,sha256=8UThLqWJbaKics2xBliaE680NNyBggRnVbYDUzTRRaw,10287
|
|
4
|
+
uppercut_subprocess_runner/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
5
|
+
uppercut_subprocess_runner-0.1.0.dist-info/METADATA,sha256=fgLr8kvM8h1WmYadKJ4TqNXtu7LK9poIRjFrre-3mMw,5411
|
|
6
|
+
uppercut_subprocess_runner-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
7
|
+
uppercut_subprocess_runner-0.1.0.dist-info/RECORD,,
|