modAL 1.3.6.dev9__tar.gz → 1.3.6.dev11__tar.gz

{modal-1.3.6.dev9 → modal-1.3.6.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.3.6.dev9
+Version: 1.3.6.dev11
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0

{modal-1.3.6.dev9 → modal-1.3.6.dev11}/modal/_utils/task_command_router_client.py

@@ -242,6 +242,44 @@ class TaskCommandRouterClient:
                 lambda: self._call_with_auth_retry(self._stub.TaskExecStart, request)
             )
 
+    async def container_create(self, request: sr_pb2.TaskContainerCreateRequest) -> sr_pb2.TaskContainerCreateResponse:
+        """Create an additional container via task command router."""
+        with grpc_error_converter():
+            return await call_with_retries_on_transient_errors(
+                lambda: self._call_with_auth_retry(self._stub.TaskContainerCreate, request)
+            )
+
+    async def container_terminate(
+        self,
+        request: sr_pb2.TaskContainerTerminateRequest,
+    ) -> sr_pb2.TaskContainerTerminateResponse:
+        """Terminate an additional container via task command router."""
+        with grpc_error_converter():
+            return await call_with_retries_on_transient_errors(
+                lambda: self._call_with_auth_retry(self._stub.TaskContainerTerminate, request)
+            )
+
+    async def container_wait(self, request: sr_pb2.TaskContainerWaitRequest) -> sr_pb2.TaskContainerWaitResponse:
+        """Wait for an additional container via task command router."""
+        with grpc_error_converter():
+            return await call_with_retries_on_transient_errors(
+                lambda: self._call_with_auth_retry(self._stub.TaskContainerWait, request)
+            )
+
+    async def container_get(self, request: sr_pb2.TaskContainerGetRequest) -> sr_pb2.TaskContainerGetResponse:
+        """Get the latest tracked container for a logical name via task command router."""
+        with grpc_error_converter():
+            return await call_with_retries_on_transient_errors(
+                lambda: self._call_with_auth_retry(self._stub.TaskContainerGet, request)
+            )
+
+    async def container_list(self, request: sr_pb2.TaskContainerListRequest) -> sr_pb2.TaskContainerListResponse:
+        """List sandbox containers via task command router."""
+        with grpc_error_converter():
+            return await call_with_retries_on_transient_errors(
+                lambda: self._call_with_auth_retry(self._stub.TaskContainerList, request)
+            )
+
     async def exec_stdio_read(
         self,
         task_id: str,

{modal-1.3.6.dev9 → modal-1.3.6.dev11}/modal/cli/shell.py

@@ -18,6 +18,7 @@ from ..mount import _Mount
 from ..runner import interactive_shell
 from ..sandbox import Sandbox
 from ..secret import Secret
+from ..stream_type import StreamType
 from ..volume import Volume
 from .container import exec
 from .import_refs import (
@@ -64,26 +65,75 @@ def _is_valid_modal_id(ref: str, prefix: str) -> bool:
     return ref.startswith(prefix) and len(ref[len(prefix) :]) > 0 and ref[len(prefix) :].isalnum()
 
 
+def _parse_sandbox_container_ref(ref: str) -> tuple[str, Optional[str]]:
+    """Parse a sandbox:container reference into (sandbox_id, container_name).
+
+    Supports the pattern `sb-xyz:container_name` for accessing sandbox containers.
+    Returns (ref, None) if no container name is specified.
+    """
+    if _is_valid_modal_id(ref, "sb-"):
+        return ref, None
+
+    if ":" in ref:
+        parts = ref.split(":", 1)
+        sandbox_id, container_name = parts[0], parts[1]
+        if _is_valid_modal_id(sandbox_id, "sb-") and container_name:
+            return sandbox_id, container_name
+
+    return ref, None
+
+
 def _is_running_container_ref(ref: Optional[str]) -> bool:
     if ref is None:
         return False
-    return _is_valid_modal_id(ref, "sb-") or _is_valid_modal_id(ref, "ta-")
+    sandbox_id, _ = _parse_sandbox_container_ref(ref)
+    return _is_valid_modal_id(sandbox_id, "sb-") or _is_valid_modal_id(ref, "ta-")
+
+
+def _start_shell_in_sandbox_container(sandbox_id: str, container_name: str, cmd: str, pty: bool) -> None:
+    """Shell into a named container within a sandbox."""
+    try:
+        sandbox = Sandbox.from_id(sandbox_id)
+    except NotFoundError:
+        raise ClickException(f"Sandbox '{sandbox_id}' not found (is it still running?)")
+    except Exception as e:
+        raise ClickException(f"Error connecting to Sandbox '{sandbox_id}': {str(e)}")
+
+    try:
+        sandbox_container = sandbox._experimental_containers.get(name=container_name)
+        if pty:
+            process = sandbox_container.exec(*shlex.split(cmd), pty=pty)
+            process.attach()
+        else:
+            process = sandbox_container.exec(
+                *shlex.split(cmd), pty=pty, stdout=StreamType.STDOUT, stderr=StreamType.STDOUT
+            )
+            process.wait()
+    except NotFoundError:
+        raise ClickException(f"Container '{container_name}' not found in Sandbox '{sandbox_id}'.")
+    except Exception as e:
+        raise ClickException(f"Error exec-ing into container '{container_name}' in Sandbox '{sandbox_id}': {str(e)}")
 
 
 def _start_shell_in_running_container(ref: str, cmd: str, pty: bool) -> None:
-    if _is_valid_modal_id(ref, "sb-"):
+    sandbox_id, container_name = _parse_sandbox_container_ref(ref)
+
+    if container_name is not None:
+        return _start_shell_in_sandbox_container(sandbox_id, container_name, cmd, pty)
+
+    if _is_valid_modal_id(sandbox_id, "sb-"):
         try:
-            sandbox = Sandbox.from_id(ref)
+            sandbox = Sandbox.from_id(sandbox_id)
             ref = sandbox._get_task_id()
-        except NotFoundError as e:
-            raise ClickException(f"Sandbox '{ref}' not found (is it still running?)")
+        except NotFoundError:
+            raise ClickException(f"Sandbox '{sandbox_id}' not found (is it still running?)")
         except Exception as e:
-            raise ClickException(f"Error connecting to Sandbox '{ref}': {str(e)}")
+            raise ClickException(f"Error connecting to Sandbox '{sandbox_id}': {str(e)}")
 
     assert _is_valid_modal_id(ref, "ta-")
     try:
         exec(container_id=ref, command=shlex.split(cmd), pty=pty)
-    except NotFoundError as e:
+    except NotFoundError:
         raise ClickException(f"Container '{ref}' not found (is it still running?)")
     except Exception as e:
         raise ClickException(f"Error connecting to container '{ref}': {str(e)}")

{modal-1.3.6.dev9 → modal-1.3.6.dev11}/modal/client.pyi

@@ -35,7 +35,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.3.6.dev9",
+        version: str = "1.3.6.dev11",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.
@@ -171,7 +171,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.3.6.dev9",
+        version: str = "1.3.6.dev11",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

{modal-1.3.6.dev9 → modal-1.3.6.dev11}/modal/sandbox.py

@@ -35,7 +35,14 @@ from ._utils.name_utils import check_object_name
 from ._utils.task_command_router_client import TaskCommandRouterClient
 from .client import _Client
 from .container_process import _ContainerProcess
-from .exception import ClientClosed, Error, ExecutionError, InvalidError, SandboxTerminatedError, SandboxTimeoutError
+from .exception import (
+    ClientClosed,
+    Error,
+    ExecutionError,
+    InvalidError,
+    SandboxTerminatedError,
+    SandboxTimeoutError,
+)
 from .file_io import FileWatchEvent, FileWatchEventType, _FileIO, ls, mkdir, rm, watch
 from .gpu import GPU_T
 from .image import _Image
@@ -68,6 +75,16 @@ if TYPE_CHECKING:
     import modal.app
 
 
+def _result_returncode(result: Optional[api_pb2.GenericResult]) -> Optional[int]:
+    if result is None or result.status == api_pb2.GenericResult.GENERIC_STATUS_UNSPECIFIED:
+        return None
+    if result.status == api_pb2.GenericResult.GENERIC_STATUS_TIMEOUT:
+        return 124
+    if result.status == api_pb2.GenericResult.GENERIC_STATUS_TERMINATED:
+        return 137
+    return result.exitcode
+
+
 def _validate_exec_args(args: Sequence[str]) -> None:
     # Entrypoint args must be strings.
     if not all(isinstance(arg, str) for arg in args):
@@ -904,6 +921,12 @@ class _Sandbox(_Object, type_prefix="sb"):
             self._command_router_client = await TaskCommandRouterClient.try_init(self._client, task_id)
         return self._command_router_client
 
+    @property
+    def _experimental_containers(self) -> "_SandboxContainerManager":
+        """Manage additional containers running in this Sandbox."""
+        self._ensure_attached()
+        return _SandboxContainerManager(self)
+
     @overload
     async def exec(
         self,
@@ -1006,6 +1029,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         secrets: Optional[Collection[_Secret]] = None,
         text: bool = True,
         bufsize: Literal[-1, 1] = -1,
+        container_id: Optional[str] = None,
     ) -> Union[_ContainerProcess[bytes], _ContainerProcess[str]]:
         """Private method used internally.
 
@@ -1035,6 +1059,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             "text": text,
             "bufsize": bufsize,
             "runtime_debug": config.get("function_runtime_debug"),
+            "container_id": container_id,
         }
         # NB: This must come after the task ID is set, since the sandbox must be
         # scheduled before we can create a router client.
@@ -1057,8 +1082,11 @@ class _Sandbox(_Object, type_prefix="sb"):
         text: bool = True,
         bufsize: Literal[-1, 1] = -1,
         runtime_debug: bool = False,
+        container_id: Optional[str] = None,
     ) -> Union[_ContainerProcess[bytes], _ContainerProcess[str]]:
         """Execute a command through the Modal server."""
+        if container_id:
+            raise RuntimeError("Internal error: additional container exec requires task command router support")
         req = api_pb2.ContainerExecRequest(
             task_id=task_id,
             command=args,
@@ -1097,6 +1125,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         text: bool = True,
         bufsize: Literal[-1, 1] = -1,
         runtime_debug: bool = False,
+        container_id: Optional[str] = None,
     ) -> Union[_ContainerProcess[bytes], _ContainerProcess[str]]:
         """Execute a command through a task command router running on the Modal worker."""
 
@@ -1134,6 +1163,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             secret_ids=secret_ids,
             pty_info=pty_info,
             runtime_debug=runtime_debug,
+            container_id=container_id or "",
         )
         _ = await command_router_client.exec_start(start_req)
 
@@ -1332,17 +1362,7 @@ class _Sandbox(_Object, type_prefix="sb"):
     @property
     def returncode(self) -> Optional[int]:
         """Return code of the Sandbox process if it has finished running, else `None`."""
-        if self._result is None or self._result.status == api_pb2.GenericResult.GENERIC_STATUS_UNSPECIFIED:
-            return None
-
-        # Statuses are converted to exitcodes so we can conform to subprocess API.
-        # TODO: perhaps there should be a separate property that returns an enum directly?
-        elif self._result.status == api_pb2.GenericResult.GENERIC_STATUS_TIMEOUT:
-            return 124
-        elif self._result.status == api_pb2.GenericResult.GENERIC_STATUS_TERMINATED:
-            return 137
-        else:
-            return self._result.exitcode
+        return _result_returncode(self._result)
 
     @staticmethod
     async def list(
@@ -1382,4 +1402,224 @@ class _Sandbox(_Object, type_prefix="sb"):
             before_timestamp = resp.sandboxes[-1].created_at
 
 
+class _SandboxContainer:
+    """Handle to an additional container running in a Sandbox."""
+
+    _result: Optional[api_pb2.GenericResult]
+
+    def __init__(
+        self,
+        sandbox: _Sandbox,
+        container_id: str,
+        container_name: str,
+        result: Optional[api_pb2.GenericResult] = None,
+    ) -> None:
+        self._sandbox = sandbox
+        self._container_id = container_id
+        self._container_name = container_name
+        self._result = result
+
+    @property
+    def object_id(self) -> str:
+        return self._container_id
+
+    @property
+    def name(self) -> str:
+        return self._container_name
+
+    @staticmethod
+    def _from_container_info(sandbox: "_Sandbox", container_info: sr_pb2.TaskContainerInfo) -> "_SandboxContainer":
+        result = container_info.result if container_info.HasField("result") else None
+        return _SandboxContainer(sandbox, container_info.container_id, container_info.container_name, result)
+
+    async def _get_command_router(self) -> tuple[str, "TaskCommandRouterClient"]:
+        """Get task ID and command router client, raising if unavailable."""
+        task_id = await self._sandbox._get_task_id()
+        command_router_client = await self._sandbox._get_command_router_client(task_id)
+        if command_router_client is None:
+            raise RuntimeError("Internal error: additional container operations require task command router support")
+        return task_id, command_router_client
+
+    async def exec(
+        self,
+        *args: str,
+        stdout: StreamType = StreamType.PIPE,
+        stderr: StreamType = StreamType.PIPE,
+        timeout: Optional[int] = None,
+        workdir: Optional[str] = None,
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
+        text: bool = True,
+        bufsize: Literal[-1, 1] = -1,
+        pty: bool = False,
+    ) -> Union[_ContainerProcess[bytes], _ContainerProcess[str]]:
+        pty_info = self._sandbox._default_pty_info() if pty else None
+        return await self._sandbox._exec(
+            *args,
+            pty_info=pty_info,
+            stdout=stdout,
+            stderr=stderr,
+            timeout=timeout,
+            workdir=workdir,
+            env=env,
+            secrets=secrets,
+            text=text,
+            bufsize=bufsize,
+            container_id=self._container_id,
+        )
+
+    async def wait(self, raise_on_termination: bool = True) -> None:
+        if self._result is not None and self._result.status != api_pb2.GenericResult.GENERIC_STATUS_UNSPECIFIED:
+            if self._result.status == api_pb2.GenericResult.GENERIC_STATUS_TERMINATED and raise_on_termination:
+                raise SandboxTerminatedError()
+            return
+
+        task_id, command_router_client = await self._get_command_router()
+        while True:
+            resp = await command_router_client.container_wait(
+                sr_pb2.TaskContainerWaitRequest(
+                    task_id=task_id,
+                    container_id=self._container_id,
+                    timeout=10,
+                )
+            )
+            if resp.result.status:
+                self._result = resp.result
+                if resp.result.status == api_pb2.GenericResult.GENERIC_STATUS_TERMINATED and raise_on_termination:
+                    raise SandboxTerminatedError()
+                return
+
+    async def poll(self) -> Optional[int]:
+        if self._result is not None and self._result.status != api_pb2.GenericResult.GENERIC_STATUS_UNSPECIFIED:
+            return _result_returncode(self._result)
+
+        task_id, command_router_client = await self._get_command_router()
+        resp = await command_router_client.container_wait(
+            sr_pb2.TaskContainerWaitRequest(
+                task_id=task_id,
+                container_id=self._container_id,
+                timeout=0,
+            )
+        )
+        if resp.result.status:
+            self._result = resp.result
+        return _result_returncode(self._result)
+
+    @overload
+    async def terminate(
+        self,
+        *,
+        wait: Literal[True],
+    ) -> int: ...
+
+    @overload
+    async def terminate(
+        self,
+        *,
+        wait: Literal[False] = False,
+    ) -> None: ...
+
+    async def terminate(
+        self,
+        *,
+        wait: bool = False,
+    ) -> int | None:
+        task_id, command_router_client = await self._get_command_router()
+        await command_router_client.container_terminate(
+            sr_pb2.TaskContainerTerminateRequest(
+                task_id=task_id,
+                container_id=self._container_id,
+            )
+        )
+        if wait:
+            await self.wait(raise_on_termination=False)
+            return _result_returncode(self._result)
+
+
+class _SandboxContainerManager:
+    """Creates and manages additional containers in a Sandbox."""
+
+    def __init__(self, sandbox: _Sandbox) -> None:
+        self._sandbox = sandbox
+
+    async def _get_command_router(self) -> tuple[str, "TaskCommandRouterClient"]:
+        """Get task ID and command router client, raising if unavailable."""
+        task_id = await self._sandbox._get_task_id()
+        command_router_client = await self._sandbox._get_command_router_client(task_id)
+        if command_router_client is None:
+            raise RuntimeError("Internal error: additional container operations require task command router support")
+        return task_id, command_router_client
+
+    async def create(
+        self,
+        *args: str,
+        name: str,
+        image: _Image,
+        env: Optional[dict[str, str]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
+        workdir: Optional[str] = None,
+    ) -> _SandboxContainer:
+        if workdir is not None and not workdir.startswith("/"):
+            raise InvalidError(f"workdir must be an absolute path, got: {workdir}")
+        _validate_exec_args(args)
+
+        if image._mount_layers:
+            raise InvalidError(
+                "Sandbox._experimental_containers.create(image=...) only supports pre-built images. "
+                "When using `add_local*` methods, specify `copy=True` and call `.build()` before passing "
+                "the image to `._experimental_containers.create()`:\n\nE.g.\n"
+                'img = modal.Image.debian_slim().add_local_file("foo", "/foo", copy=True).build(app)\n'
+                'sandbox._experimental_containers.create(name="worker", image=img)'
+            )
+        if not image._object_id:
+            raise InvalidError(
+                "Sandbox._experimental_containers.create(image=...) currently only supports Images that are "
+                "either:\n"
+                "- prebuilt using `image.build()`\n"
+                "- referenced by id, e.g. `Image.from_id()`\n"
+                "- filesystem/directory snapshots e.g. created by `.snapshot_directory()` "
+                "or `.snapshot_filesystem()`\n"
+            )
+
+        secrets = secrets or []
+        secret_coros = [secret.hydrate(client=self._sandbox._client) for secret in secrets]
+        await TaskContext.gather(*secret_coros)
+
+        task_id, command_router_client = await self._get_command_router()
+
+        create_req = sr_pb2.TaskContainerCreateRequest(
+            task_id=task_id,
+            container_name=name,
+            image_id=image.object_id,
+            args=list(args),
+            env=env or {},
+            workdir=workdir or "",
+            secret_ids=[secret.object_id for secret in secrets],
+        )
+        create_resp = await command_router_client.container_create(create_req)
+        container_id = create_resp.container_id
+        container_name = create_resp.container_name or name
+        return _SandboxContainer(self._sandbox, container_id, container_name)
+
+    async def get(self, *, name: str, include_terminated: bool = False) -> "_SandboxContainer":
+        task_id, command_router_client = await self._get_command_router()
+        resp = await command_router_client.container_get(
+            sr_pb2.TaskContainerGetRequest(
+                task_id=task_id,
+                container_name=name,
+                include_terminated=include_terminated,
+            )
+        )
+        return _SandboxContainer._from_container_info(self._sandbox, resp.container)
+
+    async def list(self, include_terminated: bool = False) -> builtins.list[_SandboxContainer]:
+        task_id, command_router_client = await self._get_command_router()
+        resp = await command_router_client.container_list(
+            sr_pb2.TaskContainerListRequest(task_id=task_id, include_terminated=include_terminated)
+        )
+        return [_SandboxContainer._from_container_info(self._sandbox, container) for container in resp.containers]
+
+
+SandboxContainer = synchronize_api(_SandboxContainer)
+SandboxContainerManager = synchronize_api(_SandboxContainerManager)
 Sandbox = synchronize_api(_Sandbox)