modal 1.1.1.dev3__tar.gz → 1.1.1.dev4__tar.gz

{modal-1.1.1.dev3 → modal-1.1.1.dev4}/PKG-INFO

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

{modal-1.1.1.dev3 → modal-1.1.1.dev4}/modal/client.pyi

@@ -33,7 +33,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.1.1.dev3",
+        version: str = "1.1.1.dev4",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.
@@ -163,7 +163,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.1.1.dev3",
+        version: str = "1.1.1.dev4",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

{modal-1.1.1.dev3 → modal-1.1.1.dev4}/modal/sandbox.py

@@ -73,6 +73,20 @@ def _validate_exec_args(entrypoint_args: Sequence[str]) -> None:
         )
 
 
+class DefaultSandboxNameOverride(str):
+    """A singleton class that represents the default sandbox name override.
+
+    It is used to indicate that the sandbox name should not be overridden.
+    """
+
+    def __repr__(self) -> str:
+        # NOTE: this must match the instance var name below in order for type stubs to work 😬
+        return "_DEFAULT_SANDBOX_NAME_OVERRIDE"
+
+
+_DEFAULT_SANDBOX_NAME_OVERRIDE = DefaultSandboxNameOverride()
+
+
 class _Sandbox(_Object, type_prefix="sb"):
     """A `Sandbox` object lets you interact with a running sandbox. This API is similar to Python's
     [asyncio.subprocess.Process](https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.subprocess.Process).
@@ -93,6 +107,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         entrypoint_args: Sequence[str],
         image: _Image,
         secrets: Sequence[_Secret],
+        name: Optional[str] = None,
         timeout: Optional[int] = None,
         workdir: Optional[str] = None,
         gpu: GPU_T = None,
@@ -216,6 +231,7 @@ class _Sandbox(_Object, type_prefix="sb"):
                 proxy_id=(proxy.object_id if proxy else None),
                 enable_snapshot=enable_snapshot,
                 verbose=verbose,
+                name=name,
                 experimental_options=experimental_options,
             )
 
@@ -230,7 +246,9 @@ class _Sandbox(_Object, type_prefix="sb"):
     @staticmethod
     async def create(
         *entrypoint_args: str,
-        app: Optional["modal.app._App"] = None,  # Optionally associate the sandbox with an app
+        # Associate the sandbox with an app. Required unless creating from a container.
+        app: Optional["modal.app._App"] = None,
+        name: Optional[str] = None,  # Optionally give the sandbox a name. Unique within an app.
         image: Optional[_Image] = None,  # The image to run as the container for the sandbox.
         secrets: Sequence[_Secret] = (),  # Environment variables to inject into the sandbox.
         network_file_systems: dict[Union[str, os.PathLike], _NetworkFileSystem] = {},
@@ -295,6 +313,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         return await _Sandbox._create(
             *entrypoint_args,
             app=app,
+            name=name,
             image=image,
             secrets=secrets,
             network_file_systems=network_file_systems,
@@ -323,7 +342,9 @@ class _Sandbox(_Object, type_prefix="sb"):
     @staticmethod
     async def _create(
         *entrypoint_args: str,
-        app: Optional["modal.app._App"] = None,  # Optionally associate the sandbox with an app
+        # Associate the sandbox with an app. Required unless creating from a container.
+        app: Optional["modal.app._App"] = None,
+        name: Optional[str] = None,  # Optionally give the sandbox a name. Unique within an app.
         image: Optional[_Image] = None,  # The image to run as the container for the sandbox.
         secrets: Sequence[_Secret] = (),  # Environment variables to inject into the sandbox.
         mounts: Sequence[_Mount] = (),
@@ -376,6 +397,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             entrypoint_args,
             image=image or _default_image,
             secrets=secrets,
+            name=name,
             timeout=timeout,
             workdir=workdir,
             gpu=gpu,
@@ -443,6 +465,27 @@ class _Sandbox(_Object, type_prefix="sb"):
         self._stdin = StreamWriter(self.object_id, "sandbox", self._client)
         self._result = None
 
+    @staticmethod
+    async def from_name(
+        app_name: str,
+        name: str,
+        *,
+        environment_name: Optional[str] = None,
+        client: Optional[_Client] = None,
+    ) -> "_Sandbox":
+        """Get a running Sandbox by name from the given app.
+
+        Raises an error if no running sandbox is found with the given name. A Sandbox's name
+        is the `name` argument passed to `Sandbox.create`.
+        """
+        if client is None:
+            client = await _Client.from_env()
+        env_name = _get_environment_name(environment_name)
+
+        req = api_pb2.SandboxGetFromNameRequest(sandbox_name=name, app_name=app_name, environment_name=env_name)
+        resp = await retry_transient_errors(client.stub.SandboxGetFromName, req)
+        return _Sandbox._new_hydrated(resp.sandbox_id, client, None)
+
     @staticmethod
     async def from_id(sandbox_id: str, client: Optional[_Client] = None) -> "_Sandbox":
         """Construct a Sandbox from an id and look up the Sandbox result.
@@ -719,10 +762,31 @@ class _Sandbox(_Object, type_prefix="sb"):
         return obj
 
     @staticmethod
-    async def _experimental_from_snapshot(snapshot: _SandboxSnapshot, client: Optional[_Client] = None):
+    async def _experimental_from_snapshot(
+        snapshot: _SandboxSnapshot,
+        client: Optional[_Client] = None,
+        *,
+        name: Optional[str] = _DEFAULT_SANDBOX_NAME_OVERRIDE,
+    ):
         client = client or await _Client.from_env()
 
-        restore_req = api_pb2.SandboxRestoreRequest(snapshot_id=snapshot.object_id)
+        if name is _DEFAULT_SANDBOX_NAME_OVERRIDE:
+            restore_req = api_pb2.SandboxRestoreRequest(
+                snapshot_id=snapshot.object_id,
+                sandbox_name_override_type=api_pb2.SandboxRestoreRequest.SANDBOX_NAME_OVERRIDE_TYPE_UNSPECIFIED,
+            )
+        elif name is None:
+            restore_req = api_pb2.SandboxRestoreRequest(
+                snapshot_id=snapshot.object_id,
+                sandbox_name_override_type=api_pb2.SandboxRestoreRequest.SANDBOX_NAME_OVERRIDE_TYPE_NONE,
+            )
+        else:
+            restore_req = api_pb2.SandboxRestoreRequest(
+                snapshot_id=snapshot.object_id,
+                sandbox_name_override=name,
+                sandbox_name_override_type=api_pb2.SandboxRestoreRequest.SANDBOX_NAME_OVERRIDE_TYPE_STRING,
+            )
+
         restore_resp: api_pb2.SandboxRestoreResponse = await retry_transient_errors(
             client.stub.SandboxRestore, restore_req
         )

{modal-1.1.1.dev3 → modal-1.1.1.dev4}/modal/sandbox.pyi

@@ -27,6 +27,17 @@ import typing_extensions
 
 def _validate_exec_args(entrypoint_args: collections.abc.Sequence[str]) -> None: ...
 
+class DefaultSandboxNameOverride(str):
+    """A singleton class that represents the default sandbox name override.
+
+    It is used to indicate that the sandbox name should not be overridden.
+    """
+    def __repr__(self) -> str:
+        """Return repr(self)."""
+        ...
+
+_DEFAULT_SANDBOX_NAME_OVERRIDE: DefaultSandboxNameOverride
+
 class _Sandbox(modal._object._Object):
     """A `Sandbox` object lets you interact with a running sandbox. This API is similar to Python's
     [asyncio.subprocess.Process](https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.subprocess.Process).
@@ -47,6 +58,7 @@ class _Sandbox(modal._object._Object):
         entrypoint_args: collections.abc.Sequence[str],
         image: modal.image._Image,
         secrets: collections.abc.Sequence[modal.secret._Secret],
+        name: typing.Optional[str] = None,
         timeout: typing.Optional[int] = None,
         workdir: typing.Optional[str] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
@@ -79,6 +91,7 @@ class _Sandbox(modal._object._Object):
     async def create(
         *entrypoint_args: str,
         app: typing.Optional[modal.app._App] = None,
+        name: typing.Optional[str] = None,
         image: typing.Optional[modal.image._Image] = None,
         secrets: collections.abc.Sequence[modal.secret._Secret] = (),
         network_file_systems: dict[typing.Union[str, os.PathLike], modal.network_file_system._NetworkFileSystem] = {},
@@ -125,6 +138,7 @@ class _Sandbox(modal._object._Object):
     async def _create(
         *entrypoint_args: str,
         app: typing.Optional[modal.app._App] = None,
+        name: typing.Optional[str] = None,
         image: typing.Optional[modal.image._Image] = None,
         secrets: collections.abc.Sequence[modal.secret._Secret] = (),
         mounts: collections.abc.Sequence[modal.mount._Mount] = (),
@@ -154,6 +168,21 @@ class _Sandbox(modal._object._Object):
         verbose: bool = False,
     ): ...
     def _hydrate_metadata(self, handle_metadata: typing.Optional[google.protobuf.message.Message]): ...
+    @staticmethod
+    async def from_name(
+        app_name: str,
+        name: str,
+        *,
+        environment_name: typing.Optional[str] = None,
+        client: typing.Optional[modal.client._Client] = None,
+    ) -> _Sandbox:
+        """Get a running Sandbox by name from the given app.
+
+        Raises an error if no running sandbox is found with the given name. A Sandbox's name
+        is the `name` argument passed to `Sandbox.create`.
+        """
+        ...
+
     @staticmethod
     async def from_id(sandbox_id: str, client: typing.Optional[modal.client._Client] = None) -> _Sandbox:
         """Construct a Sandbox from an id and look up the Sandbox result.
@@ -243,7 +272,10 @@ class _Sandbox(modal._object._Object):
     async def _experimental_snapshot(self) -> modal.snapshot._SandboxSnapshot: ...
     @staticmethod
     async def _experimental_from_snapshot(
-        snapshot: modal.snapshot._SandboxSnapshot, client: typing.Optional[modal.client._Client] = None
+        snapshot: modal.snapshot._SandboxSnapshot,
+        client: typing.Optional[modal.client._Client] = None,
+        *,
+        name: typing.Optional[str] = _DEFAULT_SANDBOX_NAME_OVERRIDE,
     ): ...
     @typing.overload
     async def open(self, path: str, mode: _typeshed.OpenTextMode) -> modal.file_io._FileIO[str]: ...
@@ -335,6 +367,7 @@ class Sandbox(modal.object.Object):
         entrypoint_args: collections.abc.Sequence[str],
         image: modal.image.Image,
         secrets: collections.abc.Sequence[modal.secret.Secret],
+        name: typing.Optional[str] = None,
         timeout: typing.Optional[int] = None,
         workdir: typing.Optional[str] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
@@ -368,6 +401,7 @@ class Sandbox(modal.object.Object):
             /,
             *entrypoint_args: str,
             app: typing.Optional[modal.app.App] = None,
+            name: typing.Optional[str] = None,
             image: typing.Optional[modal.image.Image] = None,
             secrets: collections.abc.Sequence[modal.secret.Secret] = (),
             network_file_systems: dict[
@@ -417,6 +451,7 @@ class Sandbox(modal.object.Object):
             /,
             *entrypoint_args: str,
             app: typing.Optional[modal.app.App] = None,
+            name: typing.Optional[str] = None,
             image: typing.Optional[modal.image.Image] = None,
             secrets: collections.abc.Sequence[modal.secret.Secret] = (),
             network_file_systems: dict[
@@ -469,6 +504,7 @@ class Sandbox(modal.object.Object):
             /,
             *entrypoint_args: str,
             app: typing.Optional[modal.app.App] = None,
+            name: typing.Optional[str] = None,
             image: typing.Optional[modal.image.Image] = None,
             secrets: collections.abc.Sequence[modal.secret.Secret] = (),
             mounts: collections.abc.Sequence[modal.mount.Mount] = (),
@@ -504,6 +540,7 @@ class Sandbox(modal.object.Object):
             /,
             *entrypoint_args: str,
             app: typing.Optional[modal.app.App] = None,
+            name: typing.Optional[str] = None,
             image: typing.Optional[modal.image.Image] = None,
             secrets: collections.abc.Sequence[modal.secret.Secret] = (),
             mounts: collections.abc.Sequence[modal.mount.Mount] = (),
@@ -539,6 +576,41 @@ class Sandbox(modal.object.Object):
 
     def _hydrate_metadata(self, handle_metadata: typing.Optional[google.protobuf.message.Message]): ...
 
+    class __from_name_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            app_name: str,
+            name: str,
+            *,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> Sandbox:
+            """Get a running Sandbox by name from the given app.
+
+            Raises an error if no running sandbox is found with the given name. A Sandbox's name
+            is the `name` argument passed to `Sandbox.create`.
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            app_name: str,
+            name: str,
+            *,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> Sandbox:
+            """Get a running Sandbox by name from the given app.
+
+            Raises an error if no running sandbox is found with the given name. A Sandbox's name
+            is the `name` argument passed to `Sandbox.create`.
+            """
+            ...
+
+    from_name: __from_name_spec
+
     class __from_id_spec(typing_extensions.Protocol):
         def __call__(self, /, sandbox_id: str, client: typing.Optional[modal.client.Client] = None) -> Sandbox:
             """Construct a Sandbox from an id and look up the Sandbox result.
@@ -753,10 +825,20 @@ class Sandbox(modal.object.Object):
 
     class ___experimental_from_snapshot_spec(typing_extensions.Protocol):
         def __call__(
-            self, /, snapshot: modal.snapshot.SandboxSnapshot, client: typing.Optional[modal.client.Client] = None
+            self,
+            /,
+            snapshot: modal.snapshot.SandboxSnapshot,
+            client: typing.Optional[modal.client.Client] = None,
+            *,
+            name: typing.Optional[str] = _DEFAULT_SANDBOX_NAME_OVERRIDE,
         ): ...
         async def aio(
-            self, /, snapshot: modal.snapshot.SandboxSnapshot, client: typing.Optional[modal.client.Client] = None
+            self,
+            /,
+            snapshot: modal.snapshot.SandboxSnapshot,
+            client: typing.Optional[modal.client.Client] = None,
+            *,
+            name: typing.Optional[str] = _DEFAULT_SANDBOX_NAME_OVERRIDE,
         ): ...
 
     _experimental_from_snapshot: ___experimental_from_snapshot_spec

{modal-1.1.1.dev3 → modal-1.1.1.dev4}/modal.egg-info/PKG-INFO

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

{modal-1.1.1.dev3 → modal-1.1.1.dev4}/modal_version/__init__.py

@@ -1,4 +1,4 @@
 # Copyright Modal Labs 2025
 """Supplies the current version of the modal client library."""
 
-__version__ = "1.1.1.dev3"
+__version__ = "1.1.1.dev4"