modAL 1.3.3__tar.gz → 1.3.4__tar.gz

{modal-1.3.3 → modal-1.3.4}/PKG-INFO

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

{modal-1.3.3 → modal-1.3.4}/modal/_utils/grpc_utils.py

@@ -23,7 +23,7 @@ from grpclib.encoding.base import StatusDetailsCodecBase
 from grpclib.exceptions import StreamTerminatedError
 from grpclib.protocol import H2Protocol
 
-from modal.exception import ConnectionError
+from modal.exception import ClientClosed, ConnectionError
 from modal_proto import api_pb2
 from modal_version import __version__
 
@@ -65,6 +65,22 @@ class Subchannel:
         return True
 
 
+class PermanentCloseableChannel(grpclib.client.Channel):
+    def __init__(self, *args, closed_error_message: str, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.__closed = False
+        self.__closed_error_message = closed_error_message
+
+    async def __connect__(self):
+        if self.__closed:
+            raise ClientClosed(self.__closed_error_message)
+        return await super().__connect__()
+
+    def close(self):
+        self.__closed = True
+        return super().close()
+
+
 RETRYABLE_GRPC_STATUS_CODES = [
     Status.DEADLINE_EXCEEDED,
     Status.UNAVAILABLE,

{modal-1.3.3 → modal-1.3.4}/modal/_utils/task_command_router_client.py

@@ -21,6 +21,7 @@ from modal_proto import api_pb2, task_command_router_pb2 as sr_pb2
 from modal_proto.task_command_router_grpc import TaskCommandRouterStub
 
 from .._grpc_client import grpc_error_converter
+from .._utils.grpc_utils import PermanentCloseableChannel
 from .async_utils import aclosing
 from .grpc_utils import RETRYABLE_GRPC_STATUS_CODES, connect_channel
 
@@ -157,7 +158,7 @@ class TaskCommandRouterClient:
             ssl_context.check_hostname = False
             ssl_context.verify_mode = ssl.CERT_NONE
 
-        channel = grpclib.client.Channel(
+        channel = PermanentCloseableChannel(
             host,
             port,
             ssl=ssl_context,
@@ -165,6 +166,7 @@ class TaskCommandRouterClient:
                 http2_connection_window_size=64 * 1024 * 1024,  # 64 MiB
                 http2_stream_window_size=64 * 1024 * 1024,  # 64 MiB
             ),
+            closed_error_message="Unable to perform operation on a detached sandbox",
         )
 
         await connect_channel(channel)

{modal-1.3.3 → modal-1.3.4}/modal/app.py

@@ -324,6 +324,11 @@ class _App:
         app._running_app = RunningApp(response.app_id, interactive=False)
         return app
 
+    async def get_dashboard_url(self) -> str:
+        if self._app_id is None:
+            raise InvalidError("App is not running")
+        return f"https://modal.com/id/{self._app_id}"
+
     def set_description(self, description: str):
         """mdmd:hidden
         Set the description of the App before it starts running.

{modal-1.3.3 → modal-1.3.4}/modal/app.pyi

@@ -226,6 +226,7 @@ class _App:
         """
         ...
 
+    async def get_dashboard_url(self) -> str: ...
     def set_description(self, description: str):
         """mdmd:hidden
         Set the description of the App before it starts running.
@@ -833,6 +834,12 @@ class App:
 
     lookup: typing.ClassVar[__lookup_spec]
 
+    class __get_dashboard_url_spec(typing_extensions.Protocol):
+        def __call__(self, /) -> str: ...
+        async def aio(self, /) -> str: ...
+
+    get_dashboard_url: __get_dashboard_url_spec
+
     def set_description(self, description: str):
         """mdmd:hidden
         Set the description of the App before it starts running.

{modal-1.3.3 → modal-1.3.4}/modal/client.pyi

@@ -31,7 +31,7 @@ class _Client:
     client_type: int
 
     def __init__(
-        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "1.3.3"
+        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "1.3.4"
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.
@@ -163,7 +163,7 @@ class Client:
     client_type: int
 
     def __init__(
-        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "1.3.3"
+        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "1.3.4"
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

{modal-1.3.3 → modal-1.3.4}/modal/cloud_bucket_mount.py

@@ -121,7 +121,9 @@ class _CloudBucketMount:
 
 
 def cloud_bucket_mounts_to_proto(mounts: Sequence[tuple[str, _CloudBucketMount]]) -> list[api_pb2.CloudBucketMount]:
-    """Helper function to convert `CloudBucketMount` to a list of protobufs that can be passed to the server."""
+    """mdmd:hidden
+    Helper function to convert `CloudBucketMount` to a list of protobufs that can be passed to the server.
+    """
     cloud_bucket_mounts: list[api_pb2.CloudBucketMount] = []
 
     for path, mount in mounts:

{modal-1.3.3 → modal-1.3.4}/modal/cloud_bucket_mount.pyi

@@ -126,7 +126,9 @@ class _CloudBucketMount:
 def cloud_bucket_mounts_to_proto(
     mounts: typing.Sequence[tuple[str, _CloudBucketMount]],
 ) -> list[modal_proto.api_pb2.CloudBucketMount]:
-    """Helper function to convert `CloudBucketMount` to a list of protobufs that can be passed to the server."""
+    """mdmd:hidden
+    Helper function to convert `CloudBucketMount` to a list of protobufs that can be passed to the server.
+    """
     ...
 
 class CloudBucketMount:

{modal-1.3.3 → modal-1.3.4}/modal/gpu.py

@@ -199,6 +199,9 @@ GPU_T = Union[None, str, _GPUConfig]
 
 
 def parse_gpu_config(value: GPU_T) -> api_pb2.GPUConfig:
+    """mdmd:hidden
+    Parses a GPU config into a protobuf representation.
+    """
     if isinstance(value, _GPUConfig):
         return value._to_proto()
     elif isinstance(value, str):

{modal-1.3.3 → modal-1.3.4}/modal/image.py

@@ -418,6 +418,7 @@ class _Image(_Object, type_prefix="im"):
     ]  # added as mounts on any container referencing the Image, see `def _mount_layers`
     _added_python_source_set: frozenset[str]  # used to warn about missing mounts during auto-mount deprecation
     _metadata: Optional[api_pb2.ImageMetadata] = None  # set on hydration, private for now
+    _is_empty: bool
 
     def _initialize_from_empty(self):
         self.inside_exceptions = []
@@ -425,6 +426,7 @@ class _Image(_Object, type_prefix="im"):
         self._deferred_mounts = ()
         self._added_python_source_set = frozenset()
         self.force_build = False
+        self._is_empty = False
 
     def _initialize_from_other(self, other: "_Image"):
         self.inside_exceptions = other.inside_exceptions
@@ -432,6 +434,7 @@ class _Image(_Object, type_prefix="im"):
         self._serve_mounts = other._serve_mounts
         self._deferred_mounts = other._deferred_mounts
         self._added_python_source_set = other._added_python_source_set
+        self._is_empty = other._is_empty
 
     def _get_metadata(self) -> Optional[Message]:
         return self._metadata
@@ -721,6 +724,12 @@ class _Image(_Object, type_prefix="im"):
         )
         return obj
 
+    @staticmethod
+    def _from_scratch() -> "_Image":
+        image = _Image.from_registry("scratch")
+        image._is_empty = True
+        return image
+
     def _copy_mount(self, mount: _Mount, remote_path: Union[str, Path] = ".") -> "_Image":
         """mdmd:hidden
         Internal

{modal-1.3.3 → modal-1.3.4}/modal/image.pyi

@@ -143,6 +143,7 @@ class _Image(modal._object._Object):
     _deferred_mounts: collections.abc.Sequence[modal.mount._Mount]
     _added_python_source_set: frozenset[str]
     _metadata: typing.Optional[modal_proto.api_pb2.ImageMetadata]
+    _is_empty: bool
 
     def _initialize_from_empty(self): ...
     def _initialize_from_other(self, other: _Image): ...
@@ -186,6 +187,8 @@ class _Image(modal._object._Object):
         _namespace: int = 1,
         _do_assert_no_mount_layers: bool = True,
     ): ...
+    @staticmethod
+    def _from_scratch() -> _Image: ...
     def _copy_mount(self, mount: modal.mount._Mount, remote_path: typing.Union[str, pathlib.Path] = ".") -> _Image:
         """mdmd:hidden
         Internal
@@ -1058,6 +1061,7 @@ class Image(modal.object.Object):
     _deferred_mounts: collections.abc.Sequence[modal.mount.Mount]
     _added_python_source_set: frozenset[str]
     _metadata: typing.Optional[modal_proto.api_pb2.ImageMetadata]
+    _is_empty: bool
 
     def __init__(self, *args, **kwargs):
         """mdmd:hidden"""
@@ -1105,6 +1109,8 @@ class Image(modal.object.Object):
         _namespace: int = 1,
         _do_assert_no_mount_layers: bool = True,
     ): ...
+    @staticmethod
+    def _from_scratch() -> Image: ...
     def _copy_mount(self, mount: modal.mount.Mount, remote_path: typing.Union[str, pathlib.Path] = ".") -> Image:
         """mdmd:hidden
         Internal

{modal-1.3.3 → modal-1.3.4}/modal/io_streams.py

@@ -628,6 +628,9 @@ class _StreamReader(Generic[T]):
 
 
 MAX_BUFFER_SIZE = 2 * 1024 * 1024
+# Larger buffer limit for the new exec path via the task command router.
+# This applies only to task_exec_stdin_write; legacy ContainerExec paths keep MAX_BUFFER_SIZE.
+TASK_COMMAND_ROUTER_MAX_BUFFER_SIZE = 16 * 1024 * 1024
 
 
 class _StreamWriterThroughServer:
@@ -721,7 +724,7 @@ class _StreamWriterThroughCommandRouter:
         if isinstance(data, (bytes, bytearray, memoryview, str)):
             if isinstance(data, str):
                 data = data.encode("utf-8")
-            if len(self._buffer) + len(data) > MAX_BUFFER_SIZE:
+            if len(self._buffer) + len(data) > TASK_COMMAND_ROUTER_MAX_BUFFER_SIZE:
                 raise BufferError("Buffer size exceed limit. Call drain to flush the buffer.")
             self._buffer.extend(data)
         else:

{modal-1.3.3 → modal-1.3.4}/modal/network_file_system.py

@@ -37,6 +37,7 @@ NETWORK_FILE_SYSTEM_PUT_FILE_CLIENT_TIMEOUT = (
 def network_file_system_mount_protos(
     validated_network_file_systems: list[tuple[str, "_NetworkFileSystem"]],
 ) -> list[api_pb2.SharedVolumeMount]:
+    """mdmd:hidden"""
     network_file_system_mounts = []
     # Relies on dicts being ordered (true as of Python 3.6).
     for path, volume in validated_network_file_systems:

{modal-1.3.3 → modal-1.3.4}/modal/network_file_system.pyi

@@ -11,7 +11,9 @@ import typing_extensions
 
 def network_file_system_mount_protos(
     validated_network_file_systems: list[tuple[str, _NetworkFileSystem]],
-) -> list[modal_proto.api_pb2.SharedVolumeMount]: ...
+) -> list[modal_proto.api_pb2.SharedVolumeMount]:
+    """mdmd:hidden"""
+    ...
 
 class _NetworkFileSystem(modal._object._Object):
     """A shared, writable file system accessible by one or more Modal functions.

{modal-1.3.3 → modal-1.3.4}/modal/sandbox.py

@@ -35,7 +35,7 @@ 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 ExecutionError, InvalidError, SandboxTerminatedError, SandboxTimeoutError
+from .exception import ClientClosed, ExecutionError, InvalidError, SandboxTerminatedError, SandboxTimeoutError
 from .file_io import FileWatchEvent, FileWatchEventType, _FileIO
 from .gpu import GPU_T
 from .image import _Image
@@ -116,6 +116,7 @@ class _Sandbox(_Object, type_prefix="sb"):
     _tunnels: Optional[dict[int, Tunnel]]
     _enable_snapshot: bool
     _command_router_client: Optional[TaskCommandRouterClient]
+    _attached: bool
 
     @staticmethod
     def _default_pty_info() -> api_pb2.PTYInfo:
@@ -516,6 +517,40 @@ class _Sandbox(_Object, type_prefix="sb"):
         self._enable_snapshot = False
         self._command_router_client = None
 
+    def _initialize_from_other(self, other):
+        super()._initialize_from_other(other)
+        self._attached = other._attached
+
+    def _initialize_from_empty(self):
+        super()._initialize_from_empty()
+        self._attached = True
+
+    async def detach(self):
+        """Disconnects your client from the sandbox and cleans up resources assoicated with the connection.
+
+        Be sure to only call `detach` when you are done interacting with the sandbox. After calling `detach`,
+        any operation using the Sandbox object is not guaranteed to work anymore. If you want to continue interacting
+        with a running sandbox, use `Sandbox.from_id` to get a new Sandbox object.
+        """
+        if not self._attached:
+            return
+        if self._command_router_client is not None:
+            await self._command_router_client.close()
+        self._attached = False
+
+    @property
+    def _client(self):
+        self._ensure_attached()
+        return self.__client
+
+    @_client.setter
+    def _client(self, value):
+        self.__client = value
+
+    def _ensure_attached(self):
+        if not self._attached:
+            raise ClientClosed("Unable to perform operation on a detached sandbox")
+
     @staticmethod
     async def from_name(
         app_name: str,
@@ -609,21 +644,57 @@ class _Sandbox(_Object, type_prefix="sb"):
 
         return image
 
-    async def _experimental_mount_image(self, path: Union[PurePosixPath, str], image: Optional[_Image]):
-        """Mount an Image at a path in the Sandbox filesystem."""
+    async def mount_image(self, path: Union[PurePosixPath, str], image: _Image):
+        """Mount an Image at a specified path in a running Sandbox.
+
+        `path` should be a directory. If it doesn't exist it will be created. If it exists and contains
+        data, the previous directory will be replaced by the mount.
+
+        The `image` argument currently only supports Images that are either:
+        - prebuilt using `image.build()`
+        - referenced by image id, e.g. `Image.from_id(...)`
+        - filesystem/directory snapshots e.g. created by `.snapshot_directory()`
+        or `.snapshot_filesystem()`"
+
+        Usage:
+        ```py notest
+        user_project_snapshot: Image = sandbox_session_1.snapshot_directory("/user_project")
 
-        image_id = None
+        # You can later mount this snapshot to another Sandbox:
+        sandbox_session_2 = modal.Sandbox.create(...)
+        sandbox_session_2.mount_image("/user_project", user_project_snapshot)
+        sandbox_session_2.ls("/user_project")
+        ```
+        """
 
-        if image:
-            if not image._object_id:
-                # FIXME
-                raise InvalidError("Image has not been built.")
+        if not isinstance(image, _Image):
+            raise TypeError(f"Sandbox.mount_image(image=...) expects an Image object, got {image!r}")
+
+        if image._mount_layers:
+            raise InvalidError(
+                "Sandbox.mount_image() only supports pre-built images. When using `add_local*` methods, "
+                "specify `copy=True` and call `.build()` before passing the image to `mount_image()`:\n\nE.g.\n"
+                'img = modal.Image.debian_slim().add_local_file("foo", "/foo", copy=True).build(app)\n'
+                "sandbox.mount_image(path, img)"
+            )
+        if image._is_empty:
+            image_id = ""
+        elif image._object_id:
             image_id = image._object_id
         else:
-            image_id = ""  # empty string indicates mount an empty dir
+            raise InvalidError(
+                "Sandbox.mount_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"
+            )
 
         task_id = await self._get_task_id()
         if (command_router_client := await self._get_command_router_client(task_id)) is None:
+            # It used to be the case that sandboxes could either be controlled through the control
+            # plane or through direct connections, but nowadays they should always use direct control
+            # so this error should be unexpected
             raise InvalidError("Mounting directories requires direct Sandbox control - please contact Modal support.")
 
         posix_path = PurePosixPath(path)
@@ -634,8 +705,31 @@ class _Sandbox(_Object, type_prefix="sb"):
         req = sr_pb2.TaskMountDirectoryRequest(task_id=task_id, path=path_bytes, image_id=image_id)
         await command_router_client.mount_image(req)
 
-    async def _experimental_snapshot_directory(self, path: Union[PurePosixPath, str]) -> _Image:
-        """Snapshot local changes to a previously mounted Image, creating a new Image."""
+    async def _experimental_mount_image(self, path: Union[PurePosixPath, str], image: Optional[_Image]):
+        """Deprecated alias for `Sandbox.mount_image()`."""
+        deprecation_warning(
+            (2026, 2, 20),
+            "The `Sandbox._experimental_mount_image()` method is deprecated. Use `Sandbox.mount_image()` instead.",
+        )
+        if image is None:
+            image = _Image._from_scratch()
+        await self.mount_image(path, image)
+
+    async def snapshot_directory(self, path: Union[PurePosixPath, str]) -> _Image:
+        """Snapshot a directory in a running Sandbox, creating a new Image with its content.
+
+        Directory snapshots are currently persisted for 30 days after they were last created or used.
+
+        Usage:
+        ```py notest
+        user_project_snapshot: Image = sandbox_session_1.snapshot_directory("/user_project")
+
+        # You can later mount this snapshot to another Sandbox:
+        sandbox_session_2 = modal.Sandbox.create(...)
+        sandbox_session_2.mount_image("/user_project", user_project_snapshot)
+        sandbox_session_2.ls("/user_project")
+        ```
+        """
 
         task_id = await self._get_task_id()
         if (command_router_client := await self._get_command_router_client(task_id)) is None:
@@ -652,6 +746,15 @@ class _Sandbox(_Object, type_prefix="sb"):
         res = await command_router_client.snapshot_directory(req)
         return _Image._new_hydrated(res.image_id, self._client, None)
 
+    async def _experimental_snapshot_directory(self, path: Union[PurePosixPath, str]) -> _Image:
+        """Deprecated alias for `Sandbox.snapshot_directory()`."""
+        deprecation_warning(
+            (2026, 2, 20),
+            "The `Sandbox._experimental_snapshot_directory()` method is deprecated. "
+            "Use `Sandbox.snapshot_directory()` instead.",
+        )
+        return await self.snapshot_directory(path)
+
     # Live handle methods
 
     async def wait(self, raise_on_termination: bool = True):
@@ -659,7 +762,8 @@ class _Sandbox(_Object, type_prefix="sb"):
 
         while True:
             req = api_pb2.SandboxWaitRequest(sandbox_id=self.object_id, timeout=10)
-            resp = await self._client.stub.SandboxWait(req)
+            # Use the private __client to allow `wait` to work with a detached sandbox
+            resp = await self.__client.stub.SandboxWait(req)
             if resp.result.status:
                 logger.debug(f"Sandbox {self.object_id} wait completed with status {resp.result.status}")
                 self._result = resp.result
@@ -702,7 +806,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         self, user_metadata: Optional[Union[str, dict[str, Any]]] = None
     ) -> SandboxConnectCredentials:
         """
-        [Alpha] Create a token for making HTTP connections to the Sandbox.
+        Create a token for making HTTP connections to the Sandbox.
 
         Also accepts an optional user_metadata string or dict to associate with the token. This metadata
         will be added to the headers by the proxy when forwarding requests to the Sandbox."""
@@ -728,12 +832,32 @@ class _Sandbox(_Object, type_prefix="sb"):
             ),
         )
 
-    async def terminate(self) -> None:
+    @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,  # wait for terminate to complete and return the exit code.
+    ) -> int | None:
         """Terminate Sandbox execution.
 
         This is a no-op if the Sandbox has already finished running."""
-
         await self._client.stub.SandboxTerminate(api_pb2.SandboxTerminateRequest(sandbox_id=self.object_id))
+        if wait:
+            await self.wait(raise_on_termination=False)
+            return self.returncode
 
     async def poll(self) -> Optional[int]:
         """Check if the Sandbox has finished running.
@@ -1079,6 +1203,12 @@ class _Sandbox(_Object, type_prefix="sb"):
             raise ExecutionError(resp.task_result.exception)
         return sandbox
 
+    @overload
+    async def open(
+        self,
+        path: str,
+    ) -> _FileIO[str]: ...
+
     @overload
     async def open(
         self,
@@ -1147,7 +1277,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         [`StreamReader`](https://modal.com/docs/reference/modal.io_streams#modalio_streamsstreamreader) for
         the sandbox's stdout stream.
         """
-
+        self._ensure_attached()
         return self._stdout
 
     @property
@@ -1155,7 +1285,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         """[`StreamReader`](https://modal.com/docs/reference/modal.io_streams#modalio_streamsstreamreader) for
         the Sandbox's stderr stream.
         """
-
+        self._ensure_attached()
         return self._stderr
 
     @property
@@ -1164,7 +1294,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         [`StreamWriter`](https://modal.com/docs/reference/modal.io_streams#modalio_streamsstreamwriter) for
         the Sandbox's stdin stream.
         """
-
+        self._ensure_attached()
         return self._stdin
 
     @property