boxlite 0.5.7__cp312-cp312-macosx_14_0_arm64.whl

boxlite/__init__.py

@@ -0,0 +1,123 @@
+"""
+BoxLite - Lightweight, secure containerization for any environment.
+
+Following SQLite philosophy: "BoxLite" for branding, "boxlite" for code APIs.
+"""
+
+import warnings
+
+# Import core Rust API
+try:
+    from .boxlite import (
+        Options,
+        BoxOptions,
+        Boxlite,
+        Box,
+        Execution,
+        ExecStdout,
+        ExecStderr,
+        BoxInfo,
+        BoxStateInfo,
+        RuntimeMetrics,
+        BoxMetrics,
+    )
+
+    __all__ = [
+        # Core Rust API
+        "Options",
+        "BoxOptions",
+        "Boxlite",
+        "Box",
+        "Execution",
+        "ExecStdout",
+        "ExecStderr",
+        "BoxInfo",
+        "BoxStateInfo",
+        "RuntimeMetrics",
+        "BoxMetrics",
+    ]
+except ImportError as e:
+    warnings.warn(f"BoxLite native extension not available: {e}", ImportWarning)
+    __all__ = []
+
+# Import Python convenience wrappers (re-exported via __all__)
+try:
+    from .simplebox import SimpleBox  # noqa: F401
+    from .exec import ExecResult  # noqa: F401
+    from .codebox import CodeBox  # noqa: F401
+    from .errors import BoxliteError, ExecError, TimeoutError, ParseError  # noqa: F401
+
+    __all__.extend(
+        [
+            # Python convenience wrappers
+            "SimpleBox",
+            "CodeBox",
+            "ExecResult",
+            # Error types
+            "BoxliteError",
+            "ExecError",
+            "TimeoutError",
+            "ParseError",
+        ]
+    )
+except ImportError:
+    pass
+
+# Specialized containers (re-exported via __all__)
+try:
+    from .browserbox import BrowserBox, BrowserBoxOptions  # noqa: F401
+
+    __all__.extend(["BrowserBox", "BrowserBoxOptions"])
+except ImportError:
+    pass
+
+try:
+    from .computerbox import ComputerBox  # noqa: F401
+
+    __all__.extend(["ComputerBox"])
+except ImportError:
+    pass
+
+try:
+    from .interactivebox import InteractiveBox  # noqa: F401
+
+    __all__.extend(["InteractiveBox"])
+except ImportError:
+    pass
+
+# Sync API (greenlet-based synchronous wrappers, re-exported via __all__)
+# Requires greenlet: pip install boxlite[sync]
+try:
+    from .sync_api import (  # noqa: F401
+        SyncBoxlite,
+        SyncBox,
+        SyncExecution,
+        SyncExecStdout,
+        SyncExecStderr,
+        SyncSimpleBox,
+        SyncCodeBox,
+    )
+
+    __all__.extend(
+        [
+            "SyncBoxlite",
+            "SyncBox",
+            "SyncExecution",
+            "SyncExecStdout",
+            "SyncExecStderr",
+            "SyncSimpleBox",
+            "SyncCodeBox",
+        ]
+    )
+except ImportError:
+    # greenlet not installed - sync API not available
+    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,142 @@
+"""
+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
+
+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

boxlite/computerbox.py

@@ -0,0 +1,302 @@
+"""
+ComputerBox - Desktop environment with web access.
+
+Provides a minimal, elegant API for running isolated desktop environments
+that can be viewed from a browser, with full GUI automation support.
+"""
+
+import asyncio
+import logging
+from typing import Optional, Tuple, TYPE_CHECKING
+
+from . import constants as const
+from .errors import ExecError, TimeoutError, ParseError
+from .simplebox import SimpleBox
+
+if TYPE_CHECKING:
+    from .boxlite import Boxlite
+
+__all__ = ["ComputerBox"]
+
+logger = logging.getLogger("boxlite.computerbox")
+
+
+class ComputerBox(SimpleBox):
+    """
+    Desktop environment accessible via web browser.
+
+    Auto-starts a full desktop environment with web interface.
+    Access the desktop by opening the URL in your browser.
+
+    Note: Uses HTTPS with self-signed certificate - your browser will show
+    a security warning. Click "Advanced" and "Proceed" to access the desktop.
+
+    Usage:
+        >>> async with ComputerBox() as desktop:
+        ...     await desktop.wait_until_ready()
+        ...     screenshot = await desktop.screenshot()
+
+    Example with custom settings:
+        >>> async with ComputerBox(memory=4096, cpu=4) as desktop:
+        ...     await desktop.mouse_move(100, 200)
+        ...     await desktop.left_click()
+    """
+
+    def __init__(
+        self,
+        cpu: int = const.COMPUTERBOX_CPUS,
+        memory: int = const.COMPUTERBOX_MEMORY_MIB,
+        gui_http_port: int = const.COMPUTERBOX_GUI_HTTP_PORT,
+        gui_https_port: int = const.COMPUTERBOX_GUI_HTTPS_PORT,
+        runtime: Optional["Boxlite"] = None,
+        **kwargs,
+    ):
+        """
+        Create and auto-start a desktop environment.
+
+        Args:
+            cpu: Number of CPU cores (default: 2)
+            memory: Memory in MiB (default: 2048)
+            gui_http_port: Port for HTTP desktop GUI (default: 3000)
+            gui_https_port: Port for HTTPS desktop GUI (default: 3001)
+            runtime: Optional runtime instance (uses global default if None)
+            **kwargs: Additional configuration options (volumes, etc.)
+        """
+        user_env = kwargs.pop("env", [])
+        default_env = [
+            ("DISPLAY", const.COMPUTERBOX_DISPLAY_NUMBER),
+            ("DISPLAY_SIZEW", str(const.COMPUTERBOX_DISPLAY_WIDTH)),
+            ("DISPLAY_SIZEH", str(const.COMPUTERBOX_DISPLAY_HEIGHT)),
+            ("SELKIES_MANUAL_WIDTH", str(const.COMPUTERBOX_DISPLAY_WIDTH)),
+            ("SELKIES_MANUAL_HEIGHT", str(const.COMPUTERBOX_DISPLAY_HEIGHT)),
+            ("SELKIES_UI_SHOW_SIDEBAR", "false"),
+        ]
+
+        user_ports = kwargs.pop("ports", [])
+        default_ports = [
+            (gui_http_port, const.COMPUTERBOX_GUI_HTTP_PORT),
+            (gui_https_port, const.COMPUTERBOX_GUI_HTTPS_PORT),
+        ]
+
+        super().__init__(
+            image=const.COMPUTERBOX_IMAGE,
+            memory_mib=memory,
+            cpus=cpu,
+            runtime=runtime,
+            env=default_env + list(user_env),
+            ports=default_ports + list(user_ports),
+            **kwargs,
+        )
+
+    async def wait_until_ready(self, timeout: int = const.DESKTOP_READY_TIMEOUT):
+        """
+        Wait until the desktop environment is fully loaded and ready.
+
+        Args:
+            timeout: Maximum time to wait in seconds (default: 60)
+
+        Raises:
+            TimeoutError: If desktop doesn't become ready within timeout period
+        """
+        logger.info("Waiting for desktop to become ready...")
+        import time
+
+        start_time = time.time()
+
+        while True:
+            elapsed = time.time() - start_time
+            if elapsed > timeout:
+                raise TimeoutError(
+                    f"Desktop did not become ready within {timeout} seconds"
+                )
+
+            try:
+                exec_result = await self.exec("xwininfo", "-tree", "-root")
+                expected_size = f"{const.COMPUTERBOX_DISPLAY_WIDTH}x{const.COMPUTERBOX_DISPLAY_HEIGHT}"
+
+                if (
+                    "xfdesktop" in exec_result.stdout
+                    and expected_size in exec_result.stdout
+                ):
+                    logger.info(f"Desktop ready after {elapsed:.1f} seconds")
+                    return
+
+                logger.debug(
+                    f"Desktop not ready yet (waited {elapsed:.1f}s), retrying..."
+                )
+                await asyncio.sleep(const.DESKTOP_READY_RETRY_DELAY)
+
+            except (ExecError, ConnectionError, OSError, asyncio.TimeoutError) as e:
+                logger.debug(f"Desktop not ready: {e}, retrying...")
+                await asyncio.sleep(const.DESKTOP_READY_RETRY_DELAY)
+            except Exception as e:
+                logger.error(f"Fatal error in wait_until_ready: {e}")
+                raise
+
+    async def screenshot(self) -> dict:
+        """
+        Capture a screenshot of the desktop.
+
+        Returns:
+            Dictionary with: data (base64 PNG), width, height, format
+        """
+        logger.info("Taking screenshot...")
+
+        python_code = """
+from PIL import ImageGrab
+import io
+import base64
+img = ImageGrab.grab()
+buffer = io.BytesIO()
+img.save(buffer, format="PNG")
+print(base64.b64encode(buffer.getvalue()).decode("utf-8"))
+"""
+        exec_result = await self.exec("python3", "-c", python_code)
+
+        if exec_result.exit_code != 0:
+            raise ExecError("screenshot()", exec_result.exit_code, exec_result.stderr)
+
+        return {
+            "data": exec_result.stdout.strip(),
+            "width": const.COMPUTERBOX_DISPLAY_WIDTH,
+            "height": const.COMPUTERBOX_DISPLAY_HEIGHT,
+            "format": "png",
+        }
+
+    async def mouse_move(self, x: int, y: int):
+        """Move mouse cursor to absolute coordinates."""
+        exec_result = await self.exec("xdotool", "mousemove", str(x), str(y))
+        if exec_result.exit_code != 0:
+            raise ExecError(
+                f"mouse_move({x}, {y})", exec_result.exit_code, exec_result.stderr
+            )
+
+    async def left_click(self):
+        """Click left mouse button at current position."""
+        exec_result = await self.exec("xdotool", "click", "1")
+        if exec_result.exit_code != 0:
+            raise ExecError("left_click()", exec_result.exit_code, exec_result.stderr)
+
+    async def right_click(self):
+        """Click right mouse button at current position."""
+        exec_result = await self.exec("xdotool", "click", "3")
+        if exec_result.exit_code != 0:
+            raise ExecError("right_click()", exec_result.exit_code, exec_result.stderr)
+
+    async def middle_click(self):
+        """Click middle mouse button at current position."""
+        exec_result = await self.exec("xdotool", "click", "2")
+        if exec_result.exit_code != 0:
+            raise ExecError("middle_click()", exec_result.exit_code, exec_result.stderr)
+
+    async def double_click(self):
+        """Double-click left mouse button at current position."""
+        exec_result = await self.exec(
+            "xdotool", "click", "--repeat", "2", "--delay", "100", "1"
+        )
+        if exec_result.exit_code != 0:
+            raise ExecError("double_click()", exec_result.exit_code, exec_result.stderr)
+
+    async def triple_click(self):
+        """Triple-click left mouse button at current position."""
+        exec_result = await self.exec(
+            "xdotool", "click", "--repeat", "3", "--delay", "100", "1"
+        )
+        if exec_result.exit_code != 0:
+            raise ExecError("triple_click()", exec_result.exit_code, exec_result.stderr)
+
+    async def left_click_drag(self, start_x: int, start_y: int, end_x: int, end_y: int):
+        """Drag mouse from start position to end position with left button held."""
+        exec_result = await self.exec(
+            "xdotool",
+            "mousemove",
+            str(start_x),
+            str(start_y),
+            "mousedown",
+            "1",
+            "sleep",
+            "0.1",
+            "mousemove",
+            str(end_x),
+            str(end_y),
+            "sleep",
+            "0.1",
+            "mouseup",
+            "1",
+        )
+        if exec_result.exit_code != 0:
+            raise ExecError(
+                "left_click_drag()", exec_result.exit_code, exec_result.stderr
+            )
+
+    async def cursor_position(self) -> Tuple[int, int]:
+        """Get the current mouse cursor position. Returns (x, y) tuple."""
+        exec_result = await self.exec("xdotool", "getmouselocation", "--shell")
+        if exec_result.exit_code != 0:
+            raise ExecError(
+                "cursor_position()", exec_result.exit_code, exec_result.stderr
+            )
+
+        x, y = None, None
+        for line in exec_result.stdout.split("\n"):
+            line = line.strip()
+            if line.startswith("X="):
+                x = int(line[2:])
+            elif line.startswith("Y="):
+                y = int(line[2:])
+
+        if x is not None and y is not None:
+            return (x, y)
+        raise ParseError("Failed to parse cursor position from xdotool output")
+
+    async def type(self, text: str):
+        """Type text using the keyboard."""
+        exec_result = await self.exec("xdotool", "type", "--", text)
+        if exec_result.exit_code != 0:
+            raise ExecError("type()", exec_result.exit_code, exec_result.stderr)
+
+    async def key(self, text: str):
+        """Press a special key or key combination (e.g., 'Return', 'ctrl+c')."""
+        exec_result = await self.exec("xdotool", "key", text)
+        if exec_result.exit_code != 0:
+            raise ExecError("key()", exec_result.exit_code, exec_result.stderr)
+
+    async def scroll(self, x: int, y: int, direction: str, amount: int = 3):
+        """
+        Scroll at a specific position.
+
+        Args:
+            x, y: Coordinates where to scroll
+            direction: 'up', 'down', 'left', or 'right'
+            amount: Number of scroll units (default: 3)
+        """
+        direction_map = {"up": "4", "down": "5", "left": "6", "right": "7"}
+        button = direction_map.get(direction.lower())
+        if not button:
+            raise ValueError(f"Invalid scroll direction: {direction}")
+
+        exec_result = await self.exec(
+            "xdotool",
+            "mousemove",
+            str(x),
+            str(y),
+            "click",
+            "--repeat",
+            str(amount),
+            button,
+        )
+        if exec_result.exit_code != 0:
+            raise ExecError("scroll()", exec_result.exit_code, exec_result.stderr)
+
+    async def get_screen_size(self) -> Tuple[int, int]:
+        """Get the screen resolution. Returns (width, height) tuple."""
+        exec_result = await self.exec("xdotool", "getdisplaygeometry")
+        if exec_result.exit_code != 0:
+            raise ExecError(
+                "get_screen_size()", exec_result.exit_code, exec_result.stderr
+            )
+
+        parts = exec_result.stdout.strip().split()
+        if len(parts) == 2:
+            return (int(parts[0]), int(parts[1]))
+        raise ParseError("Failed to parse screen size from xdotool output")