bounded_subprocess 1.5.0__py3-none-any.whl

bounded_subprocess/__init__.py

@@ -0,0 +1,30 @@
+import time
+from typing import List
+
+from .util import Result, BoundedSubprocessState, SLEEP_BETWEEN_READS
+
+
+def run(
+    args: List[str],
+    timeout_seconds: int = 15,
+    max_output_size: int = 2048,
+    env=None,
+) -> Result:
+    """
+    Runs the given program with arguments. After the timeout elapses, kills the process
+    and all other processes in the process group. Captures at most max_output_size bytes
+    of stdout and stderr each, and discards any output beyond that.
+    """
+    state = BoundedSubprocessState(args, env, max_output_size)
+
+    # We sleep for 0.1 seconds in each iteration.
+    max_iterations = timeout_seconds * 10
+
+    for _ in range(max_iterations):
+        keep_reading = state.try_read()
+        if keep_reading:
+            time.sleep(SLEEP_BETWEEN_READS)
+        else:
+            break
+
+    return state.terminate()

bounded_subprocess/bounded_subprocess_async.py

@@ -0,0 +1,33 @@
+import asyncio
+from typing import List
+from .util import Result, BoundedSubprocessState, SLEEP_BETWEEN_READS
+
+
+async def run(
+    args: List[str],
+    timeout_seconds: int = 15,
+    max_output_size: int = 2048,
+    env=None,
+) -> Result:
+    """
+    Runs the given program with arguments. After the timeout elapses, kills the process
+    and all other processes in the process group. Captures at most max_output_size bytes
+    of stdout and stderr each, and discards any output beyond that.
+    """
+    # If you read the code for BoundedSubprocessState, you probably thought we
+    # were going to use asyncio.create_subprocess_exec. But, we're not. We're
+    # using subprocess.Popen because it supports non-blocking reads. What's
+    # async here? It's just the sleep between reads.
+    state = BoundedSubprocessState(args, env, max_output_size)
+
+    # We sleep for 0.1 seconds in each iteration.
+    max_iterations = timeout_seconds * 10
+
+    for _ in range(max_iterations):
+        keep_reading = state.try_read()
+        if keep_reading:
+            await asyncio.sleep(SLEEP_BETWEEN_READS)
+        else:
+            break
+
+    return state.terminate()

bounded_subprocess/interactive.py

@@ -0,0 +1,131 @@
+from typeguard import typechecked
+from typing import List, Optional
+import time
+import errno
+import subprocess
+from .util import set_nonblocking
+
+
+_MAX_BYTES_PER_READ = 1024
+_SLEEP_AFTER_WOUND_BLOCK = 0.5
+
+
+@typechecked
+class Interactive:
+    """
+    A class for interacting with a subprocess that is careful to use non-blocking
+    I/O so that we can timeout reads and writes.
+    """
+
+    def __init__(self, args: List[str], read_buffer_size: int):
+        """
+        read_buffer_size is the maximum number of bytes to read from stdout
+        and stdout each. If the process writes more than this, the extra bytes
+        will be discarded.
+        """
+        popen = subprocess.Popen(
+            args,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            # stderr=subprocess.PIPE,
+            bufsize=_MAX_BYTES_PER_READ,
+        )
+        set_nonblocking(popen.stdin)
+        set_nonblocking(popen.stdout)
+        self._read_buffer_size = read_buffer_size
+        self._stdout_saved_bytes = bytearray()
+        self._stderr_saved_bytes = bytearray()
+        self._popen = popen
+
+    def close(self, nice_timeout_seconds: int) -> int:
+        """
+        Close the process and wait for it to exit.
+        """
+        try:
+            self._popen.stdin.close()
+        except BlockingIOError:
+            # .close() will attempt to flush any buffered writes to stdout
+            # before the close returns. This may block, but since the file
+            # descriptor is non-blocking, we get a BlockingIOError.
+            pass
+        self._popen.stdout.close()
+        for _ in range(nice_timeout_seconds):
+            if self._popen.poll() is not None:
+                break
+            time.sleep(1)
+        self._popen.kill()
+        return_code = self._popen.returncode
+        return return_code if return_code is not None else -9
+
+    def write(self, stdin_data: bytes, timeout_seconds: int):
+        """
+        Write data to the process's stdin.
+        """
+        if self._popen.poll() is not None:
+            return False
+
+        write_start_index = 0
+        start_time = time.time()
+        while write_start_index < len(stdin_data):
+            try:
+                bytes_written = self._popen.stdin.write(stdin_data[write_start_index:])
+                self._popen.stdin.flush()
+            except BlockingIOError as exn:
+                if exn.errno != errno.EAGAIN:
+                    return False
+                bytes_written = exn.characters_written
+                time.sleep(_SLEEP_AFTER_WOUND_BLOCK)
+            except BrokenPipeError:
+                # The child has closed stdin. It is likely dead.
+                return False
+            write_start_index += bytes_written
+            if time.time() - start_time > timeout_seconds:
+                return False
+        return True
+
+    def _read_line_from_saved_bytes(self, newline_search_index: int) -> Optional[bytes]:
+        """
+        Try to read a line of output from the buffer of stdout that this object
+        manages itself. The newline_search_index to indicate where to  start
+        looking for b"\n". Typically will be 0, but there are cases where we
+        are certain that the the newline is not in a prefix.
+        """
+        newline_index = self._stdout_saved_bytes.find(b"\n", newline_search_index)
+        if newline_index == -1:
+            return None
+        # memoryview helps avoid a pointless copy
+        line = memoryview(self._stdout_saved_bytes)[:newline_index].tobytes()
+        del self._stdout_saved_bytes[: newline_index + 1]
+        return line
+
+    def read_line(self, timeout_seconds: int) -> Optional[bytes]:
+        """
+        Read a line from the process's stdout.
+        """
+        from_saved_bytes = self._read_line_from_saved_bytes(0)
+        if from_saved_bytes is not None:
+            return from_saved_bytes
+        if self._popen.poll() is not None:
+            return None
+        deadline = time.time() + timeout_seconds
+        while time.time() < deadline:
+            new_bytes = self._popen.stdout.read(_MAX_BYTES_PER_READ)
+            # If the read would block, we get None and not zero bytes on MacOS.
+            if new_bytes is None:
+                time.sleep(_SLEEP_AFTER_WOUND_BLOCK)
+                continue
+            # If we read 0 bytes, the child has closed stdout and is likely dead.
+            if len(new_bytes) == 0:
+                return None
+            prev_saved_bytes_len = len(self._stdout_saved_bytes)
+            self._stdout_saved_bytes.extend(new_bytes)
+            from_saved_bytes = self._read_line_from_saved_bytes(prev_saved_bytes_len)
+            if from_saved_bytes is not None:
+                return from_saved_bytes
+            if len(self._stdout_saved_bytes) > self._read_buffer_size:
+                del self._stdout_saved_bytes[
+                    : len(self._stdout_saved_bytes) - self._read_buffer_size
+                ]
+            time.sleep(_SLEEP_AFTER_WOUND_BLOCK)
+
+        return None

bounded_subprocess/interactive_async.py

@@ -0,0 +1,131 @@
+from typeguard import typechecked
+from typing import List, Optional
+import time
+import errno
+import subprocess
+from .util import set_nonblocking
+import asyncio
+
+_MAX_BYTES_PER_READ = 1024
+_SLEEP_AFTER_WOUND_BLOCK = 0.5
+
+
+@typechecked
+class Interactive:
+    """
+    A class for interacting with a subprocess that is careful to use non-blocking
+    I/O so that we can timeout reads and writes.
+    """
+
+    def __init__(self, args: List[str], read_buffer_size: int):
+        """
+        read_buffer_size is the maximum number of bytes to read from stdout
+        and stdout each. If the process writes more than this, the extra bytes
+        will be discarded.
+        """
+        popen = subprocess.Popen(
+            args,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            # stderr=subprocess.PIPE,
+            bufsize=_MAX_BYTES_PER_READ,
+        )
+        set_nonblocking(popen.stdin)
+        set_nonblocking(popen.stdout)
+        self._read_buffer_size = read_buffer_size
+        self._stdout_saved_bytes = bytearray()
+        self._stderr_saved_bytes = bytearray()
+        self._popen = popen
+
+    async def close(self, nice_timeout_seconds: int) ->  int:
+        """
+        Close the process and wait for it to exit.
+        """
+        try:
+            self._popen.stdin.close()
+        except BlockingIOError:
+            # .close() will attempt to flush any buffered writes to stdout
+            # before the close returns. This may block, but since the file
+            # descriptor is non-blocking, we get a BlockingIOError.
+            pass
+        self._popen.stdout.close()
+        for _ in range(nice_timeout_seconds):
+            if self._popen.poll() is not None:
+                break
+            await asyncio.sleep(1)
+        self._popen.kill()
+        return_code = self._popen.returncode
+        return return_code if return_code is not None else -9
+
+    async def write(self, stdin_data: bytes, timeout_seconds: int):
+        """
+        Write data to the process's stdin.
+        """
+        if self._popen.poll() is not None:
+            return False
+
+        write_start_index = 0
+        start_time = time.time()
+        while write_start_index < len(stdin_data):
+            try:
+                bytes_written = self._popen.stdin.write(stdin_data[write_start_index:])
+                self._popen.stdin.flush()
+            except BlockingIOError as exn:
+                if exn.errno != errno.EAGAIN:
+                    return False
+                bytes_written = exn.characters_written
+                await asyncio.sleep(_SLEEP_AFTER_WOUND_BLOCK)
+            except BrokenPipeError:
+                # The child has closed stdin. It is likely dead.
+                return False
+            write_start_index += bytes_written
+            if time.time() - start_time > timeout_seconds:
+                return False
+        return True
+
+    def _read_line_from_saved_bytes(self, newline_search_index: int) -> Optional[bytes]:
+        """
+        Try to read a line of output from the buffer of stdout that this object
+        manages itself. The newline_search_index to indicate where to  start
+        looking for b"\n". Typically will be 0, but there are cases where we
+        are certain that the the newline is not in a prefix.
+        """
+        newline_index = self._stdout_saved_bytes.find(b"\n", newline_search_index)
+        if newline_index == -1:
+            return None
+        # memoryview helps avoid a pointless copy
+        line = memoryview(self._stdout_saved_bytes)[:newline_index].tobytes()
+        del self._stdout_saved_bytes[: newline_index + 1]
+        return line
+
+    async def read_line(self, timeout_seconds: int) -> Optional[bytes]:
+        """
+        Read a line from the process's stdout.
+        """
+        from_saved_bytes = self._read_line_from_saved_bytes(0)
+        if from_saved_bytes is not None:
+            return from_saved_bytes
+        if self._popen.poll() is not None:
+            return None
+        deadline = time.time() + timeout_seconds
+        while time.time() < deadline:
+            new_bytes = self._popen.stdout.read(_MAX_BYTES_PER_READ)
+            # If the read would block, we get None and not zero bytes on MacOS.
+            if new_bytes is None:
+                await asyncio.sleep(_SLEEP_AFTER_WOUND_BLOCK)
+                continue
+            # If we read 0 bytes, the child has closed stdout and is likely dead.
+            if len(new_bytes) == 0:
+                return None
+            prev_saved_bytes_len = len(self._stdout_saved_bytes)
+            self._stdout_saved_bytes.extend(new_bytes)
+            from_saved_bytes = self._read_line_from_saved_bytes(prev_saved_bytes_len)
+            if from_saved_bytes is not None:
+                return from_saved_bytes
+            if len(self._stdout_saved_bytes) > self._read_buffer_size:
+                del self._stdout_saved_bytes[
+                    : len(self._stdout_saved_bytes) - self._read_buffer_size
+                ]
+            await asyncio.sleep(_SLEEP_AFTER_WOUND_BLOCK)
+
+        return None

bounded_subprocess/util.py

@@ -0,0 +1,110 @@
+import subprocess
+import os
+import fcntl
+import signal
+
+MAX_BYTES_PER_READ = 1024
+SLEEP_BETWEEN_READS = 0.1
+
+
+class Result:
+    timeout: int
+    exit_code: int
+    stdout: str
+    stderr: str
+
+    def __init__(self, timeout, exit_code, stdout, stderr):
+        self.timeout = timeout
+        self.exit_code = exit_code
+        self.stdout = stdout
+        self.stderr = stderr
+
+
+def set_nonblocking(reader):
+    fd = reader.fileno()
+    fl = fcntl.fcntl(fd, fcntl.F_GETFL)
+    fcntl.fcntl(fd, fcntl.F_SETFL, fl | os.O_NONBLOCK)
+
+
+class BoundedSubprocessState:
+    """
+    This class lets us share code between the synchronous and asynchronous
+    implementations.
+    """
+
+    def __init__(self, args, env, max_output_size):
+        """
+        Start the process in a new session.
+        """
+        p = subprocess.Popen(
+            args,
+            env=env,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            start_new_session=True,
+            bufsize=MAX_BYTES_PER_READ,
+        )
+        set_nonblocking(p.stdout)
+        set_nonblocking(p.stderr)
+
+        self.process_group_id = os.getpgid(p.pid)
+        self.p = p
+        self.exit_code = None
+        self.stdout_saved_bytes = []
+        self.stderr_saved_bytes = []
+        self.stdout_bytes_read = 0
+        self.stderr_bytes_read = 0
+        self.max_output_size = max_output_size
+
+    def try_read(self) -> bool:
+        """
+        Reads from the process. Returning False indicates that we should stop
+        reading.
+        """
+        this_stdout_read = self.p.stdout.read(MAX_BYTES_PER_READ)
+        this_stderr_read = self.p.stderr.read(MAX_BYTES_PER_READ)
+        # this_stdout_read and this_stderr_read may be None if stdout or stderr
+        # are closed. Without these checks, test_close_output fails.
+        if (
+            this_stdout_read is not None
+            and self.stdout_bytes_read < self.max_output_size
+        ):
+            self.stdout_saved_bytes.append(this_stdout_read)
+            self.stdout_bytes_read += len(this_stdout_read)
+        if (
+            this_stderr_read is not None
+            and self.stderr_bytes_read < self.max_output_size
+        ):
+            self.stderr_saved_bytes.append(this_stderr_read)
+            self.stderr_bytes_read += len(this_stderr_read)
+
+        self.exit_code = self.p.poll()
+        if self.exit_code is not None:
+            # Finish reading output if needed.
+            left_to_read = self.max_output_size - self.stdout_bytes_read
+            if left_to_read <= 0:
+                return False
+            this_stdout_read = self.p.stdout.read(left_to_read)
+            this_stderr_read = self.p.stderr.read(left_to_read)
+            if this_stdout_read is not None:
+                self.stdout_saved_bytes.append(this_stdout_read)
+            if this_stderr_read is not None:
+                self.stderr_saved_bytes.append(this_stderr_read)
+            return False
+        return True
+
+    def terminate(self) -> Result:
+        try:
+            # Kills the process group. Without this line, test_fork_once fails.
+            os.killpg(self.process_group_id, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+
+        timeout = self.exit_code is None
+        exit_code = self.exit_code if self.exit_code is not None else -1
+        stdout = b"".join(self.stdout_saved_bytes).decode("utf-8", errors="ignore")
+        stderr = b"".join(self.stderr_saved_bytes).decode("utf-8", errors="ignore")
+        return Result(
+            timeout=timeout, exit_code=exit_code, stdout=stdout, stderr=stderr
+        )

bounded_subprocess-1.5.0.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: bounded_subprocess
+Version: 1.5.0
+Summary: A library to facilitate running subprocesses that may misbehave.
+Project-URL: Homepage, https://github.com/arjunguha/bounded_subprocess
+Project-URL: Bug Tracker, https://github.com/arjunguha/bounded_subprocess
+Author: Arjun Guha, Ming-Ho Yee, Francesca Lucchetti
+License: MIT License
+        
+        Copyright (c) 2022--2024 Northeastern University
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+License-File: LICENSE.txt
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: typeguard<5.0.0,>=4.4.2
+Description-Content-Type: text/markdown
+
+# bounded_subprocess
+
+[![PyPI - Version](https://img.shields.io/pypi/v/bounded-subprocess.svg)](https://pypi.org/project/bounded-subprocess)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bounded-subprocess.svg)](https://pypi.org/project/bounded-subprocess)
+
+The `bounded-subprocess` module runs a subprocess with several bounds:
+
+1. The subprocess runs in a Linux session, so the process and all its children
+   can be killed;
+2. The subprocess runs with a given timeout; and
+3. The parent captures a bounded amount of output from the subprocess and
+   discards the rest.
+
+Note that the subprocess is not isolated: it can use the network, the filesystem,
+or create new sessions.
+
+## Installation
+
+```console
+python3 -m pip install bounded-subprocess
+```
+
+## License
+
+`bounded-subprocess` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

bounded_subprocess-1.5.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+bounded_subprocess/__init__.py,sha256=PHsdbPdGYopVQH_KG8vdpifyt8ZuCLd0h_JeMRCPNdI,855
+bounded_subprocess/bounded_subprocess_async.py,sha256=uvwMhB0OSJ91qJXVFlIzWfNQXQzw9I8WV7RdNzNWVDc,1158
+bounded_subprocess/interactive.py,sha256=Vn-002fH6rAekOwugGqdZUZ3O3x1wY-mLxApBtyC-DA,5016
+bounded_subprocess/interactive_async.py,sha256=igxFfeC7zdQxX34-pQRlTNgYIpSbVFgmGYCCvpwsMPw,5085
+bounded_subprocess/util.py,sha256=MBP34Juj-3JGJj6-XFzTaLhPZztQGk2tpONH8AvUX48,3638
+bounded_subprocess-1.5.0.dist-info/METADATA,sha256=FA0SjIq_lciG1NrdOXjF29tCXIKAuCFO2WyiAlkwkdI,2664
+bounded_subprocess-1.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+bounded_subprocess-1.5.0.dist-info/licenses/LICENSE.txt,sha256=UVerBV0_1vMFt8QkaXuVnZVSlOiKDiBSieK5MNLy4Ls,1086
+bounded_subprocess-1.5.0.dist-info/RECORD,,

bounded_subprocess-1.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bounded_subprocess-1.5.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2022--2024 Northeastern University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.