boxlite 0.5.7__cp312-cp312-macosx_14_0_arm64.whl

boxlite/constants.py

@@ -0,0 +1,25 @@
+"""
+Centralized constants for BoxLite Python SDK.
+"""
+
+# Default VM resources
+DEFAULT_CPUS = 1
+DEFAULT_MEMORY_MIB = 2048
+
+# ComputerBox defaults (higher resources for desktop)
+COMPUTERBOX_CPUS = 2
+COMPUTERBOX_MEMORY_MIB = 2048
+COMPUTERBOX_IMAGE = "lscr.io/linuxserver/webtop:ubuntu-xfce"
+
+# ComputerBox display settings
+COMPUTERBOX_DISPLAY_NUMBER = ":1"
+COMPUTERBOX_DISPLAY_WIDTH = 1024
+COMPUTERBOX_DISPLAY_HEIGHT = 768
+
+# ComputerBox network ports (webtop defaults)
+COMPUTERBOX_GUI_HTTP_PORT = 3000
+COMPUTERBOX_GUI_HTTPS_PORT = 3001
+
+# Timeouts (seconds)
+DESKTOP_READY_TIMEOUT = 60
+DESKTOP_READY_RETRY_DELAY = 0.5

boxlite/errors.py

@@ -0,0 +1,44 @@
+"""
+BoxLite error types.
+
+Provides a hierarchy of exceptions for different failure modes.
+"""
+
+__all__ = ["BoxliteError", "ExecError", "TimeoutError", "ParseError"]
+
+
+class BoxliteError(Exception):
+    """Base exception for all boxlite errors."""
+
+    pass
+
+
+class ExecError(BoxliteError):
+    """
+    Raised when a command execution fails (non-zero exit code).
+
+    Attributes:
+        command: The command that failed
+        exit_code: The non-zero exit code
+        stderr: Standard error output from the command
+    """
+
+    def __init__(self, command: str, exit_code: int, stderr: str):
+        self.command = command
+        self.exit_code = exit_code
+        self.stderr = stderr
+        super().__init__(
+            f"Command '{command}' failed with exit code {exit_code}: {stderr}"
+        )
+
+
+class TimeoutError(BoxliteError):
+    """Raised when an operation times out."""
+
+    pass
+
+
+class ParseError(BoxliteError):
+    """Raised when output parsing fails."""
+
+    pass

boxlite/exec.py

@@ -0,0 +1,27 @@
+"""
+Execution API - Simple interface for command execution.
+
+Provides Docker-like API for executing commands in boxes.
+"""
+
+from dataclasses import dataclass
+
+__all__ = [
+    "ExecResult",
+]
+
+
+@dataclass
+class ExecResult:
+    """
+    Result from a command execution.
+
+    Attributes:
+        exit_code: Exit code from the command (negative if terminated by signal)
+        stdout: Standard output as string
+        stderr: Standard error as string
+    """
+
+    exit_code: int
+    stdout: str
+    stderr: str

boxlite/interactivebox.py

@@ -0,0 +1,287 @@
+"""
+InteractiveBox - Interactive terminal sessions with PTY support.
+
+Provides automatic PTY-based interactive sessions, similar to `docker exec -it`.
+"""
+
+import asyncio
+import logging
+import os
+import sys
+import termios
+import tty
+from typing import Optional, TYPE_CHECKING
+
+from .simplebox import SimpleBox
+
+if TYPE_CHECKING:
+    from .boxlite import Boxlite
+
+# Configure logger
+logger = logging.getLogger("boxlite.interactivebox")
+
+
+class InteractiveBox(SimpleBox):
+    """
+    Interactive box with automatic PTY and terminal forwarding.
+
+    When used as a context manager, automatically:
+    1. Auto-detects terminal size (for PTY)
+    2. Starts a shell with PTY
+    3. Sets local terminal to cbreak mode
+    4. Forwards stdin/stdout bidirectionally
+    5. Restores terminal mode on exit
+
+    Example:
+        async with InteractiveBox(image="alpine:latest") as box:
+            # You're now in an interactive shell!
+            # Type commands, see output in real-time
+            # Type "exit" to close
+            pass
+    """
+
+    def __init__(
+        self,
+        image: str,
+        shell: str = "/bin/sh",
+        tty: Optional[bool] = None,
+        memory_mib: Optional[int] = None,
+        cpus: Optional[int] = None,
+        runtime: Optional["Boxlite"] = None,
+        name: Optional[str] = None,
+        auto_remove: bool = True,
+        **kwargs,
+    ):
+        """
+        Create interactive box.
+
+        Args:
+            image: Container image to use
+            shell: Shell to run (default: /bin/sh)
+            tty: Control terminal I/O forwarding behavior:
+                - None (default): Auto-detect - forward I/O if stdin is a TTY
+                - True: Force I/O forwarding (manual interactive mode)
+                - False: No I/O forwarding (programmatic control only)
+            memory_mib: Memory limit in MiB
+            cpus: Number of CPU cores
+            runtime: Optional runtime instance (uses global default if None)
+            name: Optional name for the box (must be unique)
+            auto_remove: Remove box when stopped (default: True)
+            **kwargs: Additional configuration options (working_dir, env)
+        """
+        # Initialize base class (handles runtime, BoxOptions, _box, _started)
+        super().__init__(
+            image=image,
+            memory_mib=memory_mib,
+            cpus=cpus,
+            runtime=runtime,
+            name=name,
+            auto_remove=auto_remove,
+            **kwargs,
+        )
+
+        # InteractiveBox-specific config
+        self._shell = shell
+        self._env = kwargs.get("env", [])
+
+        # Determine TTY mode: None = auto-detect, True = force, False = disable
+        self._tty = sys.stdin.isatty() if tty is None else tty
+
+        # Interactive state
+        self._old_tty_settings = None
+        self._io_task = None
+        self._execution = None
+        self._stdin = None
+        self._stdout = None
+        self._stderr = None
+        self._exited = None  # Event to signal process exit
+
+    # id property inherited from SimpleBox
+
+    async def __aenter__(self):
+        """Start box and enter interactive TTY session."""
+        if self._started:
+            return self
+
+        # Create and start box (via parent)
+        await super().__aenter__()
+
+        # Start shell with PTY
+        self._execution = await self._start_interactive_shell()
+
+        # Get stdin/stdout/stderr ONCE (can only be called once due to .take())
+        self._stdin = self._execution.stdin()
+        self._stdout = self._execution.stdout()
+        self._stderr = self._execution.stderr()
+
+        # Only set cbreak mode and start forwarding if tty=True
+        if self._tty:
+            stdin_fd = sys.stdin.fileno()
+            self._old_tty_settings = termios.tcgetattr(stdin_fd)
+            tty.setraw(sys.stdin.fileno(), when=termios.TCSANOW)
+
+            # Create exit event for graceful shutdown
+            self._exited = asyncio.Event()
+
+            # Start bidirectional I/O forwarding using gather (more Pythonic)
+            self._io_task = asyncio.gather(
+                self._forward_stdin(),
+                self._forward_output(),
+                self._forward_stderr(),
+                self._wait_for_exit(),
+                return_exceptions=True,
+            )
+        else:
+            # No I/O forwarding, just wait for execution
+            self._io_task = self._wait_for_exit()
+
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        # Restore terminal settings
+        if self._old_tty_settings is not None:
+            try:
+                termios.tcsetattr(
+                    sys.stdin.fileno(), termios.TCSADRAIN, self._old_tty_settings
+                )
+            except Exception as e:
+                logger.error(f"Caught exception on TTY settings: {e}")
+
+        """Exit interactive session and restore terminal."""
+        # Wait for I/O task to complete (or cancel if needed)
+        if hasattr(self, "_io_task") and self._io_task is not None:
+            try:
+                # Give it a moment to finish naturally
+                await asyncio.wait_for(self._io_task, timeout=3)
+                logger.info("Closing interactive shell (I/O tasks finished).")
+                self._io_task = None
+            except asyncio.TimeoutError:
+                # If it doesn't finish, that's ok - box is shutting down anyway
+                logger.error("Timeout waiting for I/O tasks to finish, cancelling...")
+            except Exception as e:
+                # Ignore other exceptions during cleanup
+                logger.error(f"Caught exception on exit: {e}")
+
+        # Shutdown box (via parent)
+        return await super().__aexit__(exc_type, exc_val, exc_tb)
+
+    async def wait(self):
+        await self._execution.wait()
+
+    async def _start_interactive_shell(self):
+        """Start shell with PTY (internal)."""
+        # Execute shell with PTY using simplified boolean API
+        # Terminal size is auto-detected (like Docker)
+        execution = await self._box.exec(
+            self._shell,
+            args=[],
+            env=self._env,
+            tty=True,  # Simple boolean - auto-detects terminal size
+        )
+
+        return execution
+
+    async def _forward_stdin(self):
+        """Forward stdin to PTY (internal)."""
+        try:
+            if self._stdin is None:
+                return
+
+            # Forward stdin in chunks
+            loop = asyncio.get_event_loop()
+            while not self._exited.is_set():
+                # Read from stdin with timeout to check exit event
+                try:
+                    read_task = loop.run_in_executor(
+                        None, os.read, sys.stdin.fileno(), 1024
+                    )
+                    # Wait for either stdin data or exit event
+                    done, pending = await asyncio.wait(
+                        [
+                            asyncio.ensure_future(read_task),
+                            asyncio.ensure_future(self._exited.wait()),
+                        ],
+                        return_when=asyncio.FIRST_COMPLETED,
+                    )
+
+                    # Cancel pending tasks
+                    for task in pending:
+                        task.cancel()
+
+                    # Check if we exited
+                    if self._exited.is_set():
+                        logger.info("Closing interactive shell (stdin forwarding).")
+                        break
+
+                    # Get the data from completed read task
+                    for task in done:
+                        if task.exception() is None:
+                            data = task.result()
+                            if isinstance(data, bytes) and data:
+                                await self._stdin.send_input(data)
+                            elif not data:
+                                # EOF
+                                return
+
+                except asyncio.CancelledError:
+                    break
+
+        except asyncio.CancelledError:
+            logger.info("Cancelling interactive shell (stdin forwarding).")
+        except Exception as e:
+            logger.error(f"Caught exception on stdin: {e}")
+
+    async def _forward_output(self):
+        """Forward PTY output to stdout (internal)."""
+        try:
+            if self._stdout is None:
+                return
+
+            # Forward all output to stdout
+            async for chunk in self._stdout:
+                # Write directly to stdout (bypass print buffering)
+                if isinstance(chunk, bytes):
+                    sys.stdout.buffer.write(chunk)
+                else:
+                    sys.stdout.buffer.write(chunk.encode("utf-8", errors="replace"))
+                sys.stdout.buffer.flush()
+
+            logger.info("\nOutput forwarding ended.")
+
+        except asyncio.CancelledError:
+            logger.error("Cancelling interactive shell (stdout forwarding).")
+        except Exception as e:
+            logger.error(f"\nError forwarding output: {e}", file=sys.stderr)
+
+    async def _forward_stderr(self):
+        """Forward PTY stderr to stderr (internal)."""
+        try:
+            if self._stderr is None:
+                return
+
+            # Forward all error output to stderr
+            async for chunk in self._stderr:
+                # Write directly to stderr (bypass print buffering)
+                if isinstance(chunk, bytes):
+                    sys.stderr.buffer.write(chunk)
+                else:
+                    sys.stderr.buffer.write(chunk.encode("utf-8", errors="replace"))
+                sys.stderr.buffer.flush()
+
+            logger.info("\nStderr forwarding ended.")
+
+        except asyncio.CancelledError:
+            logger.error("Cancelling interactive shell (stderr forwarding).")
+        except Exception as e:
+            logger.error(f"\nError forwarding stderr: {e}", file=sys.stderr)
+
+    async def _wait_for_exit(self):
+        """Wait for the shell to exit (internal)."""
+        try:
+            await self._execution.wait()
+        except Exception:
+            pass  # Ignore errors, cleanup will happen in __aexit__
+        finally:
+            # Signal other tasks to stop
+            if self._exited:
+                self._exited.set()

boxlite/simplebox.py

@@ -0,0 +1,256 @@
+"""
+SimpleBox - Foundation for specialized container types.
+
+Provides common functionality for all specialized boxes (CodeBox, BrowserBox, etc.)
+"""
+
+import logging
+from enum import IntEnum
+from typing import Optional, TYPE_CHECKING
+
+from .exec import ExecResult
+
+if TYPE_CHECKING:
+    from .boxlite import Boxlite
+
+logger = logging.getLogger("boxlite.simplebox")
+
+__all__ = ["SimpleBox"]
+
+
+class StreamType(IntEnum):
+    """Stream type for command execution output."""
+
+    STDOUT = 1
+    STDERR = 2
+
+
+class SimpleBox:
+    """
+    Base class for specialized container types.
+
+    This class encapsulates the common patterns:
+    1. Async context manager support
+    2. Automatic runtime lifecycle management
+    3. Stdio blocking mode restoration
+
+    Subclasses should override:
+    - _create_box_options(): Return BoxOptions for their specific use case
+    - Add domain-specific methods (e.g., CodeBox.run(), BrowserBox.navigate())
+    """
+
+    def __init__(
+        self,
+        image: str,
+        memory_mib: Optional[int] = None,
+        cpus: Optional[int] = None,
+        runtime: Optional["Boxlite"] = None,
+        name: Optional[str] = None,
+        auto_remove: bool = True,
+        **kwargs,
+    ):
+        """
+        Create a specialized box.
+
+        Args:
+            image: Container images to use
+            memory_mib: Memory limit in MiB
+            cpus: Number of CPU cores
+            runtime: Optional runtime instance (uses global default if None)
+            name: Optional name for the box (must be unique)
+            auto_remove: Remove box when stopped (default: True)
+            **kwargs: Additional configuration options
+
+        Note: The box is not actually created until entering the async context manager.
+        Use `async with SimpleBox(...) as box:` to create and start the box.
+        """
+        try:
+            from .boxlite import Boxlite, BoxOptions
+        except ImportError as e:
+            raise ImportError(
+                f"BoxLite native extension not found: {e}. "
+                "Please install with: pip install boxlite"
+            )
+
+        # Use provided runtime or get Rust's global default
+        if runtime is None:
+            self._runtime = Boxlite.default()
+        else:
+            self._runtime = runtime
+
+        # Store box options for deferred creation in __aenter__
+        self._box_options = BoxOptions(
+            image=image,
+            cpus=cpus,
+            memory_mib=memory_mib,
+            auto_remove=auto_remove,
+            **kwargs,
+        )
+        self._name = name
+        self._box = None
+        self._started = False
+
+    async def __aenter__(self):
+        """Async context manager entry - creates and starts the box.
+
+        This method is idempotent - calling it multiple times is safe.
+        All initialization logic lives here; start() is just an alias.
+        """
+        if self._started:
+            return self
+        self._box = await self._runtime.create(self._box_options, name=self._name)
+        await self._box.__aenter__()
+        self._started = True
+        return self
+
+    async def start(self):
+        """
+        Explicitly create and start the box.
+
+        Alternative to using context manager. Allows::
+
+            box = SimpleBox(image="alpine:latest")
+            await box.start()
+            await box.exec("echo", "hello")
+
+        Returns:
+            self for method chaining
+        """
+        return await self.__aenter__()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit - delegates to Box.__aexit__ (returns awaitable)."""
+        return await self._box.__aexit__(exc_type, exc_val, exc_tb)
+
+    @property
+    def id(self) -> str:
+        """Get the box ID."""
+        if not self._started:
+            raise RuntimeError(
+                "Box not started. Use 'async with SimpleBox(...) as box:' "
+                "or call 'await box.start()' first."
+            )
+        return self._box.id
+
+    def info(self):
+        """Get box information."""
+        if not self._started:
+            raise RuntimeError(
+                "Box not started. Use 'async with SimpleBox(...) as box:' "
+                "or call 'await box.start()' first."
+            )
+        return self._box.info()
+
+    async def exec(
+        self,
+        cmd: str,
+        *args: str,
+        env: Optional[dict[str, str]] = None,
+    ) -> ExecResult:
+        """
+        Execute a command in the box and return the result.
+
+        Args:
+            cmd: Command to execute (e.g., 'ls', 'python')
+            *args: Arguments to the command (e.g., '-l', '-a')
+            env: Environment variables (default: guest's default environment)
+
+        Returns:
+            ExecResult with exit_code and output
+
+        Examples:
+            Simple execution::
+
+                result = await box.exec('ls', '-l', '-a')
+                print(f"Exit code: {result.exit_code}")
+                print(f"Stdout: {result.stdout}")
+                print(f"Stderr: {result.stderr}")
+
+            With environment variables::
+
+                result = await box.exec('env', env={'FOO': 'bar'})
+                print(result.stdout)
+        """
+        if not self._started:
+            raise RuntimeError(
+                "Box not started. Use 'async with SimpleBox(...) as box:' "
+                "or call 'await box.start()' first."
+            )
+
+        arg_list = list(args) if args else None
+        # Convert env dict to list of tuples if provided
+        env_list = list(env.items()) if env else None
+
+        # Execute via Rust (returns PyExecution)
+        execution = await self._box.exec(cmd, arg_list, env_list)
+
+        # Get streams from Rust execution
+        try:
+            stdout = execution.stdout()
+        except Exception as e:
+            logger.error(f"take stdout err: {e}")
+            stdout = None
+
+        try:
+            stderr = execution.stderr()
+        except Exception as e:
+            logger.error(f"take stderr err: {e}")
+            stderr = None
+
+        # Collect stdout and stderr separately
+        stdout_lines = []
+        stderr_lines = []
+
+        # Read stdout
+        if stdout:
+            logger.debug("collecting stdout")
+            try:
+                async for line in stdout:
+                    if isinstance(line, bytes):
+                        stdout_lines.append(line.decode("utf-8", errors="replace"))
+                    else:
+                        stdout_lines.append(line)
+            except Exception as e:
+                logger.error(f"collecting stdout err: {e}")
+                pass
+
+        # Read stderr
+        if stderr:
+            logger.debug("collecting stderr")
+            try:
+                async for line in stderr:
+                    if isinstance(line, bytes):
+                        stderr_lines.append(line.decode("utf-8", errors="replace"))
+                    else:
+                        stderr_lines.append(line)
+            except Exception as e:
+                logger.error(f"collecting stderr err: {e}")
+                pass
+
+        # Combine lines
+        stdout = "".join(stdout_lines)
+        stderr = "".join(stderr_lines)
+
+        try:
+            exec_result = await execution.wait()
+            exit_code = exec_result.exit_code
+        except Exception as e:
+            logger.error(f"failed to wait execution: {e}")
+            exit_code = -1
+
+        logger.debug(f"exec finish, exit_code: {exit_code}")
+
+        return ExecResult(exit_code=exit_code, stdout=stdout, stderr=stderr)
+
+    def shutdown(self):
+        """
+        Shutdown the box and release resources.
+
+        Note: Usually not needed as context manager handles cleanup.
+        """
+        if not self._started:
+            raise RuntimeError(
+                "Box not started. Use 'async with SimpleBox(...) as box:' "
+                "or call 'await box.start()' first."
+            )
+        self._box.shutdown()