Overide Image.hydrate to hide from docs and error better (#3333)

* Overide Image.hydrate to hide from docs and error better

* Add .hydrate() call on hydrated image

Author: mwaskom

modal/image.py

@@ -23,6 +23,7 @@
 
 from google.protobuf.message import Message
 from grpclib.exceptions import GRPCError, StreamTerminatedError
+from typing_extensions import Self
 
 from modal_proto import api_pb2
 
@@ -42,7 +43,7 @@
 from .cloud_bucket_mount import _CloudBucketMount
 from .config import config, logger, user_config_path
 from .environments import _get_environment_cached
-from .exception import InvalidError, NotFoundError, RemoteError, VersionError
+from .exception import ExecutionError, InvalidError, NotFoundError, RemoteError, 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
@@ -2295,5 +2296,15 @@ async def _logs(self) -> typing.AsyncGenerator[str, None]:
                 if task_log.data:
                     yield task_log.data
 
+    async def hydrate(self, client: Optional[_Client] = None) -> Self:
+        """mdmd:hidden"""
+        # Image inherits hydrate() from Object but can't be hydrated on demand
+        # Overriding the method lets us hide it from the docs and raise a better error message
+        if not self.is_hydrated:
+            raise ExecutionError(
+                "Images cannot currently be hydrated on demand; you can build an Image by running an App that uses it."
+            )
+        return self
+
 
 Image = synchronize_api(_Image)

test/image_test.py

@@ -17,7 +17,7 @@
 from modal._serialization import serialize
 from modal._utils.async_utils import synchronizer
 from modal.client import Client
-from modal.exception import InvalidError, ModuleNotMountable, NotFoundError, VersionError
+from modal.exception import ExecutionError, InvalidError, ModuleNotMountable, NotFoundError, VersionError
 from modal.experimental import raw_dockerfile_image, raw_registry_image
 from modal.file_pattern_matcher import FilePatternMatcher
 from modal.image import (
@@ -2261,3 +2261,8 @@ def test_raw_registry_image(servicer, client):
 
     with pytest.raises(InvalidError, match="whatever"):
         raw_registry_image(tag, registry_secret=registry_secret, credential_type="whatever")  # type: ignore
+
+
+def test_hydration_refusal():
+    with pytest.raises(ExecutionError, match="Images cannot currently be hydrated on demand"):
+        Image.debian_slim().hydrate()