modal 1.1.5.dev83__py3-none-any.whl → 1.3.1.dev8__py3-none-any.whl

modal/image.py

@@ -21,40 +21,50 @@ from typing import (
     get_args,
 )
 
+import typing_extensions
 from google.protobuf.message import Message
-from grpclib.exceptions import GRPCError, StreamTerminatedError
+from grpclib.exceptions import StreamTerminatedError
 from typing_extensions import Self
 
 from modal._serialization import serialize_data_format
 from modal_proto import api_pb2
 
+from ._load_context import LoadContext
 from ._object import _Object, live_method_gen
 from ._resolver import Resolver
 from ._serialization import get_preferred_payload_format, serialize
-from ._utils.async_utils import synchronize_api
+from ._utils.async_utils import deprecate_aio_usage, synchronize_api, synchronizer
 from ._utils.blob_utils import MAX_OBJECT_SIZE_BYTES
 from ._utils.docker_utils import (
     extract_copy_command_patterns,
     find_dockerignore_file,
 )
 from ._utils.function_utils import FunctionInfo
-from ._utils.grpc_utils import RETRYABLE_GRPC_STATUS_CODES, retry_transient_errors
+from ._utils.mount_utils import validate_only_modal_volumes
 from .client import _Client
 from .cloud_bucket_mount import _CloudBucketMount
 from .config import config, logger, user_config_path
 from .environments import _get_environment_cached
-from .exception import ExecutionError, InvalidError, NotFoundError, RemoteError, VersionError
+from .exception import (
+    ExecutionError,
+    InternalError,
+    InvalidError,
+    NotFoundError,
+    RemoteError,
+    ServiceError,
+    VersionError,
+)
 from .file_pattern_matcher import NON_PYTHON_FILES, FilePatternMatcher, _ignore_fn
 from .gpu import GPU_T, parse_gpu_config
 from .mount import _Mount, python_standalone_mount_name
 from .network_file_system import _NetworkFileSystem
 from .output import _get_output_manager
-from .scheduler_placement import SchedulerPlacement
 from .secret import _Secret
 from .volume import _Volume
 
 if typing.TYPE_CHECKING:
     import modal._functions
+    import modal.client
 
 # This is used for both type checking and runtime validation
 ImageBuilderVersion = Literal["2023.12", "2024.04", "2024.10", "2025.06", "PREVIEW"]
@@ -64,11 +74,11 @@ ImageBuilderVersion = Literal["2023.12", "2024.04", "2024.10", "2025.06", "PREVI
 # Python versions in mount.py where we specify the "standalone Python versions" we create mounts for.
 # Consider consolidating these multiple sources of truth?
 SUPPORTED_PYTHON_SERIES: dict[ImageBuilderVersion, list[str]] = {
-    "PREVIEW": ["3.9", "3.10", "3.11", "3.12", "3.13"],
-    "2025.06": ["3.9", "3.10", "3.11", "3.12", "3.13"],
-    "2024.10": ["3.9", "3.10", "3.11", "3.12", "3.13"],
-    "2024.04": ["3.9", "3.10", "3.11", "3.12"],
-    "2023.12": ["3.9", "3.10", "3.11", "3.12"],
+    "PREVIEW": ["3.10", "3.11", "3.12", "3.13", "3.14"],
+    "2025.06": ["3.10", "3.11", "3.12", "3.13", "3.14"],
+    "2024.10": ["3.10", "3.11", "3.12", "3.13"],
+    "2024.04": ["3.10", "3.11", "3.12"],
+    "2023.12": ["3.10", "3.11", "3.12"],
 }
 
 LOCAL_REQUIREMENTS_DIR = Path(__file__).parent / "builder"
@@ -373,9 +383,7 @@ async def _image_await_build_result(image_id: str, client: _Client) -> api_pb2.I
     while result_response is None:
         try:
             await join()
-        except (StreamTerminatedError, GRPCError) as exc:
-            if isinstance(exc, GRPCError) and exc.status not in RETRYABLE_GRPC_STATUS_CODES:
-                raise exc
+        except (ServiceError, InternalError, StreamTerminatedError) as exc:
             retry_count += 1
             if retry_count >= 3:
                 raise exc
@@ -433,12 +441,16 @@ class _Image(_Object, type_prefix="im"):
 
         base_image = self
 
-        async def _load(self2: "_Image", resolver: Resolver, existing_object_id: Optional[str]):
+        async def _load(
+            self2: "_Image", resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]
+        ):
             self2._hydrate_from_other(base_image)  # same image id as base image as long as it's lazy
             self2._deferred_mounts = tuple(base_image._deferred_mounts) + (mount,)
             self2._serve_mounts = base_image._serve_mounts | ({mount} if mount.is_local() else set())
 
-        img = _Image._from_loader(_load, "Image(local files)", deps=lambda: [base_image, mount])
+        img = _Image._from_loader(
+            _load, "Image(local files)", deps=lambda: [base_image, mount], load_context_overrides=LoadContext.empty()
+        )
         img._added_python_source_set = base_image._added_python_source_set
         return img
 
@@ -487,6 +499,7 @@ class _Image(_Object, type_prefix="im"):
         context_mount_function: Optional[Callable[[], Optional[_Mount]]] = None,
         force_build: bool = False,
         build_args: dict[str, str] = {},
+        validated_volumes: Optional[Sequence[tuple[str, _Volume]]] = None,
         # For internal use only.
         _namespace: "api_pb2.DeploymentNamespace.ValueType" = api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
         _do_assert_no_mount_layers: bool = True,
@@ -494,6 +507,9 @@ class _Image(_Object, type_prefix="im"):
         if base_images is None:
             base_images = {}
 
+        if validated_volumes is None:
+            validated_volumes = []
+
         if secrets is None:
             secrets = []
         if gpu_config is None:
@@ -514,20 +530,22 @@ class _Image(_Object, type_prefix="im"):
                 deps += (build_function,)
             if image_registry_config and image_registry_config.secret:
                 deps += (image_registry_config.secret,)
+            for _, vol in validated_volumes:
+                deps += (vol,)
             return deps
 
-        async def _load(self: _Image, resolver: Resolver, existing_object_id: Optional[str]):
+        async def _load(self: _Image, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]):
             context_mount = context_mount_function() if context_mount_function else None
             if context_mount:
-                await resolver.load(context_mount)
+                await resolver.load(context_mount, load_context)
 
             if _do_assert_no_mount_layers:
                 for image in base_images.values():
                     # base images can't have
                     image._assert_no_mount_layers()
 
-            assert resolver.app_id  # type narrowing
-            environment = await _get_environment_cached(resolver.environment_name or "", resolver.client)
+            assert load_context.app_id  # type narrowing
+            environment = await _get_environment_cached(load_context.environment_name or "", load_context.client)
             # A bit hacky,but assume that the environment provides a valid builder version
             image_builder_version = cast(ImageBuilderVersion, environment._settings.image_builder_version)
             builder_version = _get_image_builder_version(image_builder_version)
@@ -592,6 +610,17 @@ class _Image(_Object, type_prefix="im"):
                 build_function_id = ""
                 _build_function = None
 
+            # Relies on dicts being ordered (true as of Python 3.6).
+            volume_mounts = [
+                api_pb2.VolumeMount(
+                    mount_path=path,
+                    volume_id=volume.object_id,
+                    allow_background_commits=True,
+                    read_only=volume._read_only,
+                )
+                for path, volume in validated_volumes
+            ]
+
             image_definition = api_pb2.Image(
                 base_images=base_images_pb2s,
                 dockerfile_commands=dockerfile.commands,
@@ -604,10 +633,11 @@ class _Image(_Object, type_prefix="im"):
                 runtime_debug=config.get("function_runtime_debug"),
                 build_function=_build_function,
                 build_args=build_args,
+                volume_mounts=volume_mounts,
             )
 
             req = api_pb2.ImageGetOrCreateRequest(
-                app_id=resolver.app_id,
+                app_id=load_context.app_id,
                 image=image_definition,
                 existing_image_id=existing_object_id or "",  # TODO: ignored
                 build_function_id=build_function_id,
@@ -619,7 +649,7 @@ class _Image(_Object, type_prefix="im"):
                 allow_global_deployment=os.environ.get("MODAL_IMAGE_ALLOW_GLOBAL_DEPLOYMENT") == "1",
                 ignore_cache=config.get("ignore_cache"),
             )
-            resp = await retry_transient_errors(resolver.client.stub.ImageGetOrCreate, req)
+            resp = await load_context.client.stub.ImageGetOrCreate(req)
             image_id = resp.image_id
             result: api_pb2.GenericResult
             metadata: Optional[api_pb2.ImageMetadata] = None
@@ -632,7 +662,7 @@ class _Image(_Object, type_prefix="im"):
             else:
                 # not built or in the process of building - wait for build
                 logger.debug("Waiting for image %s" % image_id)
-                resp = await _image_await_build_result(image_id, resolver.client)
+                resp = await _image_await_build_result(image_id, load_context.client)
                 result = resp.result
                 if resp.HasField("metadata"):
                     metadata = resp.metadata
@@ -662,7 +692,7 @@ class _Image(_Object, type_prefix="im"):
             else:
                 raise RemoteError("Unknown status %s!" % result.status)
 
-            self._hydrate(image_id, resolver.client, metadata)
+            self._hydrate(image_id, load_context.client, metadata)
             local_mounts = set()
             for base in base_images.values():
                 local_mounts |= base._serve_mounts
@@ -671,7 +701,7 @@ class _Image(_Object, type_prefix="im"):
             self._serve_mounts = frozenset(local_mounts)
 
         rep = f"Image({dockerfile_function})"
-        obj = _Image._from_loader(_load, rep, deps=_deps)
+        obj = _Image._from_loader(_load, rep, deps=_deps, load_context_overrides=LoadContext.empty())
         obj.force_build = force_build
         obj._added_python_source_set = frozenset.union(
             frozenset(), *(base._added_python_source_set for base in base_images.values())
@@ -838,23 +868,25 @@ class _Image(_Object, type_prefix="im"):
         img._added_python_source_set |= set(modules)
         return img
 
-    @staticmethod
-    async def from_id(image_id: str, client: Optional[_Client] = None) -> "_Image":
+    @deprecate_aio_usage((2025, 11, 14), "Image.from_id")
+    @classmethod
+    def from_id(cls, image_id: str, client: Optional["modal.client.Client"] = None) -> typing_extensions.Self:
         """Construct an Image from an id and look up the Image result.
 
         The ID of an Image object can be accessed using `.object_id`.
         """
-        if client is None:
-            client = await _Client.from_env()
+        _client = typing.cast(_Client, synchronizer._translate_in(client))
 
-        async def _load(self: _Image, resolver: Resolver, existing_object_id: Optional[str]):
-            resp = await retry_transient_errors(client.stub.ImageFromId, api_pb2.ImageFromIdRequest(image_id=image_id))
-            self._hydrate(resp.image_id, resolver.client, resp.metadata)
+        async def _load(self: _Image, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]):
+            resp = await load_context.client.stub.ImageFromId(api_pb2.ImageFromIdRequest(image_id=image_id))
+            self._hydrate(resp.image_id, load_context.client, resp.metadata)
 
         rep = f"Image.from_id({image_id!r})"
-        obj = _Image._from_loader(_load, rep)
 
-        return obj
+        obj = _Image._from_loader(_load, rep, load_context_overrides=LoadContext(client=_client))
+        obj._object_id = image_id
+
+        return typing.cast(typing_extensions.Self, synchronizer._translate_out(obj))
 
     async def build(self, app: "modal.app._App") -> "_Image":
         """Eagerly build an image.
@@ -867,8 +899,8 @@ class _Image(_Object, type_prefix="im"):
         ```python
         image = modal.Image.debian_slim().uv_pip_install("scipy", "numpy")
 
-        app = modal.App("build-image")
-        with modal.enable_output(), app.run():
+        app = modal.App.lookup("build-image", create_if_missing=True)
+        with modal.enable_output():  # To see logs in your local terminal
             image.build(app)
 
         # Save the image id
@@ -881,7 +913,7 @@ class _Image(_Object, type_prefix="im"):
         Alternatively, you can pre-build a image and use it in a sandbox.
 
         ```python notest
-        app = modal.App.lookup("sandbox-example")
+        app = modal.App.lookup("sandbox-example", create_if_missing=True)
 
         with modal.enable_output():
             image = modal.Image.debian_slim().uv_pip_install("scipy")
@@ -911,11 +943,8 @@ class _Image(_Object, type_prefix="im"):
         if app.app_id is None:
             raise InvalidError("App has not been initialized yet. Use the content manager `app.run()` or `App.lookup`")
 
-        app_id = app.app_id
-        app_client = app._client or await _Client.from_env()
-
-        resolver = Resolver(app_client, app_id=app_id)
-        await resolver.load(self)
+        resolver = Resolver()
+        await resolver.load(self, app._root_load_context)
         return self
 
     def pip_install(
@@ -1690,6 +1719,7 @@ class _Image(_Object, type_prefix="im"):
         *commands: Union[str, list[str]],
         env: Optional[dict[str, Optional[str]]] = None,
         secrets: Optional[Collection[_Secret]] = None,
+        volumes: Optional[dict[Union[str, PurePosixPath], _Volume]] = None,
         gpu: GPU_T = None,
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
     ) -> "_Image":
@@ -1712,6 +1742,7 @@ class _Image(_Object, type_prefix="im"):
             secrets=secrets,
             gpu_config=parse_gpu_config(gpu),
             force_build=self.force_build or force_build,
+            validated_volumes=validate_only_modal_volumes(volumes, "Image.run_commands"),
         )
 
     @staticmethod
@@ -1722,9 +1753,6 @@ class _Image(_Object, type_prefix="im"):
         """A Micromamba base image. Micromamba allows for fast building of small Conda-based containers."""
 
         def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
-            nonlocal python_version
-            if version == "2023.12" and python_version is None:
-                python_version = "3.9"  # Backcompat for old hardcoded default param
             validated_python_version = _validate_python_version(python_version, version)
             micromamba_version = _base_image_config("micromamba", version)
             tag = f"mambaorg/micromamba:{micromamba_version}"
@@ -2279,8 +2307,6 @@ class _Image(_Object, type_prefix="im"):
             # It may be possible to support lambdas eventually, but for now we don't handle them well, so reject quickly
             raise InvalidError("Image.run_function does not support lambda functions.")
 
-        scheduler_placement = SchedulerPlacement(region=region) if region else None
-
         info = FunctionInfo(raw_f)
 
         function = _Function.from_local(
@@ -2292,7 +2318,7 @@ class _Image(_Object, type_prefix="im"):
             volumes=volumes,
             network_file_systems=network_file_systems,
             cloud=cloud,
-            scheduler_placement=scheduler_placement,
+            region=region,
             memory=memory,
             timeout=timeout,
             cpu=cpu,

modal/image.pyi

@@ -124,6 +124,8 @@ async def _image_await_build_result(
     image_id: str, client: modal.client._Client
 ) -> modal_proto.api_pb2.ImageJoinStreamingResponse: ...
 
+SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
+
 class _Image(modal._object._Object):
     """Base class for container images to run functions in.
 
@@ -176,6 +178,7 @@ class _Image(modal._object._Object):
         ] = None,
         force_build: bool = False,
         build_args: dict[str, str] = {},
+        validated_volumes: typing.Optional[collections.abc.Sequence[tuple[str, modal.volume._Volume]]] = None,
         _namespace: int = 1,
         _do_assert_no_mount_layers: bool = True,
     ): ...
@@ -310,13 +313,17 @@ class _Image(modal._object._Object):
         """
         ...
 
-    @staticmethod
-    async def from_id(image_id: str, client: typing.Optional[modal.client._Client] = None) -> _Image:
-        """Construct an Image from an id and look up the Image result.
+    class __from_id_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(self, /, image_id: str, client: typing.Optional[modal.client.Client] = None) -> SUPERSELF:
+            """Construct an Image from an id and look up the Image result.
 
-        The ID of an Image object can be accessed using `.object_id`.
-        """
-        ...
+            The ID of an Image object can be accessed using `.object_id`.
+            """
+            ...
+
+        async def aio(self, /, image_id: str, client: typing.Optional[modal.client.Client] = None): ...
+
+    from_id: typing.ClassVar[__from_id_spec[typing_extensions.Self]]
 
     async def build(self, app: modal.app._App) -> _Image:
         """Eagerly build an image.
@@ -329,8 +336,8 @@ class _Image(modal._object._Object):
         ```python
         image = modal.Image.debian_slim().uv_pip_install("scipy", "numpy")
 
-        app = modal.App("build-image")
-        with modal.enable_output(), app.run():
+        app = modal.App.lookup("build-image", create_if_missing=True)
+        with modal.enable_output():  # To see logs in your local terminal
             image.build(app)
 
         # Save the image id
@@ -343,7 +350,7 @@ class _Image(modal._object._Object):
         Alternatively, you can pre-build a image and use it in a sandbox.
 
         ```python notest
-        app = modal.App.lookup("sandbox-example")
+        app = modal.App.lookup("sandbox-example", create_if_missing=True)
 
         with modal.enable_output():
             image = modal.Image.debian_slim().uv_pip_install("scipy")
@@ -668,6 +675,7 @@ class _Image(modal._object._Object):
         *commands: typing.Union[str, list[str]],
         env: typing.Optional[dict[str, typing.Optional[str]]] = None,
         secrets: typing.Optional[collections.abc.Collection[modal.secret._Secret]] = None,
+        volumes: typing.Optional[dict[typing.Union[str, pathlib.PurePosixPath], modal.volume._Volume]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         force_build: bool = False,
     ) -> _Image:
@@ -1033,8 +1041,6 @@ class _Image(modal._object._Object):
         """mdmd:hidden"""
         ...
 
-SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
-
 class Image(modal.object.Object):
     """Base class for container images to run functions in.
 
@@ -1091,6 +1097,7 @@ class Image(modal.object.Object):
         ] = None,
         force_build: bool = False,
         build_args: dict[str, str] = {},
+        validated_volumes: typing.Optional[collections.abc.Sequence[tuple[str, modal.volume.Volume]]] = None,
         _namespace: int = 1,
         _do_assert_no_mount_layers: bool = True,
     ): ...
@@ -1225,24 +1232,19 @@ class Image(modal.object.Object):
         """
         ...
 
-    class __from_id_spec(typing_extensions.Protocol):
-        def __call__(self, /, image_id: str, client: typing.Optional[modal.client.Client] = None) -> Image:
+    class __from_id_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(self, /, image_id: str, client: typing.Optional[modal.client.Client] = None) -> SUPERSELF:
             """Construct an Image from an id and look up the Image result.
 
             The ID of an Image object can be accessed using `.object_id`.
             """
             ...
 
-        async def aio(self, /, image_id: str, client: typing.Optional[modal.client.Client] = None) -> Image:
-            """Construct an Image from an id and look up the Image result.
-
-            The ID of an Image object can be accessed using `.object_id`.
-            """
-            ...
+        async def aio(self, /, image_id: str, client: typing.Optional[modal.client.Client] = None): ...
 
-    from_id: __from_id_spec
+    from_id: typing.ClassVar[__from_id_spec[typing_extensions.Self]]
 
-    class __build_spec(typing_extensions.Protocol[SUPERSELF]):
+    class __build_spec(typing_extensions.Protocol):
         def __call__(self, /, app: modal.app.App) -> Image:
             """Eagerly build an image.
 
@@ -1254,8 +1256,8 @@ class Image(modal.object.Object):
             ```python
             image = modal.Image.debian_slim().uv_pip_install("scipy", "numpy")
 
-            app = modal.App("build-image")
-            with modal.enable_output(), app.run():
+            app = modal.App.lookup("build-image", create_if_missing=True)
+            with modal.enable_output():  # To see logs in your local terminal
                 image.build(app)
 
             # Save the image id
@@ -1268,7 +1270,7 @@ class Image(modal.object.Object):
             Alternatively, you can pre-build a image and use it in a sandbox.
 
             ```python notest
-            app = modal.App.lookup("sandbox-example")
+            app = modal.App.lookup("sandbox-example", create_if_missing=True)
 
             with modal.enable_output():
                 image = modal.Image.debian_slim().uv_pip_install("scipy")
@@ -1307,8 +1309,8 @@ class Image(modal.object.Object):
             ```python
             image = modal.Image.debian_slim().uv_pip_install("scipy", "numpy")
 
-            app = modal.App("build-image")
-            with modal.enable_output(), app.run():
+            app = modal.App.lookup("build-image", create_if_missing=True)
+            with modal.enable_output():  # To see logs in your local terminal
                 image.build(app)
 
             # Save the image id
@@ -1321,7 +1323,7 @@ class Image(modal.object.Object):
             Alternatively, you can pre-build a image and use it in a sandbox.
 
             ```python notest
-            app = modal.App.lookup("sandbox-example")
+            app = modal.App.lookup("sandbox-example", create_if_missing=True)
 
             with modal.enable_output():
                 image = modal.Image.debian_slim().uv_pip_install("scipy")
@@ -1349,7 +1351,7 @@ class Image(modal.object.Object):
             """
             ...
 
-    build: __build_spec[typing_extensions.Self]
+    build: __build_spec
 
     def pip_install(
         self,
@@ -1648,6 +1650,7 @@ class Image(modal.object.Object):
         *commands: typing.Union[str, list[str]],
         env: typing.Optional[dict[str, typing.Optional[str]]] = None,
         secrets: typing.Optional[collections.abc.Collection[modal.secret.Secret]] = None,
+        volumes: typing.Optional[dict[typing.Union[str, pathlib.PurePosixPath], modal.volume.Volume]] = None,
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         force_build: bool = False,
     ) -> Image:
@@ -2002,7 +2005,7 @@ class Image(modal.object.Object):
         """
         ...
 
-    class ___logs_spec(typing_extensions.Protocol[SUPERSELF]):
+    class ___logs_spec(typing_extensions.Protocol):
         def __call__(self, /) -> typing.Generator[str, None, None]:
             """Streams logs from an image, or returns logs from an already completed image.
 
@@ -2017,7 +2020,7 @@ class Image(modal.object.Object):
             """
             ...
 
-    _logs: ___logs_spec[typing_extensions.Self]
+    _logs: ___logs_spec
 
     class __hydrate_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /, client: typing.Optional[modal.client.Client] = None) -> SUPERSELF: