boxlite 0.1.0.dev0__cp313-cp313-manylinux_2_28_x86_64.whl → 0.1.1.dev0__cp313-cp313-manylinux_2_28_x86_64.whl

boxlite/__init__.py

@@ -5,21 +5,41 @@ Following SQLite philosophy: "BoxLite" for branding, "boxlite" for code APIs.
 """
 
 import os
+import warnings
 from pathlib import Path
 
-# Set BOXLITE_BIN_DIR if not already set, to help Rust find binaries
-if "BOXLITE_BIN_DIR" not in os.environ:
-    # Check if binaries are bundled with the package
-    package_bin_dir = Path(__file__).parent / "bin"
-    if package_bin_dir.exists():
-        os.environ["BOXLITE_BIN_DIR"] = str(package_bin_dir)
+# Import core functionality from Rust extension
+try:
+    from .boxlite import (
+        Options,
+        BoxOptions,
+        Boxlite,
+        Box,
+        BoxInfo,
+    )
 
-from .core.box import Box
-from .boxes import CodeBox
+    __all__ = [
+        "Options",
+        "BoxOptions",
+        "Boxlite",
+        "Box",
+        "BoxInfo",
+    ]
+except ImportError as e:
+    warnings.warn(f"BoxLite native extension not available: {e}", ImportWarning)
+    __all__ = []
 
-# Future specialized containers
-# from .boxes.browser import BrowserBox
-# from .boxes.claude_code import ClaudeCodeBox
+# Import Python convenience wrappers
+try:
+    from .basebox import BaseBox
+    from .codebox import CodeBox
+    __all__.extend(["BaseBox", "CodeBox"])
+except ImportError:
+    pass
 
-__version__ = "0.1.0"
-__all__ = ["Box", "CodeBox"]
+# Future specialized containers can be added here at top-level
+# Example: BrowserBox (see browserbox.py for implementation template)
+# from .browserbox import BrowserBox
+# __all__.append("BrowserBox")
+
+__version__ = "0.1.1-dev"

boxlite/basebox.py

@@ -0,0 +1,205 @@
+"""
+BaseBox - Foundation for specialized container types.
+
+Provides common functionality for all specialized boxes (CodeBox, BrowserBox, etc.)
+"""
+
+from typing import Optional
+import sys
+import os
+import fcntl
+
+
+class BaseBox:
+    """
+    Base class for specialized container types.
+
+    This class encapsulates the common patterns:
+    1. Dual constructor (convenience vs explicit runtime)
+    2. Async context manager support
+    3. Stdio blocking mode restoration
+    4. Runtime lifecycle management
+
+    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,
+        home_dir: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Create a specialized box with its own internal runtime.
+
+        This is the convenience constructor that creates a runtime automatically.
+        For better resource management when creating multiple boxes, use create() instead.
+
+        Args:
+            image: Container image to use
+            memory_mib: Memory limit in MiB
+            cpus: Number of CPU cores
+            home_dir: Runtime home directory (optional)
+            **kwargs: Additional configuration options
+        """
+        try:
+            from .boxlite import Boxlite, Options
+        except ImportError as e:
+            raise ImportError(
+                f"BoxLite native extension not found: {e}. "
+                "Please install with: pip install boxlite"
+            )
+
+        # Create runtime options
+        runtime_opts = Options(
+            home_dir=home_dir,
+            engine=kwargs.get('engine', 'libkrun')
+        )
+
+        # Create the runtime (this acquires the lock)
+        self._runtime = Boxlite(runtime_opts)
+        self._owns_runtime = True
+
+        # Create box using subclass-defined options
+        box_opts = self._create_box_options(image, memory_mib, cpus, **kwargs)
+        self._box = self._runtime.create(box_opts)
+
+    @classmethod
+    def create(
+        cls,
+        runtime,  # Type: Boxlite, but avoid import at module level
+        image: str,
+        memory_mib: Optional[int] = None,
+        cpus: Optional[int] = None,
+        **kwargs
+    ):
+        """
+        Create a specialized box using an existing runtime.
+
+        This is the recommended approach when creating multiple boxes,
+        as it shares a single runtime instance.
+
+        Args:
+            runtime: Existing Boxlite runtime instance
+            image: Container image to use
+            memory_mib: Memory limit in MiB
+            cpus: Number of CPU cores
+            **kwargs: Additional configuration options
+
+        Returns:
+            Specialized box instance
+
+        Example:
+            >>> runtime = boxlite.Boxlite(boxlite.Options())
+            >>> box1 = SomeBox.create(runtime, image="custom:latest")
+            >>> box2 = SomeBox.create(runtime, image="custom:latest", memory_mib=1024)
+        """
+        # Create instance without going through __init__
+        instance = cls.__new__(cls)
+        instance._runtime = runtime
+        instance._owns_runtime = False
+
+        # Create box using subclass-defined options
+        box_opts = instance._create_box_options(image, memory_mib, cpus, **kwargs)
+        instance._box = runtime.create(box_opts)
+
+        return instance
+
+    def _create_box_options(self, image: str, memory_mib: Optional[int], cpus: Optional[int], **kwargs):
+        """
+        Create BoxOptions for this specialized box.
+
+        Subclasses should override this to provide their specific defaults.
+
+        Args:
+            image: Container image
+            memory_mib: Memory limit
+            cpus: CPU cores
+            **kwargs: Additional options
+
+        Returns:
+            BoxOptions instance
+        """
+        try:
+            from .boxlite import BoxOptions
+        except ImportError as e:
+            raise ImportError(
+                f"BoxLite native extension not found: {e}. "
+                "Please install with: pip install boxlite"
+            )
+
+        return BoxOptions(
+            image=image,
+            cpus=cpus,
+            memory_mib=memory_mib,
+            working_dir=kwargs.get('working_dir'),
+            env=kwargs.get('env', [])
+        )
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        self._box.__enter__()
+        # Tokio runtime sets stdout/stderr to non-blocking mode
+        # Restore blocking mode to prevent BlockingIOError when printing
+        self._restore_blocking_mode()
+        return self
+
+    def _restore_blocking_mode(self):
+        """Restore blocking mode on stdout/stderr after Tokio sets them to non-blocking."""
+        for fd in [sys.stdout.fileno(), sys.stderr.fileno()]:
+            try:
+                flags = fcntl.fcntl(fd, fcntl.F_GETFL)
+                if flags & os.O_NONBLOCK:
+                    fcntl.fcntl(fd, fcntl.F_SETFL, flags & ~os.O_NONBLOCK)
+            except (OSError, AttributeError):
+                # Ignore errors (e.g., when stdout/stderr is not a real file)
+                pass
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        result = self._box.__exit__(exc_type, exc_val, exc_tb)
+
+        # Close runtime if we own it
+        if self._owns_runtime:
+            self._runtime.close()
+
+        return result
+
+    @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 execute(self, command: str, *args) -> str:
+        """
+        Execute a command in the container.
+
+        Args:
+            command: Command to execute
+            *args: Command arguments
+
+        Returns:
+            Command output as string
+        """
+        result = await self._box.execute(command, list(args) if args else None)
+        if isinstance(result, list):
+            return '\n'.join(f"[{stream}] {text}" for stream, text in result if text.strip())
+        return str(result)
+
+    def shutdown(self):
+        """
+        Shutdown the box and release resources.
+
+        Note: Usually not needed as context manager handles cleanup.
+        """
+        self._box.shutdown()
+        if self._owns_runtime:
+            self._runtime.close()

boxlite/browserbox.py

@@ -0,0 +1,104 @@
+"""
+BrowserBox - Secure web browser container (example).
+
+This is a future specialized box showing how to extend BaseBox.
+"""
+
+from typing import Optional
+from .basebox import BaseBox
+
+
+class BrowserBox(BaseBox):
+    """
+    Secure container for browser automation (future implementation).
+
+    Example of how to create specialized boxes by inheriting from BaseBox.
+
+    Usage:
+        >>> runtime = boxlite.Boxlite(boxlite.Options())
+        >>> browser = BrowserBox.create(runtime)
+        >>> await browser.navigate("https://example.com")
+    """
+
+    def __init__(
+        self,
+        image: str = "browserbox:latest",
+        memory_mib: Optional[int] = 2048,  # Browsers need more memory
+        cpus: Optional[int] = None,
+        home_dir: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Create a new BrowserBox with its own internal runtime.
+
+        Args:
+            image: Container image with browser (default: browserbox:latest)
+            memory_mib: Memory limit in MiB (default: 2048 for browsers)
+            cpus: Number of CPU cores
+            home_dir: Runtime home directory (optional)
+            **kwargs: Additional configuration options
+        """
+        super().__init__(image, memory_mib, cpus, home_dir, **kwargs)
+
+    @classmethod
+    def create(
+        cls,
+        runtime,
+        image: str = "browserbox:latest",
+        memory_mib: Optional[int] = 2048,
+        cpus: Optional[int] = None,
+        **kwargs
+    ):
+        """
+        Create a BrowserBox using an existing runtime.
+
+        Args:
+            runtime: Existing Boxlite runtime instance
+            image: Container image with browser
+            memory_mib: Memory limit in MiB (default: 2048)
+            cpus: Number of CPU cores
+            **kwargs: Additional configuration options
+
+        Returns:
+            BrowserBox instance
+        """
+        return super(BrowserBox, cls).create(runtime, image, memory_mib, cpus, **kwargs)
+
+    async def navigate(self, url: str) -> str:
+        """
+        Navigate browser to URL (example method).
+
+        Args:
+            url: URL to navigate to
+
+        Returns:
+            Page content or status
+        """
+        # Example implementation - would use actual browser automation
+        return await self.execute("curl", "-L", url)
+
+    async def screenshot(self, path: str) -> str:
+        """
+        Take a screenshot (example method).
+
+        Args:
+            path: Path to save screenshot
+
+        Returns:
+            Status message
+        """
+        # Example implementation - would use actual browser automation
+        return await self.execute("echo", "Screenshot would be saved to", path)
+
+    async def eval_js(self, script: str) -> str:
+        """
+        Evaluate JavaScript in browser context (example method).
+
+        Args:
+            script: JavaScript code to execute
+
+        Returns:
+            Execution result
+        """
+        # Example implementation - would use actual browser automation
+        return await self.execute("echo", "Would evaluate JS:", script)

boxlite/{boxes/codebox.py → codebox.py}

@@ -4,21 +4,25 @@ CodeBox - Secure Python code execution container.
 Provides a simple, secure environment for running untrusted Python code.
 """
 
-from typing import Optional, Dict, Any, Union
-from ..core.box import Box
+from typing import Optional
+from .basebox import BaseBox
 
 
-class CodeBox(Box):
+class CodeBox(BaseBox):
     """
     Secure container for executing Python code.
 
     CodeBox provides an isolated environment for running untrusted Python code
     with built-in safety and result formatting.
 
-    Example:
-        >>> with CodeBox() as codebox:
-        ...     result = codebox.run("print('Hello, World!')")
-        ...     print(result)
+    Usage Pattern 1 - Explicit runtime (recommended for multiple boxes):
+        >>> runtime = boxlite.Boxlite(boxlite.Options())
+        >>> codebox = CodeBox.create(runtime, memory_mib=512)
+        >>> result = await codebox.run("print('Hello, World!')")
+
+    Usage Pattern 2 - Convenience constructor (creates internal runtime):
+        >>> async with CodeBox() as cb:
+        ...     result = await cb.run("print('Hello, World!')")
     """
 
     def __init__(
@@ -26,34 +30,57 @@ class CodeBox(Box):
         image: str = "python:slim",
         memory_mib: Optional[int] = None,
         cpus: Optional[int] = None,
+        home_dir: Optional[str] = None,
         **kwargs
     ):
         """
-        Create a new CodeBox for Python code execution.
+        Create a new CodeBox with its own internal runtime.
+
+        This is the convenience constructor that creates a runtime automatically.
+        For better resource management when creating multiple boxes, use create() instead.
 
         Args:
             image: Container image with Python (default: python:slim)
             memory_mib: Memory limit in MiB (default: system default)
             cpus: Number of CPU cores (default: system default)
-            **kwargs: Additional Box configuration options
+            home_dir: Runtime home directory (optional)
+            **kwargs: Additional configuration options
         """
-        # Set up Python-specific defaults
-        config = {
-            'engine': kwargs.get('engine', 'libkrun'),
-            'memory_mib': memory_mib,
-            'cpus': cpus,
-        }
+        super().__init__(image, memory_mib, cpus, home_dir, **kwargs)
 
-        # Filter out None values
-        config = {k: v for k, v in config.items() if v is not None}
+    @classmethod
+    def create(
+        cls,
+        runtime,
+        image: str = "python:slim",
+        memory_mib: Optional[int] = None,
+        cpus: Optional[int] = None,
+        **kwargs
+    ):
+        """
+        Create a CodeBox using an existing runtime.
 
-        # Merge with any additional kwargs
-        config.update({k: v for k, v in kwargs.items() if k not in config})
+        This is the recommended approach when creating multiple boxes,
+        as it shares a single runtime instance.
 
-        # Initialize the base Box with Python image
-        super().__init__(image=image, **config)
+        Args:
+            runtime: Existing Boxlite runtime instance
+            image: Container image with Python (default: python:slim)
+            memory_mib: Memory limit in MiB
+            cpus: Number of CPU cores
+            **kwargs: Additional configuration options
+
+        Returns:
+            CodeBox instance
+
+        Example:
+            >>> runtime = boxlite.Boxlite(boxlite.Options())
+            >>> cb1 = CodeBox.create(runtime)
+            >>> cb2 = CodeBox.create(runtime, memory_mib=1024)
+        """
+        return super(CodeBox, cls).create(runtime, image, memory_mib, cpus, **kwargs)
 
-    async def run(self, code: str, timeout: Optional[int] = None) -> Union[str, Dict[str, Any]]:
+    async def run(self, code: str, timeout: Optional[int] = None) -> str:
         """
         Execute Python code in the secure container.
 

boxlite-0.1.1.dev0.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: boxlite
+Version: 0.1.1.dev0
+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
+Requires-Python: >=3.10

boxlite-0.1.1.dev0.dist-info/RECORD

@@ -0,0 +1,12 @@
+boxlite/__init__.py,sha256=ba3Qv2xQPLNPBIGsvj8JEigfg4dUeAEofqcM1n6hc4Y,1028
+boxlite/basebox.py,sha256=KZ6WAqDRrrcWfWFY2FxQGz5mdeeHDNL3CMWYafHawvY,6507
+boxlite/boxlite.cpython-313-x86_64-linux-gnu.so,sha256=tae8LrjCnEFXHxySW6TluUBymC3cGF3ogQeb0HkPdPE,10555929
+boxlite/browserbox.py,sha256=33AkrXebs_nRc70vZauLqWVTkqkzg4_UZWn1b8mhTYo,3077
+boxlite/codebox.py,sha256=COlWcJwqgdxqAti2QoCljreaXF2RC3qxfzgdB05eEXQ,4929
+boxlite/bin/boxlite-guest,sha256=zDK45neGSXikS45k0GjbRQVeawqkPdYk94K16WLFuTs,2702712
+boxlite/bin/boxlite-runner,sha256=8uAND2WajEe3_Z396kiANncQaZ3nO_KEIis_UxDiGJA,3336065
+boxlite.libs/libkrun-fb5f0f92.so.1.15.1,sha256=V_e6pKAizhttRH9qcXtMNiH8ukfAB_ycdF4I64M8HQk,6270745
+boxlite.libs/libkrunfw-6be8cb77.so.4.10.0,sha256=lvCM3V0AoERzdX44V7eZiPyJGgE3_jECBcx8UKwX5vU,19075561
+boxlite-0.1.1.dev0.dist-info/METADATA,sha256=yQHn-IKNbkV7msuDMKAW7yPRSwsl2i3IYcSVuAXhM4c,263
+boxlite-0.1.1.dev0.dist-info/WHEEL,sha256=HMO0puQEz--r12axzxwPwPpTQ-i04eJzIQtJwxCs1kk,109
+boxlite-0.1.1.dev0.dist-info/RECORD,,

boxlite/boxes/__init__.py

@@ -1,11 +0,0 @@
-"""
-Specialized BoxLite containers for specific use cases.
-"""
-
-from .codebox import CodeBox
-
-# Future specialized containers
-# from .browser import BrowserBox
-# from .claude_code import ClaudeCodeBox
-
-__all__ = ["CodeBox"]

boxlite/core/__init__.py

@@ -1,7 +0,0 @@
-"""
-Core BoxLite functionality.
-"""
-
-from .box import Box
-
-__all__ = ["Box"]

boxlite/core/box.py

@@ -1,93 +0,0 @@
-"""
-Base Box class for BoxLite containers.
-
-This is the main user-facing API that wraps the Rust extension.
-"""
-
-from typing import Optional, Dict, Any, List, Tuple
-import sys
-import os
-import fcntl
-
-
-class Box:
-    """
-    Base class for all BoxLite containers.
-
-    Provides secure, lightweight containerization using VM technology.
-    """
-
-    def __init__(self, image: str = "alpine:latest", **kwargs):
-        """
-        Create a new BoxLite container.
-
-        Args:
-            image: Container image to use (default: alpine:latest)
-            **kwargs: Additional configuration options
-                - engine: VM engine to use ('libkrun', 'firecracker')
-                - memory_mib: Memory limit in MiB
-                - cpus: Number of CPU cores
-                - env: Environment variables as list of (key, value) tuples
-        """
-        # Import the Rust extension - the native Box class
-        try:
-            from ..boxlite import Box as NativeBox
-            # Use the native implementation directly
-            self._native_box = NativeBox({
-                'engine': kwargs.get('engine', 'libkrun'),
-                'image': image,
-                **{k: v for k, v in kwargs.items() if k != 'engine'}
-            })
-            self._use_native = True
-            return
-        except ImportError as e:
-            raise ImportError(
-                f"BoxLite native extension not found: {e}. "
-                "Please install with: pip install boxlite"
-            )
-
-
-    async def __aenter__(self):
-        """Async context manager entry."""
-        if self._use_native:
-            self._native_box.__enter__()
-            # Tokio runtime sets stdout/stderr to non-blocking mode
-            # Restore blocking mode to prevent BlockingIOError when printing
-            self._restore_blocking_mode()
-        return self
-
-    def _restore_blocking_mode(self):
-        """Restore blocking mode on stdout/stderr after Tokio sets them to non-blocking."""
-        for fd in [sys.stdout.fileno(), sys.stderr.fileno()]:
-            try:
-                flags = fcntl.fcntl(fd, fcntl.F_GETFL)
-                if flags & os.O_NONBLOCK:
-                    fcntl.fcntl(fd, fcntl.F_SETFL, flags & ~os.O_NONBLOCK)
-            except (OSError, AttributeError):
-                # Ignore errors (e.g., when stdout/stderr is not a real file)
-                pass
-
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
-        """Async context manager exit."""
-        if self._use_native:
-            return self._native_box.__exit__(exc_type, exc_val, exc_tb)
-        return None
-
-    async def execute(self, command: str, *args) -> str:
-        """
-        Execute a command in the container.
-
-        Args:
-            command: Command to execute
-            *args: Command arguments
-
-        Returns:
-            Command output as string
-        """
-        if self._use_native:
-            result = await self._native_box.run_command(command, list(args) if args else None)
-            if isinstance(result, list):
-                return '\n'.join(f"[{stream}] {text}" for stream, text in result if text.strip())
-            return str(result)
-
-        raise RuntimeError("Container not initialized")

boxlite-0.1.0.dev0.dist-info/METADATA

@@ -1,6 +0,0 @@
-Metadata-Version: 2.4
-Name: boxlite
-Version: 0.1.0.dev0
-Summary: Python bindings for Boxlite runtime
-Author: Dorian Zheng
-Requires-Python: >=3.10

boxlite-0.1.0.dev0.dist-info/RECORD

@@ -1,12 +0,0 @@
-boxlite/__init__.py,sha256=uFUVtHBVkjxpx9NxyyRfezBlLDpunNF_J-NCESPg-bg,726
-boxlite/boxlite.cpython-313-x86_64-linux-gnu.so,sha256=PkKT5IphOTcf4-ra_kRWseJFZ6W0ZuDcS8dZrO837IA,2907672
-boxlite/bin/boxlite-guest,sha256=KC2-jmeNazCWw1yglz39lvDNb_b7XvetOWAVYhiYYkw,2595080
-boxlite/bin/boxlite-runner,sha256=mTzEFYTb9BllvobFy8EF1wvNtpN6Zvix-dcn6_Q3pr0,1918793
-boxlite/boxes/__init__.py,sha256=MYz3-Hgr9Qh2krmyp79amIGn5YovUOspLxZ-7HK7320,223
-boxlite/boxes/codebox.py,sha256=ZBeXNjlRwRN0ywqnqCfqYdHYJmeZA2bqnPDOdeHXR6s,3850
-boxlite/core/__init__.py,sha256=gnumx6utojYT12dd4_kGlJmxwMf0Yidnpc3RsLmOFpc,76
-boxlite/core/box.py,sha256=XwcevOo0opXWvVbUNL98Ozb7lf13Ucg8pPVrTqBqbzk,3223
-boxlite.libs/libkrun-a6731198.so.1.15.1,sha256=mvtQ-5ccDtlgnobBgrl2ErSvTOeYf9Ykqqw6_5LignA,5553409
-boxlite-0.1.0.dev0.dist-info/METADATA,sha256=igHLOzaNtebVZfmMCMpQT9sbawuqEYsnpN_bHaVxDp0,146
-boxlite-0.1.0.dev0.dist-info/WHEEL,sha256=HMO0puQEz--r12axzxwPwPpTQ-i04eJzIQtJwxCs1kk,109
-boxlite-0.1.0.dev0.dist-info/RECORD,,