opensandbox-code-interpreter 0.1.0__py3-none-any.whl

code_interpreter/sync/adapters/__init__.py

@@ -0,0 +1,26 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Adapter implementations for Code Interpreter sync services.
+"""
+
+from code_interpreter.sync.adapters.code_adapter import CodesAdapterSync
+from code_interpreter.sync.adapters.factory import AdapterFactorySync
+
+__all__ = [
+    "AdapterFactorySync",
+    "CodesAdapterSync",
+]

code_interpreter/sync/adapters/code_adapter.py

@@ -0,0 +1,215 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Synchronous adapter for code execution service (including SSE streaming).
+"""
+
+import json
+import logging
+
+import httpx
+from opensandbox.adapters.converter.event_node import EventNode
+from opensandbox.adapters.converter.exception_converter import (
+    ExceptionConverter,
+)
+from opensandbox.adapters.converter.response_handler import (
+    handle_api_error,
+    require_parsed,
+)
+from opensandbox.config.connection_sync import ConnectionConfigSync
+from opensandbox.exceptions import InvalidArgumentException, SandboxApiException
+from opensandbox.models.execd import Execution
+from opensandbox.models.execd_sync import ExecutionHandlersSync
+from opensandbox.models.sandboxes import SandboxEndpoint
+from opensandbox.sync.adapters.converter.execution_event_dispatcher import (
+    ExecutionEventDispatcherSync,
+)
+
+from code_interpreter.models.code_sync import CodeContextSync, SupportedLanguageSync
+from code_interpreter.sync.services.code import CodesSync
+
+logger = logging.getLogger(__name__)
+
+
+class CodesAdapterSync(CodesSync):
+    """
+    Synchronous adapter for code execution service.
+
+    This adapter is the sync counterpart of :class:`code_interpreter.adapters.code_adapter.CodesAdapter`.
+    It wraps the generated execd API client for non-streaming operations and uses direct ``httpx``
+    streaming for SSE output while running code.
+
+    Notes:
+
+    - ``run`` performs blocking SSE streaming via ``httpx.Client.stream``.
+    - Each SSE line is parsed into an :class:`EventNode` and dispatched via
+      :class:`ExecutionEventDispatcherSync` to update the shared :class:`Execution` object
+      and invoke any user-provided handlers.
+    """
+
+    RUN_CODE_PATH = "/code"
+    CREATE_CONTEXT_PATH = "/code/context"
+
+    def __init__(self, execd_endpoint: SandboxEndpoint, connection_config: ConnectionConfigSync) -> None:
+        """
+        Initialize the code service adapter (sync).
+
+        Args:
+            execd_endpoint: Endpoint for execd daemon connection
+            connection_config: Shared connection configuration (transport, headers, timeouts)
+        """
+        self.execd_endpoint = execd_endpoint
+        self.connection_config = connection_config
+        from opensandbox.api.execd import Client
+
+        base_url = f"{self.connection_config.protocol}://{self.execd_endpoint.endpoint}"
+        timeout_seconds = self.connection_config.request_timeout.total_seconds()
+        timeout = httpx.Timeout(timeout_seconds)
+        headers = {"User-Agent": self.connection_config.user_agent, **self.connection_config.headers}
+
+        self._client = Client(base_url=base_url, timeout=timeout)
+        self._httpx_client = httpx.Client(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+            transport=self.connection_config.transport,
+        )
+        self._client.set_httpx_client(self._httpx_client)
+
+        sse_headers = {**headers, "Accept": "text/event-stream", "Cache-Control": "no-cache"}
+        self._sse_client = httpx.Client(
+            headers=sse_headers,
+            timeout=httpx.Timeout(connect=timeout_seconds, read=None, write=timeout_seconds, pool=None),
+            transport=self.connection_config.transport,
+        )
+
+    def _get_execd_url(self, path: str) -> str:
+        """Build URL for execd endpoint."""
+        return f"{self.connection_config.protocol}://{self.execd_endpoint.endpoint}{path}"
+
+    def create_context(self, language: str) -> CodeContextSync:
+        """
+        Create a new execution context for code interpretation (sync).
+
+        Uses the generated API client for this non-streaming operation.
+        """
+        try:
+            from opensandbox.api.execd.api.code_interpreting import create_code_context
+            from opensandbox.api.execd.models.code_context import (
+                CodeContext as ApiCodeContext,
+            )
+            from opensandbox.api.execd.models.code_context_request import (
+                CodeContextRequest,
+            )
+            from opensandbox.api.execd.types import UNSET
+
+            response_obj = create_code_context.sync_detailed(
+                client=self._client,
+                body=CodeContextRequest(language=language),
+            )
+            handle_api_error(response_obj, "Create code context")
+            parsed = require_parsed(response_obj, ApiCodeContext, "Create code context")
+            context_id = parsed.id if parsed.id is not UNSET else None
+            return CodeContextSync(id=context_id, language=parsed.language)
+        except Exception as e:
+            logger.error("Failed to create context", exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    def run(
+        self,
+        code: str,
+        *,
+        context: CodeContextSync | None = None,
+        handlers: ExecutionHandlersSync | None = None,
+    ) -> Execution:
+        """
+        Execute code within the specified context using SSE streaming (sync).
+
+        Args:
+            code: Source code to execute.
+            context: Execution context (language + optional id). If None, a temporary Python context is used.
+            handlers: Optional streaming handlers for stdout/stderr/events.
+
+        Returns:
+            Execution result populated incrementally while streaming events
+
+        Raises:
+            InvalidArgumentException: if code is empty
+            SandboxApiException: if execd returns a non-200 response
+            SandboxException: for other errors converted by :class:`ExceptionConverter`
+        """
+        if not code.strip():
+            raise InvalidArgumentException("Code cannot be empty")
+
+        try:
+            context = context or CodeContextSync(language=SupportedLanguageSync.PYTHON)
+            api_request = {
+                "code": code,
+                "context": {
+                    "language": context.language,
+                    **({"id": context.id} if context.id else {}),
+                },
+            }
+
+            url = self._get_execd_url(self.RUN_CODE_PATH)
+            execution = Execution(id=None, execution_count=None, result=[], error=None)
+            dispatcher = ExecutionEventDispatcherSync(execution, handlers)
+
+            with self._sse_client.stream("POST", url, json=api_request) as response:
+                if response.status_code != 200:
+                    response.read()
+                    raise SandboxApiException(
+                        message=f"Failed to run code. Status code: {response.status_code}",
+                        status_code=response.status_code,
+                    )
+
+                for line in response.iter_lines():
+                    if not line or not line.strip():
+                        continue
+                    data = line
+                    if data.startswith("data:"):
+                        data = data[5:].strip()
+                    try:
+                        event_dict = json.loads(data)
+                        event_node = EventNode(**event_dict)
+                        dispatcher.dispatch(event_node)
+                    except json.JSONDecodeError:
+                        logger.debug("Failed to parse SSE line: %s", line)
+                        continue
+                    except Exception as e:
+                        logger.error("Error processing event: %s", data, exc_info=e)
+                        continue
+
+            return execution
+        except Exception as e:
+            logger.error("Failed to run code (length: %s)", len(code), exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    def interrupt(self, execution_id: str) -> None:
+        """
+        Interrupt a currently running code execution.
+
+        Args:
+            execution_id: Execution id returned by execd for the running code execution
+        """
+        try:
+            from opensandbox.api.execd.api.code_interpreting import interrupt_code
+
+            response_obj = interrupt_code.sync_detailed(client=self._client, id=execution_id)
+            handle_api_error(response_obj, "Interrupt code execution")
+        except Exception as e:
+            logger.error("Failed to interrupt code execution", exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e

code_interpreter/sync/adapters/factory.py

@@ -0,0 +1,54 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Factory for creating Code Interpreter sync services.
+"""
+
+from opensandbox.config.connection_sync import ConnectionConfigSync
+from opensandbox.models.sandboxes import SandboxEndpoint
+
+from code_interpreter.sync.adapters.code_adapter import CodesAdapterSync
+from code_interpreter.sync.services.code import CodesSync
+
+
+class AdapterFactorySync:
+    """
+    Factory for creating Code Interpreter sync service instances.
+
+    This factory centralizes construction of sync services so they all share the same
+    connection configuration (transport, headers, timeouts).
+    """
+
+    def __init__(self, connection_config: ConnectionConfigSync) -> None:
+        """
+        Initialize the factory with shared connection configuration (sync).
+
+        Args:
+            connection_config: Shared connection configuration (transport, headers, timeouts).
+        """
+        self.connection_config = connection_config
+
+    def create_code_execution_service(self, endpoint: SandboxEndpoint) -> CodesSync:
+        """
+        Create a code execution service for the specified endpoint (sync).
+
+        Args:
+            endpoint: Sandbox endpoint for code execution services.
+
+        Returns:
+            Configured sync code service instance.
+        """
+        return CodesAdapterSync(endpoint, self.connection_config)

code_interpreter/sync/code_interpreter.py

@@ -0,0 +1,286 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Synchronous Code Interpreter SDK.
+"""
+
+import logging
+from datetime import datetime, timedelta, timezone
+from uuid import UUID
+
+from opensandbox.constants import DEFAULT_EXECD_PORT
+from opensandbox.exceptions import (
+    InvalidArgumentException,
+    SandboxException,
+    SandboxInternalException,
+)
+from opensandbox.models.sandboxes import (
+    SandboxEndpoint,
+    SandboxInfo,
+    SandboxMetrics,
+)
+from opensandbox.sync.sandbox import SandboxSync
+
+from code_interpreter.sync.adapters.factory import AdapterFactorySync
+from code_interpreter.sync.services.code import CodesSync
+
+logger = logging.getLogger(__name__)
+
+
+class CodeInterpreterSync:
+    """
+    Synchronous Code Interpreter SDK providing secure, isolated code execution capabilities.
+
+    This class mirrors the async :class:`code_interpreter.code_interpreter.CodeInterpreter`, but all
+    operations are **blocking** and executed in the current thread.
+
+    It wraps an existing :class:`opensandbox.sync.sandbox.SandboxSync` instance and adds
+    code-execution APIs (contexts, run with SSE streaming, interrupts) on top.
+
+    Notes:
+
+    - **Blocking**: Do not call these methods directly from an asyncio event loop thread.
+      If you need non-blocking behavior, prefer the async :class:`~code_interpreter.code_interpreter.CodeInterpreter`.
+    - **Lifecycle**: Remote lifecycle is owned by the underlying sandbox. This class delegates
+      pause/resume/kill/renew/metrics to the sandbox.
+
+    Usage Example:
+
+    ```python
+    from opensandbox.sync.sandbox import SandboxSync
+    from code_interpreter.sync.code_interpreter import CodeInterpreterSync
+    from code_interpreter.models.code import SupportedLanguage
+
+    sandbox = SandboxSync.create("python:3.11")
+    interpreter = CodeInterpreterSync.create(sandbox=sandbox)
+
+    ctx = interpreter.codes.create_context(SupportedLanguage.PYTHON)
+    result = interpreter.codes.run("print('hi')", context=ctx)
+
+    sandbox.kill()
+    sandbox.close()
+    ```
+    """
+
+    def __init__(self, sandbox: SandboxSync, code_service: CodesSync) -> None:
+        """
+        Initialize CodeInterpreterSync with sandbox and code service.
+
+        Note: This constructor is for internal use. Use :meth:`create` instead.
+
+        Args:
+            sandbox: Underlying sandbox instance
+            code_service: Code execution service implementation (sync)
+        """
+        self._sandbox = sandbox
+        self._code_service = code_service
+
+    @property
+    def sandbox(self) -> SandboxSync:
+        """
+        Provides access to the underlying sandbox instance.
+
+        Returns:
+            The underlying sandbox instance
+        """
+        return self._sandbox
+
+    @property
+    def id(self) -> UUID:
+        """
+        Gets the unique identifier of this code interpreter (same as underlying sandbox ID).
+
+        Returns:
+            UUID of the code interpreter/sandbox
+        """
+        return self._sandbox.id
+
+    @property
+    def files(self):
+        """
+        Provides access to file system operations within the sandbox.
+
+        Returns:
+            Service for filesystem manipulation
+        """
+        return self._sandbox.files
+
+    @property
+    def commands(self):
+        """
+        Provides access to command execution operations.
+
+        Returns:
+            Service for command execution
+        """
+        return self._sandbox.commands
+
+    @property
+    def metrics(self):
+        """
+        Provides access to sandbox metrics and monitoring.
+
+        Returns:
+            Service for metrics retrieval
+        """
+        return self._sandbox.metrics
+
+    @property
+    def codes(self) -> CodesSync:
+        """
+        Provides access to code execution operations (sync).
+
+        This service enables:
+        - Multi-language code execution (Python, JavaScript, Bash, etc.)
+        - Execution context management with persistent variables
+        - Real-time output streaming and interruption capabilities
+
+        Returns:
+            Service for advanced code execution with session support
+        """
+        return self._code_service
+
+    def get_endpoint(self, port: int) -> SandboxEndpoint:
+        """
+        Gets a specific network endpoint for the underlying sandbox.
+
+        Args:
+            port: The port number to get the endpoint for
+
+        Returns:
+            Endpoint information including host, port, and connection details
+
+        Raises:
+            SandboxException: If endpoint cannot be retrieved
+        """
+        return self._sandbox.get_endpoint(port)
+
+    def get_info(self) -> SandboxInfo:
+        """
+        Gets the current status of this sandbox.
+
+        Returns:
+            Current sandbox status including state and metadata
+
+        Raises:
+            SandboxException: If status cannot be retrieved
+        """
+        return self._sandbox.get_info()
+
+    def get_metrics(self) -> SandboxMetrics:
+        """
+        Gets the current resource usage metrics for the underlying sandbox.
+
+        Returns:
+            Current sandbox metrics including CPU, memory, and I/O statistics
+
+        Raises:
+            SandboxException: If metrics cannot be retrieved
+        """
+        return self._sandbox.get_metrics()
+
+    def renew(self, timeout: timedelta | int) -> None:
+        """
+        Renew the sandbox expiration time to delay automatic termination.
+
+        Args:
+            timeout: Duration to add to the current time to set the new expiration.
+                Can be timedelta or seconds as int.
+
+        Raises:
+            SandboxException: If the operation fails
+        """
+        if isinstance(timeout, int):
+            timeout = timedelta(seconds=timeout)
+        logger.info(
+            "Renew code interpreter %s timeout, estimated expiration to %s",
+            self.id,
+            datetime.now(timezone.utc) + timeout,
+        )
+        self._sandbox.renew(timeout)
+
+    def pause(self) -> None:
+        """
+        Pauses the sandbox while preserving its state.
+
+        Raises:
+            SandboxException: If pause operation fails
+        """
+        logger.info("Pausing code interpreter: %s", self.id)
+        self._sandbox.pause()
+
+    def resume(self) -> None:
+        """
+        Resumes a previously paused sandbox.
+
+        Raises:
+            SandboxException: If resume operation fails
+        """
+        logger.info("Resuming code interpreter: %s", self.id)
+        self._sandbox.resume()
+
+    def kill(self) -> None:
+        """
+        Terminate the remote sandbox instance (irreversible).
+
+        Note: This method does NOT close the local `SandboxSync` object resources (like connection pools).
+        You should call `sandbox().close()` or use the sync context manager on the sandbox to clean up.
+
+        Raises:
+            SandboxException: If termination fails
+        """
+        logger.info("Killing code interpreter: %s", self.id)
+        self._sandbox.kill()
+
+    def is_healthy(self) -> bool:
+        """
+        Checks if the code interpreter and its underlying sandbox are healthy and responsive.
+
+        Returns:
+            True if sandbox is healthy, False otherwise
+        """
+        return self._sandbox.is_healthy()
+
+    @classmethod
+    def create(cls, sandbox: SandboxSync) -> "CodeInterpreterSync":
+        """
+        Create a CodeInterpreterSync from an existing SandboxSync instance (blocking).
+
+        Args:
+            sandbox: Existing sandbox instance to wrap with code execution capabilities
+
+        Returns:
+            CodeInterpreterSync instance wrapping the sandbox
+
+        Raises:
+            InvalidArgumentException: If sandbox is not provided
+            SandboxException: If creation fails
+            SandboxInternalException: If internal service initialization fails
+        """
+        if sandbox is None:
+            raise InvalidArgumentException("Sandbox instance must be provided")
+
+        logger.info("Creating code interpreter from sandbox: %s", sandbox.id)
+        factory = AdapterFactorySync(sandbox.connection_config)
+        try:
+            endpoint = sandbox.get_endpoint(DEFAULT_EXECD_PORT)
+            code_service = factory.create_code_execution_service(endpoint)
+            logger.info("Code interpreter %s created successfully", sandbox.id)
+            return cls(sandbox, code_service)
+        except Exception as e:
+            if isinstance(e, SandboxException):
+                raise
+            raise SandboxInternalException(f"Failed to create code interpreter: {e}", cause=e) from e

code_interpreter/sync/services/__init__.py

@@ -0,0 +1,27 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Synchronous service interfaces (Protocols) for the Code Interpreter sync SDK.
+
+These interfaces mirror the async interfaces under :mod:`code_interpreter.services`,
+but are **blocking** and intended for use with :class:`code_interpreter.sync.code_interpreter.CodeInterpreterSync`.
+"""
+
+from code_interpreter.sync.services.code import CodesSync
+
+__all__ = [
+    "CodesSync",
+]