bounded_subprocess 2.4.0__tar.gz

bounded_subprocess-2.4.0/.git

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

bounded_subprocess-2.4.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.4.0/.github/workflows/test.yml

@@ -0,0 +1,19 @@
+name: Test
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5    
+    - name: Install the project
+      run: uv sync --locked --all-extras --dev
+    - name: Run tests
+      run: uv run python -m pytest -m "not unsafe"

bounded_subprocess-2.4.0/.gitignore

@@ -0,0 +1,5 @@
+*.pyc
+__pycache__
+/.venv
+/dist
+/bounded_subprocess.egg-info

bounded_subprocess-2.4.0/AGENTS.md

@@ -0,0 +1,5 @@
+## 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. 

bounded_subprocess-2.4.0/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.

bounded_subprocess-2.4.0/Makefile

@@ -0,0 +1,13 @@
+.PHONY: test build publish docs
+
+build:
+	uv build
+
+publish:
+	 uv publish
+
+test:
+	uv run python -m pytest -m "not unsafe"
+
+docs:
+	uv run mkdocs build

bounded_subprocess-2.4.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: bounded_subprocess
+Version: 2.4.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.4.0/README.md

@@ -0,0 +1,27 @@
+# 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.4.0/cspell.config.yaml

@@ -0,0 +1,23 @@
+version: "0.2"
+ignorePaths: []
+dictionaryDefinitions: []
+dictionaries: []
+words:
+- killpg
+- nonblocking
+- pgrep
+- GETFL
+- SETFL
+- NONBLOCK
+- getpgid
+- typeguard
+- tobytes
+- Arjun
+- Guha
+- pytest
+- Lucchetti
+- pythonpath
+- asyncio
+- bufs
+ignoreWords: []
+import: []

bounded_subprocess-2.4.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.4.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.4.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "bounded_subprocess"
+version = "2.4.0"
+authors = [
+  { name="Arjun Guha" },
+  { name="Ming-Ho Yee" },
+  { name="Francesca Lucchetti" }
+]
+description = "A library to facilitate running subprocesses that may misbehave."
+readme = "README.md"
+license = { file="LICENSE.txt" }
+requires-python = ">=3.9"
+dependencies =[
+  "typeguard>=4.4.2,<5.0.0"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+markers = [
+  "unsafe: Tests that may crash the machine on failure",
+]
+asyncio_default_fixture_loop_scope = "function"
+
+[project.urls]
+"Homepage" = "https://github.com/arjunguha/bounded_subprocess"
+"Bug Tracker" = "https://github.com/arjunguha/bounded_subprocess"
+
+[dependency-groups]
+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.4.0/src/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-2.4.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"),
+    )