boxlite 0.5.7__cp312-cp312-macosx_14_0_arm64.whl

boxlite/sync_api/_codebox.py

@@ -0,0 +1,145 @@
+"""
+SyncCodeBox - Synchronous wrapper for CodeBox.
+
+Provides a synchronous API for Python code execution using greenlet fiber switching.
+API mirrors async CodeBox exactly.
+"""
+
+from typing import TYPE_CHECKING, Optional
+
+from ._simplebox import SyncSimpleBox
+
+if TYPE_CHECKING:
+    from ._boxlite import SyncBoxlite
+
+__all__ = ["SyncCodeBox"]
+
+
+class SyncCodeBox(SyncSimpleBox):
+    """
+    Synchronous wrapper for CodeBox.
+
+    Provides synchronous methods for executing Python code in a secure container.
+    Built on top of SyncSimpleBox with Python-specific convenience methods.
+    API mirrors async CodeBox exactly.
+
+    Usage (standalone - recommended):
+        with SyncCodeBox() as box:
+            result = box.run("print('Hello, World!')")
+            print(result)  # Hello, World!
+
+    Usage (with explicit runtime):
+        with SyncBoxlite.default() as runtime:
+            with SyncCodeBox(runtime=runtime) as box:
+                result = box.run("print('Hello!')")
+                print(result)
+    """
+
+    def __init__(
+        self,
+        image: str = "python:slim",
+        memory_mib: Optional[int] = None,
+        cpus: Optional[int] = None,
+        runtime: Optional["SyncBoxlite"] = None,
+        name: Optional[str] = None,
+        auto_remove: bool = True,
+        **kwargs,
+    ):
+        """
+        Create a SyncCodeBox.
+
+        Args:
+            image: Python container image (default: "python:slim")
+            memory_mib: Memory limit in MiB (default: system default)
+            cpus: Number of CPU cores (default: system default)
+            runtime: Optional SyncBoxlite runtime. If None, creates default runtime.
+            name: Optional unique name for the box
+            auto_remove: Remove box when stopped (default: True)
+            **kwargs: Additional BoxOptions parameters
+        """
+        super().__init__(
+            image=image,
+            memory_mib=memory_mib,
+            cpus=cpus,
+            runtime=runtime,
+            name=name,
+            auto_remove=auto_remove,
+            **kwargs,
+        )
+
+    def run(self, code: str, timeout: Optional[int] = None) -> str:
+        """
+        Execute Python code synchronously.
+
+        Args:
+            code: Python code to execute
+            timeout: Execution timeout in seconds (not yet implemented)
+
+        Returns:
+            Combined stdout and stderr output
+
+        Example:
+            with SyncCodeBox() as box:
+                result = box.run("print('Hello!')")
+                print(result)  # Hello!
+
+                # Multi-line code
+                result = box.run('''
+                import sys
+                print(f"Python {sys.version}")
+                ''')
+        """
+        result = self.exec("/usr/local/bin/python", "-c", code)
+        return result.stdout + result.stderr
+
+    def install_package(self, package: str) -> str:
+        """
+        Install a Python package using pip.
+
+        Args:
+            package: Package name (e.g., "requests", "numpy==1.24.0")
+
+        Returns:
+            Installation output
+
+        Example:
+            box.install_package("requests")
+            result = box.run("import requests; print(requests.__version__)")
+        """
+        result = self.exec("pip", "install", package)
+        return result.stdout + result.stderr
+
+    def install_packages(self, *packages: str) -> str:
+        """
+        Install multiple Python packages.
+
+        Args:
+            *packages: Package names to install
+
+        Returns:
+            Installation output
+
+        Example:
+            box.install_packages("requests", "numpy", "pandas")
+        """
+        result = self.exec("pip", "install", *packages)
+        return result.stdout + result.stderr
+
+    def run_script(self, script_path: str) -> str:
+        """
+        Execute a Python script file.
+
+        Reads the script from the host filesystem and executes it in the box.
+
+        Args:
+            script_path: Path to the Python script on the host
+
+        Returns:
+            Script output (stdout + stderr)
+
+        Example:
+            result = box.run_script("./my_script.py")
+        """
+        with open(script_path, "r") as f:
+            code = f.read()
+        return self.run(code)

boxlite/sync_api/_execution.py

@@ -0,0 +1,203 @@
+"""
+SyncExecution - Synchronous wrapper for Execution.
+
+Mirrors the native Execution API exactly, but with synchronous methods.
+"""
+
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ._boxlite import SyncBoxlite
+    from ..boxlite import Execution
+
+__all__ = ["SyncExecution", "SyncExecStdout", "SyncExecStderr"]
+
+
+class SyncExecStdout:
+    """
+    Synchronous iterator for execution stdout.
+
+    Mirrors ExecStdout but uses regular iteration instead of async iteration.
+
+    Usage:
+        stdout = execution.stdout()
+        for line in stdout:
+            print(line)
+    """
+
+    def __init__(self, ctx: "SyncBoxlite", async_stdout) -> None:
+        self._ctx = ctx
+        self._async_stdout = async_stdout
+        self._async_iter = None
+
+        from ._sync_base import SyncBase
+
+        self._sync_helper = SyncBase(async_stdout, ctx.loop, ctx.dispatcher_fiber)
+
+    def _sync(self, coro):
+        """Run async operation synchronously."""
+        return self._sync_helper._sync(coro)
+
+    def __iter__(self) -> "SyncExecStdout":
+        """Start iteration."""
+        self._async_iter = self._async_stdout.__aiter__()
+        return self
+
+    def __next__(self) -> str:
+        """Get next line from stdout."""
+        if self._async_iter is None:
+            self._async_iter = self._async_stdout.__aiter__()
+
+        try:
+            line = self._sync(self._async_iter.__anext__())
+            # Decode bytes to string if needed
+            if isinstance(line, bytes):
+                return line.decode("utf-8", errors="replace")
+            return line
+        except StopAsyncIteration:
+            raise StopIteration
+
+
+class SyncExecStderr:
+    """
+    Synchronous iterator for execution stderr.
+
+    Mirrors ExecStderr but uses regular iteration instead of async iteration.
+
+    Usage:
+        stderr = execution.stderr()
+        for line in stderr:
+            print(line)
+    """
+
+    def __init__(self, ctx: "SyncBoxlite", async_stderr) -> None:
+        self._ctx = ctx
+        self._async_stderr = async_stderr
+        self._async_iter = None
+
+        from ._sync_base import SyncBase
+
+        self._sync_helper = SyncBase(async_stderr, ctx.loop, ctx.dispatcher_fiber)
+
+    def _sync(self, coro):
+        """Run async operation synchronously."""
+        return self._sync_helper._sync(coro)
+
+    def __iter__(self) -> "SyncExecStderr":
+        """Start iteration."""
+        self._async_iter = self._async_stderr.__aiter__()
+        return self
+
+    def __next__(self) -> str:
+        """Get next line from stderr."""
+        if self._async_iter is None:
+            self._async_iter = self._async_stderr.__aiter__()
+
+        try:
+            line = self._sync(self._async_iter.__anext__())
+            # Decode bytes to string if needed
+            if isinstance(line, bytes):
+                return line.decode("utf-8", errors="replace")
+            return line
+        except StopAsyncIteration:
+            raise StopIteration
+
+
+class SyncExecution:
+    """
+    Synchronous wrapper for Execution.
+
+    Provides the same API as the native Execution class, but with synchronous methods.
+    stdout() and stderr() return sync iterables instead of async iterables.
+
+    Usage:
+        execution = box.exec("echo", ["Hello"])
+
+        # Stream stdout
+        for line in execution.stdout():
+            print(f"stdout: {line}")
+
+        # Stream stderr
+        for line in execution.stderr():
+            print(f"stderr: {line}")
+
+        # Wait for completion
+        result = execution.wait()
+        print(f"Exit code: {result.exit_code}")
+    """
+
+    def __init__(
+        self,
+        ctx: "SyncBoxlite",
+        execution: "Execution",
+    ) -> None:
+        """
+        Create a SyncExecution wrapper.
+
+        Args:
+            ctx: The SyncBoxlite providing event loop and dispatcher
+            execution: The native Execution object to wrap
+        """
+        from ._sync_base import SyncBase
+
+        self._execution = execution
+        self._ctx = ctx
+        self._sync_helper = SyncBase(execution, ctx.loop, ctx.dispatcher_fiber)
+
+    def _sync(self, coro):
+        """Run async operation synchronously."""
+        return self._sync_helper._sync(coro)
+
+    @property
+    def id(self) -> str:
+        """Get the execution ID."""
+        return self._execution.id
+
+    def stdout(self) -> Optional[SyncExecStdout]:
+        """
+        Get synchronous stdout iterator.
+
+        Returns:
+            SyncExecStdout iterator, or None if stdout is not available.
+
+        Usage:
+            stdout = execution.stdout()
+            if stdout:
+                for line in stdout:
+                    print(line)
+        """
+        async_stdout = self._execution.stdout()
+        if async_stdout is None:
+            return None
+        return SyncExecStdout(self._ctx, async_stdout)
+
+    def stderr(self) -> Optional[SyncExecStderr]:
+        """
+        Get synchronous stderr iterator.
+
+        Returns:
+            SyncExecStderr iterator, or None if stderr is not available.
+
+        Usage:
+            stderr = execution.stderr()
+            if stderr:
+                for line in stderr:
+                    print(line)
+        """
+        async_stderr = self._execution.stderr()
+        if async_stderr is None:
+            return None
+        return SyncExecStderr(self._ctx, async_stderr)
+
+    def wait(self):
+        """
+        Wait for execution to complete.
+
+        Returns:
+            ExecResult with exit_code and other completion info.
+        """
+        return self._sync(self._execution.wait())
+
+    def kill(self) -> None:
+        """Kill the running execution."""
+        self._sync(self._execution.kill())

boxlite/sync_api/_simplebox.py

@@ -0,0 +1,180 @@
+"""
+SyncSimpleBox - Synchronous wrapper for SimpleBox.
+
+Provides a synchronous API for box operations.
+API mirrors async SimpleBox exactly.
+"""
+
+from typing import TYPE_CHECKING, Dict, Optional
+
+from ..exec import ExecResult
+
+if TYPE_CHECKING:
+    from ._boxlite import SyncBoxlite
+    from ._box import SyncBox
+
+__all__ = ["SyncSimpleBox"]
+
+
+class SyncSimpleBox:
+    """
+    Synchronous wrapper for SimpleBox.
+
+    Provides synchronous methods for executing commands in a BoxLite container.
+    Uses SyncBox internally which handles async bridging via greenlet.
+    API mirrors async SimpleBox exactly.
+
+    Usage (standalone - recommended):
+        with SyncSimpleBox(image="python:slim") as box:
+            result = box.exec("ls", "-la")
+            print(result.stdout)
+
+    Usage (with explicit runtime):
+        with SyncBoxlite.default() as runtime:
+            with SyncSimpleBox(image="python:slim", runtime=runtime) as box:
+                result = box.exec("ls", "-la")
+                print(result.stdout)
+    """
+
+    def __init__(
+        self,
+        image: str,
+        memory_mib: Optional[int] = None,
+        cpus: Optional[int] = None,
+        runtime: Optional["SyncBoxlite"] = None,
+        name: Optional[str] = None,
+        auto_remove: bool = True,
+        **kwargs,
+    ):
+        """
+        Create a SyncSimpleBox.
+
+        Args:
+            image: Container image to use (e.g., "python:slim", "ubuntu:latest")
+            memory_mib: Memory limit in MiB (default: system default)
+            cpus: Number of CPU cores (default: system default)
+            runtime: Optional SyncBoxlite runtime. If None, creates default runtime.
+            name: Optional unique name for the box
+            auto_remove: Remove box when stopped (default: True)
+            **kwargs: Additional BoxOptions parameters
+        """
+        from ._boxlite import SyncBoxlite
+        from ..boxlite import BoxOptions
+
+        # Handle optional runtime
+        if runtime is None:
+            runtime = SyncBoxlite.default()
+            self._owns_runtime = True
+        else:
+            self._owns_runtime = False
+
+        self._runtime = runtime
+
+        # Create box options
+        self._box_opts = BoxOptions(
+            image=image,
+            cpus=cpus,
+            memory_mib=memory_mib,
+            auto_remove=auto_remove,
+            **kwargs,
+        )
+
+        # Store for lazy creation in __enter__
+        self._name = name
+        self._box: Optional["SyncBox"] = None
+
+    def __enter__(self) -> "SyncSimpleBox":
+        """Enter context - starts runtime if owned, then starts the box."""
+        # Start runtime if we own it
+        if self._owns_runtime:
+            self._runtime.start()
+
+        # Create box via runtime - returns SyncBox!
+        self._box = self._runtime.create(self._box_opts, name=self._name)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit context - stops the box, then stops runtime if owned."""
+        # Stop the box (SyncBox.stop() is already sync)
+        if self._box is not None:
+            self._box.stop()
+
+        # Stop runtime if we own it
+        if self._owns_runtime:
+            self._runtime.stop()
+
+    @property
+    def id(self) -> str:
+        """Get the box ID."""
+        return self._box.id
+
+    @property
+    def name(self) -> Optional[str]:
+        """Get the box name (if set)."""
+        return self._box.name
+
+    def info(self):
+        """Get box information."""
+        return self._box.info()
+
+    def exec(
+        self,
+        cmd: str,
+        *args: str,
+        env: Optional[Dict[str, str]] = None,
+    ) -> ExecResult:
+        """
+        Execute a command in the box synchronously.
+
+        Args:
+            cmd: Command to run (e.g., "ls", "python")
+            *args: Command arguments (e.g., "-l", "-a")
+            env: Environment variables as dict
+
+        Returns:
+            ExecResult with exit_code, stdout, and stderr
+
+        Example:
+            result = box.exec("ls", "-la")
+            print(f"Exit code: {result.exit_code}")
+            print(f"Output: {result.stdout}")
+        """
+        # Convert args to list format expected by SyncBox
+        arg_list = list(args) if args else None
+        env_list = list(env.items()) if env else None
+
+        # SyncBox.exec() returns SyncExecution - already sync!
+        execution = self._box.exec(cmd, arg_list, env_list)
+
+        # Collect stdout (sync iteration)
+        stdout_lines = []
+        for line in execution.stdout():
+            if isinstance(line, bytes):
+                stdout_lines.append(line.decode("utf-8", errors="replace"))
+            else:
+                stdout_lines.append(line)
+
+        # Collect stderr (sync iteration)
+        stderr_lines = []
+        for line in execution.stderr():
+            if isinstance(line, bytes):
+                stderr_lines.append(line.decode("utf-8", errors="replace"))
+            else:
+                stderr_lines.append(line)
+
+        # Wait for completion (sync)
+        result = execution.wait()
+
+        return ExecResult(
+            exit_code=result.exit_code,
+            stdout="".join(stdout_lines),
+            stderr="".join(stderr_lines),
+        )
+
+    def stop(self) -> None:
+        """Stop the box (preserves state for restart)."""
+        self._box.stop()
+
+    def metrics(self):
+        """Get box metrics (CPU, memory usage)."""
+        return self._box.metrics()

boxlite/sync_api/_sync_base.py

@@ -0,0 +1,137 @@
+"""
+Base class for sync wrappers - provides _sync() method.
+
+This module contains the core bridging logic that allows sync code to
+execute async operations using greenlet fiber switching.
+"""
+
+import asyncio
+import inspect
+import traceback
+from typing import Any, Awaitable, Coroutine, TypeVar, Union
+
+from greenlet import greenlet
+
+__all__ = ["SyncBase", "SyncContextManager"]
+
+T = TypeVar("T")
+
+
+class SyncBase:
+    """
+    Base class for all sync wrapper objects.
+
+    Provides the _sync() method that bridges async to sync using greenlet
+    fiber switching. This is the core mechanism that allows synchronous
+    code to execute asynchronous operations.
+
+    How it works:
+        1. User calls a sync method (e.g., box.run_command())
+        2. Sync method calls _sync(async_coro)
+        3. _sync() creates an asyncio task and switches to dispatcher fiber
+        4. Dispatcher fiber runs event loop, processes the task
+        5. When task completes, callback switches back to user fiber
+        6. _sync() returns the task result
+    """
+
+    def __init__(
+        self,
+        impl_obj: Any,
+        loop: asyncio.AbstractEventLoop,
+        dispatcher_fiber: greenlet,
+    ) -> None:
+        """
+        Initialize SyncBase.
+
+        Args:
+            impl_obj: The underlying async implementation object
+            loop: The asyncio event loop (managed by dispatcher)
+            dispatcher_fiber: The greenlet fiber running the event loop
+        """
+        self._impl = impl_obj
+        self._loop = loop
+        self._dispatcher_fiber = dispatcher_fiber
+
+    def _sync(
+        self,
+        coro: Union[Coroutine[Any, Any, T], Awaitable[T]],
+    ) -> T:
+        """
+        Run async coroutine synchronously using greenlet fiber switching.
+
+        This is the core bridging method that enables sync-to-async conversion.
+
+        The method:
+        1. Creates an asyncio task from the coroutine
+        2. Registers a callback to switch back when task completes
+        3. Switches to dispatcher fiber to let event loop run
+        4. Returns the task result (or raises exception)
+
+        Args:
+            coro: The async coroutine to execute
+
+        Returns:
+            The result of the coroutine
+
+        Raises:
+            RuntimeError: If event loop is closed
+            Any exception raised by the coroutine
+        """
+        __tracebackhide__ = True  # Hide from pytest tracebacks
+
+        # Guard: event loop must be open
+        if self._loop.is_closed():
+            if hasattr(coro, "close"):
+                coro.close()
+            raise RuntimeError("Event loop is closed! Is BoxLite stopped?")
+
+        # 1. Get current fiber (user fiber)
+        g_self = greenlet.getcurrent()
+
+        # 2. Create async task from coroutine/future
+        # Note: PyO3's async methods return Future objects (not native coroutines),
+        # so we use ensure_future() which handles both coroutines and futures.
+        task: asyncio.Task = asyncio.ensure_future(coro, loop=self._loop)
+
+        # 3. Attach debug info for better stack traces
+        setattr(task, "__boxlite_stack__", inspect.stack(0))
+        setattr(task, "__boxlite_stack_trace__", traceback.extract_stack(limit=10))
+
+        # 4. When task completes, switch back to us
+        task.add_done_callback(lambda _: g_self.switch())
+
+        # 5. THE CORE LOOP: Keep switching to dispatcher until done
+        while not task.done():
+            self._dispatcher_fiber.switch()
+            # ^^^^^ Control goes to dispatcher fiber
+            # Dispatcher runs event loop, processes our task
+            # When task completes, callback fires g_self.switch()
+            # Control returns HERE
+
+        # 6. Return result (or raise exception)
+        return task.result()
+
+
+class SyncContextManager(SyncBase):
+    """
+    SyncBase with context manager support.
+
+    Provides __enter__ and __exit__ methods for use with 'with' statement.
+    Subclasses should override close() for cleanup logic.
+    """
+
+    def __enter__(self) -> "SyncContextManager":
+        """Enter context manager."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit context manager - calls close()."""
+        self.close()
+
+    def close(self) -> None:
+        """
+        Close and cleanup resources.
+
+        Override in subclasses to implement cleanup logic.
+        """
+        pass