boxlite 0.3.0.post2__cp312-cp312-manylinux_2_28_x86_64.whl

boxlite/__init__.py

@@ -0,0 +1,92 @@
+"""
+BoxLite - Lightweight, secure containerization for any environment.
+
+Following SQLite philosophy: "BoxLite" for branding, "boxlite" for code APIs.
+"""
+
+import os
+import warnings
+from pathlib import Path
+
+# Import core Rust API
+try:
+    from .boxlite import (
+        Options,
+        BoxOptions,
+        Boxlite,
+        Box,
+        Execution,
+        ExecStdout,
+        ExecStderr,
+        BoxInfo,
+        RuntimeMetrics,
+        BoxMetrics,
+    )
+
+    __all__ = [
+        # Core Rust API
+        "Options",
+        "BoxOptions",
+        "Boxlite",
+        "Box",
+        "Execution",
+        "ExecStdout",
+        "ExecStderr",
+        "BoxInfo",
+        "RuntimeMetrics",
+        "BoxMetrics",
+    ]
+except ImportError as e:
+    warnings.warn(f"BoxLite native extension not available: {e}", ImportWarning)
+    __all__ = []
+
+# Import Python convenience wrappers
+try:
+    from .simplebox import SimpleBox
+    from .exec import ExecResult
+    from .codebox import CodeBox
+    from .errors import BoxliteError, ExecError, TimeoutError, ParseError
+
+    __all__.extend([
+        # Python convenience wrappers
+        "SimpleBox",
+        "CodeBox",
+        "ExecResult",
+        # Error types
+        "BoxliteError",
+        "ExecError",
+        "TimeoutError",
+        "ParseError",
+    ])
+except ImportError:
+    pass
+
+# Specialized containers
+try:
+    from .browserbox import BrowserBox, BrowserBoxOptions
+
+    __all__.extend(["BrowserBox", "BrowserBoxOptions"])
+except ImportError:
+    pass
+
+try:
+    from .computerbox import ComputerBox
+
+    __all__.extend(["ComputerBox"])
+except ImportError:
+    pass
+
+try:
+    from .interactivebox import InteractiveBox
+
+    __all__.extend(["InteractiveBox"])
+except ImportError:
+    pass
+
+# Get version from package metadata
+try:
+    from importlib.metadata import version, PackageNotFoundError
+    __version__ = version("boxlite")
+except PackageNotFoundError:
+    # Package not installed (e.g., development mode)
+    __version__ = "0.0.0+dev"

boxlite/browserbox.py

@@ -0,0 +1,138 @@
+"""
+BrowserBox - Secure browser with remote debugging.
+
+Provides a minimal, elegant API for running isolated browsers that can be
+controlled from outside using standard tools like Puppeteer or Playwright.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, TYPE_CHECKING
+
+from .simplebox import SimpleBox, StreamType
+
+if TYPE_CHECKING:
+    from .boxlite import Boxlite
+
+__all__ = ["BrowserBox", "BrowserBoxOptions"]
+
+
+@dataclass
+class BrowserBoxOptions:
+    """
+    Configuration for BrowserBox.
+
+    Example:
+        >>> opts = BrowserBoxOptions(
+        ...     browser="chromium",
+        ...     memory=2048,
+        ...     cpu=2
+        ... )
+        >>> async with BrowserBox(opts) as browser:
+        ...     print(browser.endpoint())
+    """
+    browser: str = "chromium"  # chromium, firefox, or webkit
+    memory: int = 2048  # Memory in MiB
+    cpu: int = 2  # Number of CPU cores
+
+
+class BrowserBox(SimpleBox):
+    """
+    Secure browser environment with remote debugging.
+
+    Auto-starts a browser with Chrome DevTools Protocol enabled.
+    Connect from outside using Puppeteer, Playwright, Selenium, or DevTools.
+
+    Usage:
+        >>> async with BrowserBox() as browser:
+        ...     print(f"Connect to: {browser.endpoint()}")
+        ...     # Use Puppeteer/Playwright from your host to connect
+        ...     await asyncio.sleep(60)
+
+    Example with custom options:
+        >>> opts = BrowserBoxOptions(browser="firefox", memory=4096)
+        >>> async with BrowserBox(opts) as browser:
+        ...     endpoint = browser.endpoint()
+    """
+
+    # Default Playwright images (with retry logic now!)
+    _DEFAULT_IMAGE = "mcr.microsoft.com/playwright:v1.47.2-jammy"
+
+    # CDP port for each browser type
+    _PORTS = {"chromium": 9222, "firefox": 9223, "webkit": 9224}
+
+    def __init__(self, options: Optional[BrowserBoxOptions] = None,
+                 runtime: Optional['Boxlite'] = None,
+                 **kwargs):
+        """
+        Create and auto-start a browser.
+
+        Args:
+            options: Browser configuration (uses defaults if None)
+            runtime: Optional runtime instance (uses global default if None)
+            **kwargs: Additional configuration options (volumes, env, etc.)
+        """
+        opts = options or BrowserBoxOptions()
+
+        self._browser = opts.browser
+        self._port = self._PORTS.get(opts.browser, 9222)
+
+        # Initialize base box
+        super().__init__(
+            image=self._DEFAULT_IMAGE,
+            memory_mib=opts.memory,
+            cpus=opts.cpu,
+            runtime=runtime,
+            **kwargs
+        )
+
+    async def __aenter__(self):
+        """Start browser automatically on context enter."""
+        await super().__aenter__()
+        await self._start_browser()
+        return self
+
+    async def _start_browser(self):
+        """Internal: Start browser with remote debugging."""
+        if self._browser == "chromium":
+            binary = "/ms-playwright/chromium-*/chrome-linux/chrome"
+            cmd = (
+                f"{binary} --headless --no-sandbox --disable-dev-shm-usage "
+                f"--disable-gpu --remote-debugging-address=0.0.0.0 "
+                f"--remote-debugging-port={self._port} "
+                f"> /tmp/browser.log 2>&1 &"
+            )
+        elif self._browser == "firefox":
+            binary = "/ms-playwright/firefox-*/firefox/firefox"
+            cmd = (
+                f"{binary} --headless "
+                f"--remote-debugging-port={self._port} "
+                f"> /tmp/browser.log 2>&1 &"
+            )
+        else:  # webkit
+            cmd = (
+                f"playwright run-server --browser webkit "
+                f"--port {self._port} > /tmp/browser.log 2>&1 &"
+            )
+
+        # Start browser in background
+        await self.exec("sh", "-c", f"nohup {cmd}")
+
+        # Wait for browser to be ready
+        await self.exec("sleep", "3")
+
+    def endpoint(self) -> str:
+        """
+        Get the connection endpoint for remote debugging.
+
+        Returns:
+            HTTP endpoint URL for Chrome DevTools Protocol
+
+        Example:
+            >>> async with BrowserBox() as browser:
+            ...     url = browser.endpoint()
+            ...     # Use with Puppeteer:
+            ...     # puppeteer.connect({ browserURL: url })
+            ...     # Use with Playwright:
+            ...     # chromium.connect_over_cdp(url)
+        """
+        return f"http://localhost:{self._port}"

boxlite/codebox.py

@@ -0,0 +1,120 @@
+"""
+CodeBox - Secure Python code execution container.
+
+Provides a simple, secure environment for running untrusted Python code.
+"""
+
+from typing import Optional, TYPE_CHECKING
+
+from .simplebox import SimpleBox
+
+if TYPE_CHECKING:
+    from .boxlite import Boxlite
+
+
+class CodeBox(SimpleBox):
+    """
+    Secure container for executing Python code.
+
+    CodeBox provides an isolated environment for running untrusted Python code
+    with built-in safety and result formatting.
+
+    Usage:
+        >>> async with CodeBox() as cb:
+        ...     result = await cb.run("print('Hello, World!')")
+    """
+
+    def __init__(
+            self,
+            image: str = "python:slim",
+            memory_mib: Optional[int] = None,
+            cpus: Optional[int] = None,
+            runtime: Optional['Boxlite'] = None,
+            **kwargs
+    ):
+        """
+        Create a new CodeBox.
+
+        Args:
+            image: Container images with Python (default: python:slim)
+            memory_mib: Memory limit in MiB (default: system default)
+            cpus: Number of CPU cores (default: system default)
+            runtime: Optional runtime instance (uses global default if None)
+            **kwargs: Additional configuration options
+        """
+        super().__init__(image, memory_mib, cpus, runtime, **kwargs)
+
+    async def run(self, code: str, timeout: Optional[int] = None) -> str:
+        """
+        Execute Python code in the secure container.
+
+        Args:
+            code: Python code to execute
+            timeout: Execution timeout in seconds (not yet implemented)
+
+        Returns:
+            Execution output as a string (stdout + stderr)
+
+        Example:
+            >>> async with CodeBox() as cb:
+            ...     result = await cb.run("print('Hello, World!')")
+            ...     print(result)
+            Hello, World!
+
+        Note:
+            Uses python3 from the container images.
+            For custom Python paths, use exec() directly:
+                result = await cb.exec("/path/to/python", "-c", code)
+        """
+        # Execute Python code using python3 -c
+        result = await self.exec("/usr/local/bin/python", "-c", code)
+        return result.stdout + result.stderr
+
+    async def run_script(self, script_path: str) -> str:
+        """
+        Execute a Python script file in the container.
+
+        Args:
+            script_path: Path to the Python script on the host
+
+        Returns:
+            Execution output as a string
+        """
+        with open(script_path, 'r') as f:
+            code = f.read()
+        return await self.run(code)
+
+    async def install_package(self, package: str) -> str:
+        """
+        Install a Python package in the container using pip.
+
+        Args:
+            package: Package name (e.g., 'requests', 'numpy==1.24.0')
+
+        Returns:
+            Installation output
+
+        Example:
+            >>> async with CodeBox() as cb:
+            ...     await cb.install_package("requests")
+            ...     result = await cb.run("import requests; print(requests.__version__)")
+        """
+        result = await self.exec("pip", "install", package)
+        return result.stdout + result.stderr
+
+    async def install_packages(self, *packages: str) -> str:
+        """
+        Install multiple Python packages.
+
+        Args:
+            *packages: Package names to install
+
+        Returns:
+            Installation output
+
+        Example:
+            >>> async with CodeBox() as cb:
+            ...     await cb.install_packages("requests", "numpy", "pandas")
+        """
+        result = await self.exec("pip", "install", *packages)
+        return result.stdout + result.stderr