modal 1.1.1.dev3__py3-none-any.whl → 1.1.1.dev4__py3-none-any.whl

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/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/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.dist-info → modal-1.1.1.dev4.dist-info}/METADATA

@@ -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.dist-info → modal-1.1.1.dev4.dist-info}/RECORD

@@ -22,7 +22,7 @@ modal/app.py,sha256=BBR2NmGzZbFGfhKAmtzllD0o4TbVDBbOEs0O2ysSdQo,48277
 modal/app.pyi,sha256=h6JtBA6a7wobdZAuS3QuXrWCUZqfyKPuGV3XdjCqT3k,43753
 modal/call_graph.py,sha256=1g2DGcMIJvRy-xKicuf63IVE98gJSnQsr8R_NVMptNc,2581
 modal/client.py,sha256=pBSZ7lv5dezIL9U9H4tpE0Yz6qA1n0NoNbnJ3KCQMMA,18252
-modal/client.pyi,sha256=UeZZPDn3tf6rBXaczy16F0IBvKzl_jyHrD2tKKX3nhY,15388
+modal/client.pyi,sha256=Cn1yHzML2_Ob9_OujCEM52hIVuWHGNsA7bvHnAqylDQ,15388
 modal/cloud_bucket_mount.py,sha256=YOe9nnvSr4ZbeCn587d7_VhE9IioZYRvF9VYQTQux08,5914
 modal/cloud_bucket_mount.pyi,sha256=-qSfYAQvIoO_l2wsCCGTG5ZUwQieNKXdAO00yP1-LYU,7394
 modal/cls.py,sha256=7A0xGnugQzm8dOfnKMjLjtqekRlRtQ0jPFRYgq6xdUM,40018
@@ -65,8 +65,8 @@ modal/retries.py,sha256=IvNLDM0f_GLUDD5VgEDoN09C88yoxSrCquinAuxT1Sc,5205
 modal/runner.py,sha256=ostdzYpQb-20tlD6dIq7bpWTkZkOhjJBNuMNektqnJA,24068
 modal/runner.pyi,sha256=lbwLljm1cC8d6PcNvmYQhkE8501V9fg0bYqqKX6G4r4,8489
 modal/running_app.py,sha256=v61mapYNV1-O-Uaho5EfJlryMLvIT9We0amUOSvSGx8,1188
-modal/sandbox.py,sha256=zVt9zpRkbFV7amzYO45tTcRaNmpd714H1v8J_tP5nIY,37981
-modal/sandbox.pyi,sha256=TjMI14V-1fnAlb78BG89amEj9Bpuvo5FAAx-mMivsjw,39097
+modal/sandbox.py,sha256=o7LnaMDgfflE6gOvlCESoboFY6_BFZzBydoOhq91t3U,40469
+modal/sandbox.pyi,sha256=SRCbHXMBpBT5PBvKuC2lOTv8YenQHk0lvRj8dAqV_X8,41743
 modal/schedule.py,sha256=ng0g0AqNY5GQI9KhkXZQ5Wam5G42glbkqVQsNpBtbDE,3078
 modal/scheduler_placement.py,sha256=BAREdOY5HzHpzSBqt6jDVR6YC_jYfHMVqOzkyqQfngU,1235
 modal/secret.py,sha256=bpgtv0urwaBOmmJpMTZIwVWUraQlpeu4hW8pbJiGcOA,10546
@@ -151,7 +151,7 @@ modal/requirements/2025.06.txt,sha256=KxDaVTOwatHvboDo4lorlgJ7-n-MfAwbPwxJ0zcJqr
 modal/requirements/PREVIEW.txt,sha256=KxDaVTOwatHvboDo4lorlgJ7-n-MfAwbPwxJ0zcJqrs,312
 modal/requirements/README.md,sha256=9tK76KP0Uph7O0M5oUgsSwEZDj5y-dcUPsnpR0Sc-Ik,854
 modal/requirements/base-images.json,sha256=JYSDAgHTl-WrV_TZW5icY-IJEnbe2eQ4CZ_KN6EOZKU,1304
-modal-1.1.1.dev3.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+modal-1.1.1.dev4.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
 modal_docs/__init__.py,sha256=svYKtV8HDwDCN86zbdWqyq5T8sMdGDj0PVlzc2tIxDM,28
 modal_docs/gen_cli_docs.py,sha256=c1yfBS_x--gL5bs0N4ihMwqwX8l3IBWSkBAKNNIi6bQ,3801
 modal_docs/gen_reference_docs.py,sha256=d_CQUGQ0rfw28u75I2mov9AlS773z9rG40-yq5o7g2U,6359
@@ -174,10 +174,10 @@ modal_proto/options_pb2.pyi,sha256=l7DBrbLO7q3Ir-XDkWsajm0d0TQqqrfuX54i4BMpdQg,1
 modal_proto/options_pb2_grpc.py,sha256=1oboBPFxaTEXt9Aw7EAj8gXHDCNMhZD2VXqocC9l_gk,159
 modal_proto/options_pb2_grpc.pyi,sha256=CImmhxHsYnF09iENPoe8S4J-n93jtgUYD2JPAc0yJSI,247
 modal_proto/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-modal_version/__init__.py,sha256=IDDc1jzJSo8YR7w9tqSWDk7o9R5fr-uwCTOQybe6C44,120
+modal_version/__init__.py,sha256=7l0gBNbxYTxFEtanxGB_DQR1WiHDd4JbDIMYjuXVxn0,120
 modal_version/__main__.py,sha256=2FO0yYQQwDTh6udt1h-cBnGd1c4ZyHnHSI4BksxzVac,105
-modal-1.1.1.dev3.dist-info/METADATA,sha256=ehW2-mB-lMkfAIthpKKVVS-SmmH-McucQbJaJHJd-AI,2461
-modal-1.1.1.dev3.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
-modal-1.1.1.dev3.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
-modal-1.1.1.dev3.dist-info/top_level.txt,sha256=4BWzoKYREKUZ5iyPzZpjqx4G8uB5TWxXPDwibLcVa7k,43
-modal-1.1.1.dev3.dist-info/RECORD,,
+modal-1.1.1.dev4.dist-info/METADATA,sha256=8lO94lXYPCi3v2Sfs35lySEOMSljVUSECSxN7_8p_OA,2461
+modal-1.1.1.dev4.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
+modal-1.1.1.dev4.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
+modal-1.1.1.dev4.dist-info/top_level.txt,sha256=4BWzoKYREKUZ5iyPzZpjqx4G8uB5TWxXPDwibLcVa7k,43
+modal-1.1.1.dev4.dist-info/RECORD,,

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"