boxlite 0.3.0.post1__cp314-cp314-macosx_14_0_arm64.whl

boxlite/interactivebox.py

@@ -0,0 +1,292 @@
+"""
+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
+
+if TYPE_CHECKING:
+    from .runtime import Boxlite
+
+# Configure logger
+logger = logging.getLogger("boxlite.interactivebox")
+
+
+class InteractiveBox:
+    """
+    Interactive box with automatic PTY and terminal forwarding.
+
+    When used as a context manager, automatically:
+    1. Auto-detects terminal size (like Docker)
+    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,
+            **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)
+            **kwargs: Additional configuration options (working_dir, env)
+        """
+        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 default
+        if runtime is None:
+            self._runtime = Boxlite.default()
+        else:
+            self._runtime = runtime
+
+        # Create box options
+        box_opts = BoxOptions(
+            image=image,
+            cpus=cpus,
+            memory_mib=memory_mib,
+            **kwargs
+        )
+
+        # Create box directly (no SimpleBox wrapper)
+        self._box = self._runtime.create(box_opts)
+
+        # Store interactive config
+        self._shell = shell
+        self._env = kwargs.get('env', [])
+
+        # Determine TTY mode: None = auto-detect, True = force, False = disable
+        if tty is None:
+            self._tty = sys.stdin.isatty()
+        else:
+            self._tty = 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
+
+    @property
+    def id(self) -> str:
+        """Get the box ID."""
+        return self._box.id
+
+    async def __aenter__(self):
+        """Start box and enter interactive TTY session."""
+        # Start box directly
+        await self._box.__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 directly
+        return await self._box.__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,208 @@
+"""
+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
+
+from .exec import ExecResult
+
+# Configure logger
+logger = logging.getLogger("boxlite.simplebox")
+
+__all__ = ['SimpleBox']
+
+
+class StreamType(IntEnum):
+    """Stream type for command execution output (deprecated, use execution.py)."""
+    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,
+            **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)
+            **kwargs: Additional configuration options
+        """
+        try:
+            from .boxlite import Boxlite
+        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
+
+        # Create box using subclass-defined options
+        try:
+            from .boxlite import BoxOptions
+        except ImportError as e:
+            raise ImportError(
+                f"BoxLite native extension not found: {e}. "
+                "Please install with: pip install boxlite"
+            )
+
+        box_opts = BoxOptions(
+            image=image,
+            cpus=cpus,
+            memory_mib=memory_mib,
+            **kwargs
+        )
+        self._box = self._runtime.create(box_opts)
+
+    async def __aenter__(self):
+        """Async context manager entry - delegates to Box.__aenter__."""
+        await self._box.__aenter__()
+        return self
+
+    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."""
+        return self._box.id
+
+    def info(self):
+        """Get box information."""
+        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)
+        """
+
+        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.
+        """
+        self._box.shutdown()

boxlite-0.3.0.post1.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: boxlite
+Version: 0.3.0.post1
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21 ; extra == 'dev'
+Provides-Extra: dev
+Summary: Python bindings for Boxlite runtime
+Author: Dorian Zheng
+License-Expression: Apache-2.0
+Requires-Python: >=3.10

boxlite-0.3.0.post1.dist-info/RECORD

@@ -0,0 +1,19 @@
+boxlite-0.3.0.post1.dist-info/RECORD,,
+boxlite-0.3.0.post1.dist-info/WHEEL,sha256=6FIqGwdIERCadatTFtHOIr_ebO64RXZ_R6wcyoBVcQE,105
+boxlite-0.3.0.post1.dist-info/METADATA,sha256=yWxfgsV5xxhmS2vnKMXVCHD2BPWv9SZJRJvHavuirvc,295
+boxlite/exec.py,sha256=UWoLBnKUPx93ueHC2E3KVU7evaj06TIb1pHhuShZwbM,507
+boxlite/boxlite.cpython-314-darwin.so,sha256=4tqDy-AZ2mxpr6SGDnm3cEpFHjf2amLWI-6Qpj8Pp7M,12604192
+boxlite/__init__.py,sha256=2wYQEKJc86jXJIwWmIX1s1OiE3FcRs6k29NzCikcm74,1990
+boxlite/computerbox.py,sha256=K2dRQ5452bwoS33LYlu_Avp1rDsRxbH8golRTPZf5Qo,18945
+boxlite/simplebox.py,sha256=S5rz6scUoMgBK8dVZqYqMyTvhj3oCovgVSdhznyjvXY,6269
+boxlite/browserbox.py,sha256=UX4yxZsnbFHgyLhS9-OC58AG1pecHpUwbxlO6leiV98,4477
+boxlite/errors.py,sha256=vuW2uZvkrX9GGvE3SKIogO8r1rBxUplit_3F2CSxglg,957
+boxlite/interactivebox.py,sha256=ooKt2Ux9f5_Be529fM4M-Aqv65eDgosw-NJB322aZNk,10346
+boxlite/codebox.py,sha256=buppZbGh2_jd5syCXx-xFUMQWvo7DRAMXo5unEAgIZY,3677
+boxlite/runtime/mke2fs,sha256=JMZjDSJfvnWdGKNOcXwRoJOxgb7qW99mhAuovMFdbcU,578008
+boxlite/runtime/boxlite-shim,sha256=76CB-rOoQGrEjDwsZRdUFYSlhSA0YxSUCvcv8M1zQsU,3276320
+boxlite/runtime/boxlite-guest,sha256=S3wwDm9a0I--QKYbDhn4FvI3hdsgYMq8duw9M0SofJY,12200864
+boxlite/runtime/libkrunfw.4.dylib,sha256=cRy63u5WT5twkeR2bHrRCZwcw7uidbeSs_bTCaKb-tA,21979472
+boxlite/runtime/libkrun.1.15.1.dylib,sha256=ltZQfWifiQ_VViXeTRywMCd8Vj1WIP66_pR58-vmneU,3994416
+boxlite/runtime/libgvproxy.dylib,sha256=irddG9i5EMEowq0rTIMfdWDdmp_m0qZ2zdHvf5lQH0s,10809824
+boxlite/runtime/debugfs,sha256=P_1GHbPoLfesVH9KDJiSJ1Z6xX1L-utHOkuRnJYOlUY,662328

boxlite-0.3.0.post1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.10.2)
+Root-Is-Purelib: false
+Tag: cp314-cp314-macosx_14_0_arm64