bounded_subprocess 2.5.0__py3-none-any.whl

bounded_subprocess/__init__.py

@@ -0,0 +1,31 @@
+"""
+Bounded subprocess execution with timeout and output limits.
+
+This package provides convenient functions for running subprocesses with bounded
+execution time and output size, with support for both synchronous and asynchronous
+execution patterns.
+"""
+
+__version__ = "1.0.0"
+
+
+# Lazy imports for better startup performance
+def __getattr__(name):
+    if name == "run":
+        from .bounded_subprocess import run
+
+        return run
+    elif name == "Result":
+        from .util import Result
+
+        return Result
+    elif name == "SLEEP_BETWEEN_READS":
+        from .util import SLEEP_BETWEEN_READS
+
+        return SLEEP_BETWEEN_READS
+    else:
+        raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+# Expose key classes and constants for convenience
+__all__ = ["run", "Result", "SLEEP_BETWEEN_READS"]

bounded_subprocess/bounded_subprocess.py

@@ -0,0 +1,122 @@
+"""
+Synchronous subprocess execution with bounds on runtime and output size.
+"""
+
+import subprocess
+import os
+import signal
+from typing import List, Optional
+import time
+
+from .util import (
+    Result,
+    set_nonblocking,
+    MAX_BYTES_PER_READ,
+    write_nonblocking_sync,
+    read_to_eof_sync,
+)
+
+
+def run(
+    args: List[str],
+    timeout_seconds: int = 15,
+    max_output_size: int = 2048,
+    env=None,
+    stdin_data: Optional[str] = None,
+    stdin_write_timeout: Optional[int] = None,
+) -> Result:
+    """
+    Run a subprocess with a timeout and bounded stdout/stderr capture.
+
+    This helper starts the child in a new session so timeout cleanup can kill
+    the entire process group. Stdout and stderr are read in nonblocking mode and
+    truncated to `max_output_size` bytes each. If the timeout elapses, the
+    returned `Result.timeout` is True and `Result.exit_code` is -1. If
+    `stdin_data` cannot be fully written before `stdin_write_timeout`,
+    `Result.exit_code` is set to -1 even if the process exits normally.
+
+    Example:
+
+    ```python
+    from bounded_subprocess import run
+
+    result = run(
+        ["bash", "-lc", "echo ok; echo err 1>&2"],
+        timeout_seconds=5,
+        max_output_size=1024,
+    )
+    print(result.exit_code)
+    print(result.stdout.strip())
+    print(result.stderr.strip())
+    ```
+    """
+    deadline = time.time() + timeout_seconds
+
+    p = subprocess.Popen(
+        args,
+        env=env,
+        stdin=subprocess.PIPE if stdin_data is not None else subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        start_new_session=True,
+        bufsize=MAX_BYTES_PER_READ,
+    )
+    process_group_id = os.getpgid(p.pid)
+
+    set_nonblocking(p.stdout)
+    set_nonblocking(p.stderr)
+
+    if stdin_data is not None:
+        set_nonblocking(p.stdin)
+        write_ok = write_nonblocking_sync(
+            fd=p.stdin,
+            data=stdin_data.encode(),
+            timeout_seconds=stdin_write_timeout
+            if stdin_write_timeout is not None
+            else 15,
+        )
+        # From what I recall, closing stdin is not necessary, but is customary.
+        try:
+            p.stdin.close()
+        except (BrokenPipeError, BlockingIOError):
+            pass
+
+    bufs = read_to_eof_sync(
+        [p.stdout, p.stderr],
+        timeout_seconds=timeout_seconds,
+        max_len=max_output_size,
+    )
+
+    # Without this, even the trivial test fails on Linux but not on macOS. It
+    # seems possible for (1) both stdout and stderr to close (2) before the child
+    # process exits, and we can observe the instant between (1) and (2). So, we
+    # need to p.wait and not p.poll.
+    #
+    # Reading the above, we should be able to write a test case that just closes
+    # both stdout and stderr explicitly, and then sleeps for an instant before
+    # terminating normally. That program should not timeout.
+    try:
+        exit_code = p.wait(timeout=max(0, deadline - time.time()))
+        is_timeout = False
+    except subprocess.TimeoutExpired:
+        exit_code = None
+        is_timeout = True
+
+    try:
+        # Kills the process group. Without this line, test_fork_once fails.
+        os.killpg(process_group_id, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+
+    # Even if the process terminates normally, if we failed to write everything to
+    # stdin, we return -1 as the exit code.
+    exit_code = (
+        -1 if is_timeout or (stdin_data is not None and not write_ok) else exit_code
+    )
+
+    return Result(
+        timeout=is_timeout,
+        exit_code=exit_code,
+        stdout=bufs[0].decode(errors="ignore"),
+        stderr=bufs[1].decode(errors="ignore"),
+    )

bounded_subprocess/bounded_subprocess_async.py

@@ -0,0 +1,297 @@
+"""
+Asynchronous subprocess execution with bounds on runtime and output size.
+"""
+
+import asyncio
+import os
+import signal
+import time
+import subprocess
+import tempfile
+from typing import List, Optional
+import logging
+
+from .util import (
+    Result,
+    set_nonblocking,
+    MAX_BYTES_PER_READ,
+    write_nonblocking_async,
+    read_to_eof_async,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def run(
+    args: List[str],
+    timeout_seconds: int = 15,
+    max_output_size: int = 2048,
+    env=None,
+    stdin_data: Optional[str] = None,
+    stdin_write_timeout: Optional[int] = None,
+) -> Result:
+    """
+    Run a subprocess asynchronously with bounded stdout/stderr capture.
+
+    The child process is started in a new session and polled until it exits or
+    the timeout elapses. Stdout and stderr are read in nonblocking mode and
+    truncated to `max_output_size` bytes each. If the timeout elapses,
+    `Result.timeout` is True and `Result.exit_code` is -1. If `stdin_data`
+    cannot be fully written before `stdin_write_timeout`, `Result.exit_code`
+    is set to -1 even if the process exits normally.
+
+    Example:
+
+    ```python
+    import asyncio
+    from bounded_subprocess.bounded_subprocess_async import run
+
+    async def main():
+        result = await run(
+            ["bash", "-lc", "echo ok; echo err 1>&2"],
+            timeout_seconds=5,
+            max_output_size=1024,
+        )
+        print(result.exit_code)
+        print(result.stdout.strip())
+        print(result.stderr.strip())
+
+    asyncio.run(main())
+    ```
+    """
+
+    deadline = time.time() + timeout_seconds
+
+    p = subprocess.Popen(
+        args,
+        env=env,
+        stdin=subprocess.PIPE if stdin_data is not None else subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        start_new_session=True,
+        bufsize=MAX_BYTES_PER_READ,
+    )
+    process_group_id = os.getpgid(p.pid)
+
+    set_nonblocking(p.stdout)
+    set_nonblocking(p.stderr)
+
+    write_ok = True
+    if stdin_data is not None:
+        set_nonblocking(p.stdin)
+        write_ok = await write_nonblocking_async(
+            fd=p.stdin,
+            data=stdin_data.encode(),
+            timeout_seconds=stdin_write_timeout
+            if stdin_write_timeout is not None
+            else 15,
+        )
+        try:
+            p.stdin.close()
+        except (BrokenPipeError, BlockingIOError):
+            pass
+
+    bufs = await read_to_eof_async(
+        [p.stdout, p.stderr],
+        timeout_seconds=timeout_seconds,
+        max_len=max_output_size,
+    )
+
+    exit_code = None
+    is_timeout = False
+    while True:
+        rc = p.poll()
+        if rc is not None:
+            exit_code = rc
+            break
+        remaining = deadline - time.time()
+        if remaining <= 0:
+            is_timeout = True
+            break
+        await asyncio.sleep(min(0.05, remaining))
+
+    try:
+        os.killpg(process_group_id, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+
+    exit_code = (
+        -1 if is_timeout or (stdin_data is not None and not write_ok) else exit_code
+    )
+
+    return Result(
+        timeout=is_timeout,
+        exit_code=exit_code if exit_code is not None else -1,
+        stdout=bufs[0].decode(errors="ignore"),
+        stderr=bufs[1].decode(errors="ignore"),
+    )
+
+
+# https://docs.podman.io/en/stable/markdown/podman-rm.1.html
+async def _podman_rm(cidfile_path: str):
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "podman",
+            "rm",
+            "-f",
+            "--time",
+            "0",
+            "--cidfile",
+            cidfile_path,
+            "--ignore",
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        # podman rm can take time. I think this will eventually complete even
+        # if we timeout below.
+        await asyncio.wait_for(proc.wait(), timeout=5.0)
+    except Exception as e:
+        logger.error(f"Error removing container: {e}")
+    finally:
+        try:
+            os.unlink(cidfile_path)
+        except OSError:
+            pass
+
+
+async def podman_run(
+    args: List[str],
+    *,
+    image: str,
+    timeout_seconds: int,
+    max_output_size: int,
+    env=None,
+    stdin_data: Optional[str] = None,
+    stdin_write_timeout: Optional[int] = None,
+    volumes: List[str] = [],
+    cwd: Optional[str] = None,
+) -> Result:
+    """
+    Run a subprocess in a podman container asynchronously with bounded stdout/stderr capture.
+
+    This function wraps `run` but executes the command inside a podman container.
+    The container is automatically removed after execution. The interface is otherwise
+    the same as `run`, except for an additional `image` parameter to specify the
+    container image to use.
+
+    Args:
+        args: Command arguments to run in the container.
+        image: Container image to use.
+        timeout_seconds: Maximum time to wait for the process to complete.
+        max_output_size: Maximum size in bytes for stdout/stderr capture.
+        env: Optional dictionary of environment variables.
+        stdin_data: Optional string data to write to stdin.
+        stdin_write_timeout: Optional timeout for writing stdin data.
+        volumes: Optional list of volume mount specifications (e.g., ["/host/path:/container/path"]).
+        cwd: Optional working directory path inside the container.
+
+    Example:
+
+    ```python
+    import asyncio
+    from bounded_subprocess.bounded_subprocess_async import podman_run
+
+    async def main():
+        result = await podman_run(
+            ["cat"],
+            image="alpine:latest",
+            timeout_seconds=5,
+            max_output_size=1024,
+            stdin_data="hello\n",
+            volumes=["/host/data:/container/data"],
+            cwd="/container/data",
+        )
+        print(result.exit_code)
+        print(result.stdout.strip())
+
+    asyncio.run(main())
+    ```
+    """
+    deadline = time.time() + timeout_seconds
+
+    # Use --cidfile to get the container ID
+    with tempfile.NamedTemporaryFile(
+        mode="w", delete=False, prefix="bounded_subprocess_cid_"
+    ) as cidfile:
+        cidfile_path = cidfile.name
+
+    # Build podman command
+    podman_args = ["podman", "run", "--rm", "-i", "--cidfile", cidfile_path]
+
+    # Handle environment variables
+    if env is not None:
+        # Convert env dict to -e flags for podman
+        for key, value in env.items():
+            podman_args.extend(["-e", f"{key}={value}"])
+
+    # Handle volume mounts
+    for volume in volumes:
+        podman_args.extend(["-v", volume])
+
+    # Handle working directory
+    if cwd is not None:
+        podman_args.extend(["-w", cwd])
+
+    podman_args.append(image)
+    podman_args.extend(args)
+
+    p = subprocess.Popen(
+        podman_args,
+        env=None,
+        stdin=subprocess.PIPE if stdin_data is not None else subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        bufsize=MAX_BYTES_PER_READ,
+    )
+
+    set_nonblocking(p.stdout)
+    set_nonblocking(p.stderr)
+
+    write_ok = True
+    if stdin_data is not None:
+        set_nonblocking(p.stdin)
+        write_ok = await write_nonblocking_async(
+            fd=p.stdin,
+            data=stdin_data.encode(),
+            timeout_seconds=stdin_write_timeout
+            if stdin_write_timeout is not None
+            else 15,
+        )
+        try:
+            p.stdin.close()
+        except (BrokenPipeError, BlockingIOError):
+            pass
+
+    bufs = await read_to_eof_async(
+        [p.stdout, p.stderr],
+        timeout_seconds=timeout_seconds,
+        max_len=max_output_size,
+    )
+
+    # Busy-wait for the process to exit or the deadline. Why do we need this
+    # when read_to_eof_async seems to do this? read_to_eof_async will return
+    # when the process closes stdout and stderr, but the process can continue
+    # running even after that. So, we really need to wait for an exit code.
+    exit_code = None
+    is_timeout = False
+    while True:
+        rc = p.poll()
+        if rc is not None:
+            exit_code = rc
+            break
+        remaining = deadline - time.time()
+        if remaining <= 0:
+            is_timeout = True
+            break
+        await asyncio.sleep(min(0.05, remaining))
+
+    await _podman_rm(cidfile_path)
+    exit_code = (
+        -1 if is_timeout or (stdin_data is not None and not write_ok) else exit_code
+    )
+    return Result(
+        timeout=is_timeout,
+        exit_code=exit_code if exit_code is not None else -1,
+        stdout=bufs[0].decode(errors="ignore"),
+        stderr=bufs[1].decode(errors="ignore"),
+    )

bounded_subprocess/interactive.py

@@ -0,0 +1,170 @@
+"""
+Interactive subprocess wrapper with nonblocking stdin/stdout.
+"""
+
+from typeguard import typechecked
+from typing import List, Optional
+import time
+import errno
+import subprocess
+from .util import set_nonblocking, MAX_BYTES_PER_READ, write_loop_sync
+
+_SLEEP_AFTER_WOUND_BLOCK = 0.5
+
+
+class _InteractiveState:
+    """Shared implementation for synchronous and asynchronous interaction."""
+
+    def __init__(self, args: List[str], read_buffer_size: int) -> None:
+        popen = subprocess.Popen(
+            args,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            bufsize=MAX_BYTES_PER_READ,
+        )
+        set_nonblocking(popen.stdin)
+        set_nonblocking(popen.stdout)
+        self.popen = popen
+        self.read_buffer_size = read_buffer_size
+        self.stdout_saved_bytes = bytearray()
+
+    # --- low level helpers -------------------------------------------------
+    def poll(self) -> Optional[int]:
+        return self.popen.poll()
+
+    def close_pipes(self) -> None:
+        try:
+            self.popen.stdin.close()
+        except BlockingIOError:
+            pass
+        self.popen.stdout.close()
+
+    def kill(self) -> None:
+        self.popen.kill()
+
+    def return_code(self) -> int:
+        rc = self.popen.returncode
+        return rc if rc is not None else -9
+
+    def write_chunk(self, data: memoryview) -> tuple[int, bool]:
+        try:
+            written = self.popen.stdin.write(data)
+            self.popen.stdin.flush()
+            return written, True
+        except BlockingIOError as exn:
+            if exn.errno != errno.EAGAIN:
+                return exn.characters_written, False
+            return exn.characters_written, True
+        except BrokenPipeError:
+            return 0, False
+
+    def read_chunk(self) -> Optional[bytes]:
+        return self.popen.stdout.read(MAX_BYTES_PER_READ)
+
+    def pop_line(self, start_idx: int) -> Optional[bytes]:
+        newline_index = self.stdout_saved_bytes.find(b"\n", start_idx)
+        if newline_index == -1:
+            return None
+        line = memoryview(self.stdout_saved_bytes)[:newline_index].tobytes()
+        del self.stdout_saved_bytes[: newline_index + 1]
+        return line
+
+    def append_stdout(self, data: bytes) -> None:
+        self.stdout_saved_bytes.extend(data)
+
+    def trim_stdout(self) -> None:
+        if len(self.stdout_saved_bytes) > self.read_buffer_size:
+            del self.stdout_saved_bytes[
+                : len(self.stdout_saved_bytes) - self.read_buffer_size
+            ]
+
+
+@typechecked
+class Interactive:
+    """
+    Interact with a subprocess using nonblocking I/O.
+
+    The subprocess is started with pipes for stdin and stdout. Writes are
+    bounded by a timeout, and reads return complete lines (without the trailing
+    newline). The internal buffer is capped at `read_buffer_size`; older bytes
+    are dropped if output grows without line breaks.
+
+    Example:
+
+    ```python
+    from bounded_subprocess.interactive import Interactive
+
+    proc = Interactive(["python3", "-u", "-c", "print(input())"], read_buffer_size=4096)
+    ok = proc.write(b"hello\n", timeout_seconds=1)
+    line = proc.read_line(timeout_seconds=1)
+    rc = proc.close(nice_timeout_seconds=1)
+    ```
+    """
+
+    def __init__(self, args: List[str], read_buffer_size: int) -> None:
+        """
+        Start a subprocess with a bounded stdout buffer.
+
+        The child process is created with nonblocking stdin/stdout pipes. The
+        internal read buffer keeps at most `read_buffer_size` bytes of recent
+        output.
+        """
+        self._state = _InteractiveState(args, read_buffer_size)
+
+    def close(self, nice_timeout_seconds: int) -> int:
+        """
+        Close pipes, wait briefly, then kill the subprocess.
+
+        Returns the subprocess return code, or -9 if the process is still
+        running when it is killed.
+        """
+        self._state.close_pipes()
+        for _ in range(nice_timeout_seconds):
+            if self._state.poll() is not None:
+                break
+            time.sleep(1)
+        self._state.kill()
+        return self._state.return_code()
+
+    def write(self, stdin_data: bytes, timeout_seconds: int) -> bool:
+        """
+        Write `stdin_data` to the subprocess within `timeout_seconds`.
+
+        Returns False if the subprocess has already exited or if writing fails.
+        """
+        if self._state.poll() is not None:
+            return False
+        return write_loop_sync(
+            self._state.write_chunk,
+            stdin_data,
+            timeout_seconds,
+            sleep_interval=_SLEEP_AFTER_WOUND_BLOCK,
+        )
+
+    def read_line(self, timeout_seconds: int) -> Optional[bytes]:
+        """
+        Read the next line from stdout, or return None on timeout/EOF.
+
+        The returned line does not include the trailing newline byte.
+        """
+        line = self._state.pop_line(0)
+        if line is not None:
+            return line
+        if self._state.poll() is not None:
+            return None
+        deadline = time.time() + timeout_seconds
+        while time.time() < deadline:
+            new_bytes = self._state.read_chunk()
+            if new_bytes is None:
+                time.sleep(_SLEEP_AFTER_WOUND_BLOCK)
+                continue
+            if len(new_bytes) == 0:
+                return None
+            prev_len = len(self._state.stdout_saved_bytes)
+            self._state.append_stdout(new_bytes)
+            line = self._state.pop_line(prev_len)
+            if line is not None:
+                return line
+            self._state.trim_stdout()
+            time.sleep(_SLEEP_AFTER_WOUND_BLOCK)
+        return None

bounded_subprocess/interactive_async.py

@@ -0,0 +1,91 @@
+from typeguard import typechecked
+from typing import List, Optional
+import asyncio
+import time
+from .interactive import _InteractiveState
+from .util import write_nonblocking_async, can_read, MAX_BYTES_PER_READ
+
+
+@typechecked
+class Interactive:
+    """Asynchronous interface for interacting with a subprocess."""
+
+    def __init__(self, args: List[str], read_buffer_size: int) -> None:
+        self._state = _InteractiveState(args, read_buffer_size)
+
+    async def close(self, nice_timeout_seconds: int) -> int:
+        self._state.close_pipes()
+        for _ in range(nice_timeout_seconds):
+            if self._state.poll() is not None:
+                break
+            await asyncio.sleep(1)
+        self._state.kill()
+        return self._state.return_code()
+
+    async def write(self, stdin_data: bytes, timeout_seconds: int) -> bool:
+        if self._state.poll() is not None:
+            return False
+        return await write_nonblocking_async(
+            fd=self._state.popen.stdin,
+            data=stdin_data,
+            timeout_seconds=timeout_seconds,
+        )
+
+    # I think I have reinvented buffered line reading. I dimly recall studying
+    # this in excruciating detail in CS153. The difference here is that there
+    # is a bunch of extra work to avoid blocking, a timeout, and a limit on
+    # how long a received line can be.
+    async def read_line(self, timeout_seconds: int) -> Optional[bytes]:
+        # First, try to read a line from the internal buffer. The zero argument
+        # indicates where to *start looking for a newline*. The returned line
+        # always begins from the start of the buffer. This is an optimization
+        # for the loop below.
+        line = self._state.pop_line(0)
+        if line is not None:
+            return line
+
+        if self._state.poll() is not None:
+            return None
+
+        deadline = time.time() + timeout_seconds
+        while time.time() < deadline:
+            # Non-blocking wait until bytes are available, or we reach the
+            # deadline.
+            try:
+                can_read_timeout = deadline - time.time()
+                if can_read_timeout <= 0:
+                    return None
+                await asyncio.wait_for(
+                    can_read(self._state.popen.stdout),
+                    timeout=can_read_timeout,
+                )
+            except asyncio.TimeoutError:
+                return None
+
+            new_bytes = self._state.popen.stdout.read(MAX_BYTES_PER_READ)
+
+            # We append the received bytes to the buffer, and look for a newline.
+            # As an optimization, we only look for a newline in the received
+            # bytes.
+            prev_len = len(self._state.stdout_saved_bytes)
+            self._state.append_stdout(new_bytes)
+            line = self._state.pop_line(prev_len)
+            if line is not None:
+                return line
+
+            if len(new_bytes) == 0:
+                # Closed pipe before newline. We do *not* return the final
+                # bit of text that we received. But, we do clear our internal
+                # buffer.
+
+                # Alternative design: we could return the following
+                # last_incomplete_line = memoryview(self._state.stdout_saved_bytes).tobytes()
+                self._state.stdout_saved_bytes.clear()
+                return None
+
+            # We cap the size of the received line. This will make things go
+            # wrong if we are getting structured output (e.g., JSON) from the
+            # subprocess. However, it prevents the subprocess from making us
+            # run out of memory.
+            self._state.trim_stdout()
+        return None

bounded_subprocess/util.py

@@ -0,0 +1,296 @@
+"""
+Utilities for bounded subprocess I/O and nonblocking pipe helpers.
+"""
+
+import subprocess
+import os
+import fcntl
+import signal
+from typing import Callable, List, Optional
+import errno
+import time
+import asyncio
+import dataclasses
+import select
+
+MAX_BYTES_PER_READ = 1024
+SLEEP_BETWEEN_READS = 0.1
+SLEEP_BETWEEN_WRITES = 0.01
+
+
+@dataclasses.dataclass
+class Result:
+    """
+    Result of a bounded subprocess run.
+
+    The `stdout` and `stderr` fields contain at most the requested number of
+    bytes, decoded with errors ignored. `timeout` is True only when the overall
+    timeout elapses. When a timeout or stdin write failure occurs, `exit_code`
+    is -1.
+    """
+
+    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):
+    """
+    Mark a file descriptor as nonblocking.
+
+    This is required before using the read/write helpers that rely on
+    nonblocking behavior.
+    """
+    fd = reader.fileno()
+    fl = fcntl.fcntl(fd, fcntl.F_GETFL)
+    fcntl.fcntl(fd, fcntl.F_SETFL, fl | os.O_NONBLOCK)
+
+
+def write_loop_sync(
+    write_chunk: Callable[[memoryview], tuple[int, bool]],
+    data: bytes,
+    timeout_seconds: float,
+    *,
+    sleep_interval: float,
+) -> bool:
+    """
+    Repeatedly write data using `write_chunk` until complete or timeout.
+
+    The `write_chunk` callback returns `(bytes_written, keep_going)`. If
+    `keep_going` is False, this function returns False immediately.
+    """
+    mv = memoryview(data)
+    start = 0
+    start_time = time.time()
+    while start < len(mv):
+        written, keep_going = write_chunk(mv[start:])
+        start += written
+        if not keep_going:
+            return False
+        if start < len(mv):
+            if time.time() - start_time > timeout_seconds:
+                return False
+            time.sleep(sleep_interval)
+    return True
+
+
+async def can_write(fd):
+    """
+    Wait until the file descriptor is writable.
+    """
+    future = asyncio.Future()
+    loop = asyncio.get_running_loop()
+    loop.add_writer(fd, future.set_result, None)
+    future.add_done_callback(lambda f: loop.remove_writer(fd))
+    await future
+
+
+async def can_read(fd):
+    """
+    Wait until the file descriptor is readable.
+    """
+    future = asyncio.Future()
+    loop = asyncio.get_running_loop()
+    loop.add_reader(fd, future.set_result, None)
+    future.add_done_callback(lambda f: loop.remove_reader(fd))
+    await future
+
+
+async def write_nonblocking_async(*, fd, data: bytes, timeout_seconds: int) -> bool:
+    """
+    Writes to a nonblocking file descriptor with the timeout.
+
+    Returns True if all the data was written. False indicates that there was
+    either a timeout or a broken pipe.
+
+    This function does not close the file descriptor.
+    """
+    start_time_seconds = time.time()
+
+    # A slice, data[..], would create a copy. A memoryview does not.
+    mv = memoryview(data)
+    start = 0
+    while start < len(mv):
+        try:
+            # Write as much as possible without blocking.
+            written = fd.write(mv[start:])
+            if written is None:
+                written = 0
+            start = start + written
+        except BrokenPipeError:
+            return False
+        except BlockingIOError as exn:
+            if exn.errno != errno.EAGAIN:
+                # NOTE(arjun): I am not certain why this would happen. However,
+                # you are only supposed to retry on EAGAIN.
+                return False
+            # Some, but not all the bytes were written.
+            start = start + exn.characters_written
+
+            # Compute how much more time we have left.
+            wait_timeout = timeout_seconds - (time.time() - start_time_seconds)
+            # We are already past the deadline, so abort.
+            if wait_timeout <= 0:
+                return False
+            try:
+                await asyncio.wait_for(can_write(fd), wait_timeout)
+            except asyncio.TimeoutError:
+                # Deadline elapsed, so abort.
+                return False
+
+    return True
+
+
+def read_to_eof_sync(
+    files: list,
+    *,
+    timeout_seconds: int,
+    max_len: int,
+) -> Optional[List[bytes]]:
+    """
+    Read from nonblocking file descriptors until EOF, with limits on how long
+    to wait and the maximum number of bytes to read.
+
+    Returns the data read, or None if the timeout elapsed.
+    """
+    bufs = {fd: bytearray() for fd in files}
+    avail = set(files)
+    end_at = time.time() + timeout_seconds
+
+    while avail and time.time() < end_at:
+        # Wait only as long as we still have time left
+        remaining = max(0, end_at - time.time())
+        ready, _, _ = select.select(avail, [], [], remaining)
+        if not ready:
+            break
+        for fd in ready:
+            try:
+                chunk = fd.read(MAX_BYTES_PER_READ)
+                if not chunk:
+                    # Reached EOF, so we can stop reading from this file.
+                    avail.discard(fd)
+                    continue
+                the_buf = bufs[fd]
+                # Keep at most max_len bytes, silently dropping any extra bytes.
+                if len(the_buf) < max_len:
+                    keep = max_len - len(the_buf)
+                    the_buf.extend(chunk[:keep])
+            except (BlockingIOError, InterruptedError):
+                # Would-block, so we can't read from this file.
+                pass
+            except OSError:
+                # Broken pipe, bad fd, etc.
+                avail.discard(fd)
+
+    # Preserve the caller-supplied order
+    return [bytes(bufs[fd]) for fd in files]
+
+
+async def _wait_for_any_read(fds, timeout: float):
+    """Wait until any of the fds is readable or the timeout elapses."""
+    loop = asyncio.get_running_loop()
+    fut = loop.create_future()
+
+    def make_cb(fd):
+        return lambda: (not fut.done()) and fut.set_result(fd)
+
+    for fd in fds:
+        loop.add_reader(fd.fileno(), make_cb(fd))
+    try:
+        return await asyncio.wait_for(fut, timeout)
+    except asyncio.TimeoutError:
+        return None
+    finally:
+        for fd in fds:
+            loop.remove_reader(fd.fileno())
+
+
+async def read_to_eof_async(
+    files: list,
+    *,
+    timeout_seconds: int,
+    max_len: int,
+) -> List[bytes]:
+    """
+    Asynchronously read from nonblocking FDs until EOF or timeout.
+
+    The returned list preserves the order of the `files` argument.
+    """
+    bufs = {fd: bytearray() for fd in files}
+    avail = list(files)
+    end_at = time.time() + timeout_seconds
+
+    while avail and time.time() < end_at:
+        remaining = max(0, end_at - time.time())
+        fd = await _wait_for_any_read(avail, remaining)
+        if fd is None:
+            break
+        try:
+            chunk = fd.read(MAX_BYTES_PER_READ)
+            if not chunk:
+                avail.remove(fd)
+                continue
+            buf = bufs[fd]
+            if len(buf) < max_len:
+                keep = max_len - len(buf)
+                buf.extend(chunk[:keep])
+        except (BlockingIOError, InterruptedError):
+            pass
+        except OSError:
+            avail.remove(fd)
+
+    return [bytes(bufs[fd]) for fd in files]
+
+
+# This function is very similar to write_nonblocking_async. But, in my
+# opinion, trying to build an abstraction that works for both sync and async
+# code is painful and a deficiency of Python.
+def write_nonblocking_sync(*, fd, data: bytes, timeout_seconds: int) -> bool:
+    """
+    Writes to a nonblocking file descriptor with the timeout.
+
+    Returns True if all the data was written. False indicates that there was
+    either a timeout or a broken pipe.
+
+    This function does not close the file descriptor.
+    """
+    start_time_seconds = time.time()
+
+    # A slice, data[..], would create a copy. A memoryview does not.
+    mv = memoryview(data)
+    start = 0
+    while start < len(mv):
+        try:
+            # Write as much as possible without blocking.
+            written = fd.write(mv[start:])
+            if written is None:
+                written = 0
+            start = start + written
+        except BrokenPipeError:
+            return False
+        except BlockingIOError as exn:
+            if exn.errno != errno.EAGAIN:
+                # NOTE(arjun): I am not certain why this would happen. However,
+                # you are only supposed to retry on EAGAIN.
+                return False
+            # Some, but not all the bytes were written.
+            start = start + exn.characters_written
+
+            # Compute how much more time we have left.
+            wait_timeout = timeout_seconds - (time.time() - start_time_seconds)
+            # We are already past the deadline, so abort.
+            if wait_timeout <= 0:
+                return False
+            select_result = select.select([], [fd], [], wait_timeout)
+            if len(select_result[1]) == 0:
+                # Deadline elapsed, so abort.
+                return False
+
+    return True

bounded_subprocess-2.5.0.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: bounded_subprocess
+Version: 2.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.
+
+- Documentation: https://arjunguha.github.io/bounded_subprocess/
+
+## 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-2.5.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+bounded_subprocess/__init__.py,sha256=7JId4_SDjbLML7vUWIFT9CRmCr7IRwxk6YbXaD2pgQk,832
+bounded_subprocess/bounded_subprocess.py,sha256=z9bdQwdIP-0aNJwqyaY9Gq_ZKg9b7-Nd_97xGLZy9rQ,3691
+bounded_subprocess/bounded_subprocess_async.py,sha256=IqQxp4skfVpX3FWfwRy84lWAzDEKzgw1zYcMyihYD8c,8603
+bounded_subprocess/interactive.py,sha256=IK6G0SaIhsd2T7mmXc6ofF0Ehz0Xfnwl0e6fPjXqwyM,5662
+bounded_subprocess/interactive_async.py,sha256=DZZnZBTJd7xWdhQmdMmWkPOoCYVdMpR-LMY9AzvMdW4,3675
+bounded_subprocess/util.py,sha256=mQZ7mmjl5sTB3oSa8XetDErtfdRUNffaCIMuxMu4L90,9117
+bounded_subprocess-2.5.0.dist-info/METADATA,sha256=IAXP0pdI8458SM17I687Tir_HtiNjdvX9Qsx3wdlI_A,2730
+bounded_subprocess-2.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+bounded_subprocess-2.5.0.dist-info/licenses/LICENSE.txt,sha256=UVerBV0_1vMFt8QkaXuVnZVSlOiKDiBSieK5MNLy4Ls,1086
+bounded_subprocess-2.5.0.dist-info/RECORD,,

bounded_subprocess-2.5.0.dist-info/WHEEL

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

bounded_subprocess-2.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.