bounded_subprocess 2.3.1__tar.gz → 2.5.0__tar.gz

bounded_subprocess-2.5.0/.git

@@ -0,0 +1 @@
+gitdir: /media/external0/arjun-nosudo/repos/arjunguha/bounded_subprocess/bare/worktrees/main

bounded_subprocess-2.5.0/.github/workflows/docs.yaml

@@ -0,0 +1,29 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+    - name: Install project
+      run: uv sync --locked --all-extras --dev
+    - name: Build MkDocs site
+      run: make docs
+    - name: Upload GitHub Pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: ./site
+    - name: Deploy to GitHub Pages
+      uses: actions/deploy-pages@v4
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}

bounded_subprocess-2.5.0/AGENTS.md

@@ -0,0 +1,10 @@
+Use `uv run`to run and not `python`.
+
+## Publishing Process
+
+Increment the version number as appropriate in pyproject.toml. Delete old
+builds from dist/. Run uv sync to update the lock file. Commit the changes,
+which should have just changes to pyproject.taml and uv.lock. Run `uv build`
+and then `uv publish`. In the interactive prompt, you MUST enter __token__
+for the username. I know it says that, but I don't read what's on the screen.
+The password is in the keychain.

{bounded_subprocess-2.3.1 → bounded_subprocess-2.5.0}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: test build publish
+.PHONY: test build publish docs
 
 build:
 	uv build
@@ -8,3 +8,6 @@ publish:
 
 test:
 	uv run python -m pytest -m "not unsafe"
+
+docs:
+	uv run mkdocs build

{bounded_subprocess-2.3.1 → bounded_subprocess-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bounded_subprocess
-Version: 2.3.1
+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
@@ -38,6 +38,8 @@ The `bounded-subprocess` module runs a subprocess with several bounds:
 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

{bounded_subprocess-2.3.1 → bounded_subprocess-2.5.0}/README.md

@@ -14,6 +14,8 @@ The `bounded-subprocess` module runs a subprocess with several bounds:
 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

{bounded_subprocess-2.3.1 → bounded_subprocess-2.5.0}/cspell.config.yaml

@@ -18,5 +18,6 @@ words:
 - Lucchetti
 - pythonpath
 - asyncio
+- bufs
 ignoreWords: []
 import: []

bounded_subprocess-2.5.0/docs/index.md

@@ -0,0 +1,11 @@
+# bounded_subprocess
+
+::: bounded_subprocess
+
+::: bounded_subprocess.bounded_subprocess
+
+::: bounded_subprocess.bounded_subprocess_async
+
+::: bounded_subprocess.interactive
+
+::: bounded_subprocess.util

bounded_subprocess-2.5.0/mkdocs.yaml

@@ -0,0 +1,67 @@
+site_name: bounded_subprocess
+site_description: Bounded subprocess execution with timeout and output limits
+
+theme:
+  name: material
+  locale: en
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - toc.integrate
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.highlight
+    - search.share
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - md_in_html
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: ["src"]
+          options:
+            show_signature_annotations: true
+            show_root_heading: true
+            heading_level: 2
+            docstring_style: google
+            merge_init_into_class: true
+
+nav:
+  - Home: index.md
+
+repo_url: https://github.com/arjunguha/bounded_subprocess
+repo_name: arjunguha/bounded_subprocess
+edit_uri: edit/main/docs/
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/arjunguha/bounded_subprocess
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/bounded-subprocess/

{bounded_subprocess-2.3.1 → bounded_subprocess-2.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bounded_subprocess"
-version = "2.3.1"
+version = "2.5.0"
 authors = [
   { name="Arjun Guha" },
   { name="Ming-Ho Yee" },
@@ -39,4 +39,7 @@ dev = [
     "pytest>=8.3.5",
     "pytest-asyncio>=1.0.0",
     "pytest-timeout>=2.4.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.6.15",
+    "mkdocstrings[python]>=0.29.1",
 ]

{bounded_subprocess-2.3.1 → bounded_subprocess-2.5.0}/src/bounded_subprocess/__init__.py

@@ -8,27 +8,24 @@ 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 == "BoundedSubprocessState": 
-        from .util import BoundedSubprocessState
-        return BoundedSubprocessState
     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", 
-    "BoundedSubprocessState",
-    "SLEEP_BETWEEN_READS"
-]
+__all__ = ["run", "Result", "SLEEP_BETWEEN_READS"]

bounded_subprocess-2.5.0/src/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-2.5.0/src/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"),
+    )