boxlite 0.2.0.dev0__cp310-cp310-macosx_14_0_arm64.whl → 0.5.6__cp310-cp310-macosx_14_0_arm64.whl

boxlite/errors.py

@@ -4,11 +4,12 @@ BoxLite error types.
 Provides a hierarchy of exceptions for different failure modes.
 """
 
-__all__ = ['BoxliteError', 'ExecError', 'TimeoutError', 'ParseError']
+__all__ = ["BoxliteError", "ExecError", "TimeoutError", "ParseError"]
 
 
 class BoxliteError(Exception):
     """Base exception for all boxlite errors."""
+
     pass
 
 
@@ -21,18 +22,23 @@ class ExecError(BoxliteError):
         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}")
+        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

@@ -7,7 +7,7 @@ Provides Docker-like API for executing commands in boxes.
 from dataclasses import dataclass
 
 __all__ = [
-    'ExecResult',
+    "ExecResult",
 ]
 
 
@@ -21,6 +21,7 @@ class ExecResult:
         stdout: Standard output as string
         stderr: Standard error as string
     """
+
     exit_code: int
     stdout: str
     stderr: str

boxlite/interactivebox.py

@@ -12,19 +12,21 @@ import termios
 import tty
 from typing import Optional, TYPE_CHECKING
 
+from .simplebox import SimpleBox
+
 if TYPE_CHECKING:
-    from .runtime import Boxlite
+    from .boxlite import Boxlite
 
 # Configure logger
 logger = logging.getLogger("boxlite.interactivebox")
 
 
-class InteractiveBox:
+class InteractiveBox(SimpleBox):
     """
     Interactive box with automatic PTY and terminal forwarding.
 
     When used as a context manager, automatically:
-    1. Auto-detects terminal size (like Docker)
+    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
@@ -39,14 +41,16 @@ class InteractiveBox:
     """
 
     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
+        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.
@@ -61,43 +65,27 @@ class InteractiveBox:
             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)
         """
-        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(
+        # Initialize base class (handles runtime, BoxOptions, _box, _started)
+        super().__init__(
             image=image,
-            cpus=cpus,
             memory_mib=memory_mib,
-            working_dir=kwargs.get('working_dir'),
-            env=kwargs.get('env', [])
+            cpus=cpus,
+            runtime=runtime,
+            name=name,
+            auto_remove=auto_remove,
+            **kwargs,
         )
 
-        # Create box directly (no SimpleBox wrapper)
-        self._box = self._runtime.create(box_opts)
-
-        # Store interactive config
+        # InteractiveBox-specific config
         self._shell = shell
-        self._env = kwargs.get('env', [])
+        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
+        self._tty = sys.stdin.isatty() if tty is None else tty
 
         # Interactive state
         self._old_tty_settings = None
@@ -108,15 +96,15 @@ class InteractiveBox:
         self._stderr = None
         self._exited = None  # Event to signal process exit
 
-    @property
-    def id(self) -> str:
-        """Get the box ID."""
-        return self._box.id
+    # id property inherited from SimpleBox
 
     async def __aenter__(self):
         """Start box and enter interactive TTY session."""
-        # Start box directly
-        await self._box.__aenter__()
+        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()
@@ -141,7 +129,7 @@ class InteractiveBox:
                 self._forward_output(),
                 self._forward_stderr(),
                 self._wait_for_exit(),
-                return_exceptions=True
+                return_exceptions=True,
             )
         else:
             # No I/O forwarding, just wait for execution
@@ -153,13 +141,15 @@ class InteractiveBox:
         # Restore terminal settings
         if self._old_tty_settings is not None:
             try:
-                termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, self._old_tty_settings)
+                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:
+        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)
@@ -172,8 +162,8 @@ class InteractiveBox:
                 # 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)
+        # Shutdown box (via parent)
+        return await super().__aexit__(exc_type, exc_val, exc_tb)
 
     async def wait(self):
         await self._execution.wait()
@@ -202,12 +192,16 @@ class InteractiveBox:
             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)
+                    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
+                        [
+                            asyncio.ensure_future(read_task),
+                            asyncio.ensure_future(self._exited.wait()),
+                        ],
+                        return_when=asyncio.FIRST_COMPLETED,
                     )
 
                     # Cancel pending tasks
@@ -249,7 +243,7 @@ class InteractiveBox:
                 if isinstance(chunk, bytes):
                     sys.stdout.buffer.write(chunk)
                 else:
-                    sys.stdout.buffer.write(chunk.encode('utf-8', errors='replace'))
+                    sys.stdout.buffer.write(chunk.encode("utf-8", errors="replace"))
                 sys.stdout.buffer.flush()
 
             logger.info("\nOutput forwarding ended.")
@@ -271,7 +265,7 @@ class InteractiveBox:
                 if isinstance(chunk, bytes):
                     sys.stderr.buffer.write(chunk)
                 else:
-                    sys.stderr.buffer.write(chunk.encode('utf-8', errors='replace'))
+                    sys.stderr.buffer.write(chunk.encode("utf-8", errors="replace"))
                 sys.stderr.buffer.flush()
 
             logger.info("\nStderr forwarding ended.")

boxlite/simplebox.py

@@ -6,18 +6,21 @@ Provides common functionality for all specialized boxes (CodeBox, BrowserBox, et
 
 import logging
 from enum import IntEnum
-from typing import Optional
+from typing import Optional, TYPE_CHECKING
 
 from .exec import ExecResult
 
-# Configure logger
+if TYPE_CHECKING:
+    from .boxlite import Boxlite
+
 logger = logging.getLogger("boxlite.simplebox")
 
-__all__ = ['SimpleBox']
+__all__ = ["SimpleBox"]
 
 
 class StreamType(IntEnum):
-    """Stream type for command execution output (deprecated, use execution.py)."""
+    """Stream type for command execution output."""
+
     STDOUT = 1
     STDERR = 2
 
@@ -37,12 +40,14 @@ class SimpleBox:
     """
 
     def __init__(
-            self,
-            image: str,
-            memory_mib: Optional[int] = None,
-            cpus: Optional[int] = None,
-            runtime: Optional['Boxlite'] = None,
-            **kwargs
+        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.
@@ -52,10 +57,15 @@ class SimpleBox:
             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
+            from .boxlite import Boxlite, BoxOptions
         except ImportError as e:
             raise ImportError(
                 f"BoxLite native extension not found: {e}. "
@@ -68,29 +78,46 @@ class SimpleBox:
         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(
+        # Store box options for deferred creation in __aenter__
+        self._box_options = BoxOptions(
             image=image,
             cpus=cpus,
             memory_mib=memory_mib,
-            working_dir=kwargs.get('working_dir'),
-            env=kwargs.get('env', [])
+            auto_remove=auto_remove,
+            **kwargs,
         )
-        self._box = self._runtime.create(box_opts)
+        self._name = name
+        self._box = None
+        self._started = False
 
     async def __aenter__(self):
-        """Async context manager entry - delegates to Box.__aenter__."""
-        self._box.__aenter__()
+        """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)
@@ -98,17 +125,27 @@ class SimpleBox:
     @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,
+        self,
+        cmd: str,
+        *args: str,
+        env: Optional[dict[str, str]] = None,
     ) -> ExecResult:
         """
         Execute a command in the box and return the result.
@@ -134,6 +171,11 @@ class SimpleBox:
                 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
@@ -165,7 +207,7 @@ class SimpleBox:
             try:
                 async for line in stdout:
                     if isinstance(line, bytes):
-                        stdout_lines.append(line.decode('utf-8', errors='replace'))
+                        stdout_lines.append(line.decode("utf-8", errors="replace"))
                     else:
                         stdout_lines.append(line)
             except Exception as e:
@@ -178,7 +220,7 @@ class SimpleBox:
             try:
                 async for line in stderr:
                     if isinstance(line, bytes):
-                        stderr_lines.append(line.decode('utf-8', errors='replace'))
+                        stderr_lines.append(line.decode("utf-8", errors="replace"))
                     else:
                         stderr_lines.append(line)
             except Exception as e:
@@ -186,8 +228,8 @@ class SimpleBox:
                 pass
 
         # Combine lines
-        stdout = ''.join(stdout_lines)
-        stderr = ''.join(stderr_lines)
+        stdout = "".join(stdout_lines)
+        stderr = "".join(stderr_lines)
 
         try:
             exec_result = await execution.wait()
@@ -206,4 +248,9 @@ class SimpleBox:
 
         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()

boxlite/sync_api/__init__.py

@@ -0,0 +1,65 @@
+"""
+BoxLite Sync API - Synchronous wrappers using greenlet fiber switching.
+
+This module provides synchronous wrappers for BoxLite's async API using
+greenlet fiber switching. This allows sync code to execute async operations
+without blocking the event loop.
+
+Architecture:
+- A dispatcher fiber runs the asyncio event loop
+- User code runs in the main fiber
+- _sync() method switches between fibers to execute async operations
+
+Usage:
+    from boxlite import SyncCodeBox, SyncSimpleBox
+
+    # Simplest usage - standalone (like async API)
+    with SyncCodeBox() as box:
+        result = box.run("print('Hello!')")
+        print(result)
+
+    with SyncSimpleBox(image="alpine:latest") as box:
+        result = box.exec("echo", "Hello")
+        print(result.stdout)
+
+    # Or with explicit runtime (for multiple boxes)
+    from boxlite import SyncBoxlite
+
+    with SyncBoxlite.default() as runtime:
+        box = runtime.create(BoxOptions(image="alpine:latest"))
+        execution = box.exec("echo", ["Hello"])
+        for line in execution.stdout():
+            print(line)
+        box.stop()
+
+Requirements:
+    - greenlet>=3.0.0 (install with: pip install boxlite[sync])
+
+Note:
+    This API cannot be used from within an async context (e.g., inside
+    an async function or when an event loop is already running).
+    Use the async API (CodeBox, SimpleBox) in those cases.
+"""
+
+from ._boxlite import SyncBoxlite
+from ._sync_base import SyncBase, SyncContextManager
+from ._box import SyncBox
+from ._execution import SyncExecution, SyncExecStdout, SyncExecStderr
+from ._simplebox import SyncSimpleBox
+from ._codebox import SyncCodeBox
+
+__all__ = [
+    # Entry point
+    "SyncBoxlite",
+    # Base classes
+    "SyncBase",
+    "SyncContextManager",
+    # Native API mirrors
+    "SyncBox",
+    "SyncExecution",
+    "SyncExecStdout",
+    "SyncExecStderr",
+    # Convenience wrappers
+    "SyncSimpleBox",
+    "SyncCodeBox",
+]

boxlite/sync_api/_box.py

@@ -0,0 +1,133 @@
+"""
+SyncBox - Synchronous wrapper for Box.
+
+Mirrors the native Box API exactly, but with synchronous methods.
+"""
+
+from typing import TYPE_CHECKING, List, Optional, Tuple
+
+if TYPE_CHECKING:
+    from ._boxlite import SyncBoxlite
+    from ._execution import SyncExecution
+    from ..boxlite import Box, BoxInfo, BoxMetrics
+
+__all__ = ["SyncBox"]
+
+
+class SyncBox:
+    """
+    Synchronous wrapper for Box.
+
+    Provides the same API as the native Box class, but with synchronous methods.
+    Uses greenlet fiber switching internally to bridge async operations.
+
+    Usage:
+        with SyncBoxlite.default() as runtime:
+            box = runtime.create(BoxOptions(image="alpine:latest"))
+
+            execution = box.exec("echo", ["Hello"])
+            stdout = execution.stdout()
+
+            for line in stdout:
+                print(line)
+
+            result = execution.wait()
+            box.stop()
+    """
+
+    def __init__(
+        self,
+        runtime: "SyncBoxlite",
+        box: "Box",
+    ) -> None:
+        """
+        Create a SyncBox wrapper.
+
+        Args:
+            runtime: The SyncBoxlite runtime providing event loop and dispatcher
+            box: The native Box object to wrap
+        """
+        from ._sync_base import SyncBase
+
+        self._box = box
+        self._runtime = runtime
+        # Create a SyncBase helper for _sync() method
+        self._sync_helper = SyncBase(box, runtime.loop, runtime.dispatcher_fiber)
+
+    def _sync(self, coro):
+        """Run async operation synchronously."""
+        return self._sync_helper._sync(coro)
+
+    @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) -> "BoxInfo":
+        """Get box information (synchronous, no I/O)."""
+        return self._box.info()
+
+    def start(self) -> None:
+        """
+        Start the box (initialize VM).
+
+        For Configured boxes: initializes VM for the first time.
+        For Stopped boxes: restarts the VM.
+
+        This is idempotent - calling start() on a Running box is a no-op.
+        Also called implicitly by exec() if the box is not running.
+        """
+        self._sync(self._box.start())
+
+    def exec(
+        self,
+        cmd: str,
+        args: Optional[List[str]] = None,
+        env: Optional[List[Tuple[str, str]]] = None,
+    ) -> "SyncExecution":
+        """
+        Execute a command in the box.
+
+        Args:
+            cmd: Command to run (e.g., "echo", "python")
+            args: Command arguments as list
+            env: Environment variables as list of (key, value) tuples
+
+        Returns:
+            SyncExecution handle for streaming output and waiting for completion.
+
+        Example:
+            execution = box.exec("echo", ["Hello, World!"])
+            for line in execution.stdout():
+                print(line)
+            result = execution.wait()
+            print(f"Exit code: {result.exit_code}")
+        """
+        from ._execution import SyncExecution
+
+        # Run the async exec and get the Execution handle
+        execution = self._sync(self._box.exec(cmd, args, env))
+        return SyncExecution(self._runtime, execution)
+
+    def stop(self) -> None:
+        """Stop the box (preserves state for potential restart)."""
+        self._sync(self._box.stop())
+
+    def metrics(self) -> "BoxMetrics":
+        """Get box metrics (CPU, memory usage, etc.)."""
+        return self._sync(self._box.metrics())
+
+    # Context manager support
+    def __enter__(self) -> "SyncBox":
+        """Enter context - starts the box."""
+        self._sync(self._box.__aenter__())
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit context - stops the box."""
+        self._sync(self._box.__aexit__(exc_type, exc_val, exc_tb))