modal 1.5.4.dev13__tar.gz → 1.5.4.dev15__tar.gz

{modal-1.5.4.dev13 → modal-1.5.4.dev15}/PKG-INFO

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

{modal-1.5.4.dev13 → modal-1.5.4.dev15}/modal/_image.py

@@ -30,9 +30,11 @@ from modal_proto import api_pb2
 
 from ._environments import _get_environment_cached
 from ._load_context import LoadContext
+from ._logs_manager import _ImageLogsManager
 from ._object import _Object, live_method_gen
 from ._resolver import Resolver
 from ._serialization import get_preferred_payload_format, serialize
+from ._supports_logs import _ImageLogQueryData
 from ._utils.async_utils import TaskContext, deprecate_aio_usage, synchronizer
 from ._utils.blob_utils import MAX_OBJECT_SIZE_BYTES
 from ._utils.docker_utils import (
@@ -47,10 +49,10 @@ from .cloud_bucket_mount import _CloudBucketMount
 from .config import config, logger, user_config_path
 from .exception import (
     ExecutionError,
+    ImageBuildError,
     InternalError,
     InvalidError,
     NotFoundError,
-    RemoteError,
     ServiceError,
     VersionError,
 )
@@ -477,6 +479,12 @@ def _requires_image_instance(method):
     return wrapper
 
 
+@dataclass(frozen=True)
+class _FailedBuildAttempt:
+    image_id: str
+    client: _Client
+
+
 class _Image(_Object, type_prefix="im"):
     """Base class for container images to run functions in.
 
@@ -493,6 +501,9 @@ class _Image(_Object, type_prefix="im"):
     _added_python_source_set: frozenset[str]  # used to warn about missing mounts during auto-mount deprecation
     _metadata: api_pb2.ImageMetadata | None = None  # set on hydration, private for now
     _is_empty: bool
+    _build_steps: list[api_pb2.ImageBuildStep] | None = None
+    # A failed image ID is only queryable through the client that performed the build.
+    _failed_build_attempt: _FailedBuildAttempt | None = None
 
     def _initialize_from_empty(self):
         self.inside_exceptions = []
@@ -524,6 +535,9 @@ class _Image(_Object, type_prefix="im"):
         if metadata:
             assert isinstance(metadata, api_pb2.ImageMetadata)
             self._metadata = metadata
+        # Successful hydration supersedes diagnostic state retained from a failed build.
+        self._failed_build_attempt = None
+        self._build_steps = None
 
     def _add_mount_layer_or_copy(self, mount: _Mount, copy: bool = False):
         if copy:
@@ -752,12 +766,12 @@ class _Image(_Object, type_prefix="im"):
 
             if result.status == api_pb2.GenericResult.GENERIC_STATUS_FAILURE:
                 if result.exception:
-                    raise RemoteError(f"Image build for {image_id} failed with the exception:\n{result.exception}")
+                    raise ImageBuildError(
+                        f"Image build for {image_id} failed with the exception:\n{result.exception}", image_id
+                    )
                 else:
-                    msg = f"Image build for {image_id} failed. See build logs for more details."
-                    if not OutputManager.get().is_enabled:
-                        msg += " (Hint: Use `modal.enable_output()` to see logs from the process building the Image.)"
-                    raise RemoteError(msg)
+                    msg = f"Image build for {image_id} failed.\nView the build logs:\n  modal image logs {image_id}"
+                    raise ImageBuildError(msg, image_id)
             elif result.status == api_pb2.GenericResult.GENERIC_STATUS_TERMINATED:
                 msg = f"Image build for {image_id} terminated due to external shut-down. Please try again."
                 if result.exception:
@@ -765,15 +779,16 @@ class _Image(_Object, type_prefix="im"):
                         f"Image build for {image_id} terminated due to external shut-down with the exception:\n"
                         f"{result.exception}"
                     )
-                raise RemoteError(msg)
+                raise ImageBuildError(msg, image_id)
             elif result.status == api_pb2.GenericResult.GENERIC_STATUS_TIMEOUT:
-                raise RemoteError(
-                    f"Image build for {image_id} timed out. Please try again with a larger `timeout` parameter."
+                raise ImageBuildError(
+                    f"Image build for {image_id} timed out. Please try again with a larger `timeout` parameter.",
+                    image_id,
                 )
             elif result.status == api_pb2.GenericResult.GENERIC_STATUS_SUCCESS:
                 pass
             else:
-                raise RemoteError("Unknown status %s!" % result.status)
+                raise ImageBuildError("Unknown status %s!" % result.status, image_id)
 
             self._hydrate(image_id, load_context.client, metadata)
             local_mounts: set[_Mount] = set()
@@ -1064,8 +1079,18 @@ class _Image(_Object, type_prefix="im"):
 
         resolver = Resolver()
         async with TaskContext() as tc:
+            self._build_steps = None
+            self._failed_build_attempt = None
             load_context = LoadContext(task_context=tc).merged_with(app._root_load_context)
-            await resolver.load(self, load_context)
+            try:
+                await resolver.load(self, load_context)
+            except ImageBuildError as e:
+                self._failed_build_attempt = _FailedBuildAttempt(
+                    image_id=e.image_id,
+                    client=load_context.client,
+                )
+
+                raise
         return self
 
     @_requires_image_instance
@@ -3028,3 +3053,38 @@ class _Image(_Object, type_prefix="im"):
                 "Images cannot currently be hydrated on demand; you can build an Image by running an App that uses it."
             )
         return self
+
+    async def _resolve_image_id_client_for_logs(self) -> tuple[str, _Client]:
+        if self._failed_build_attempt is not None:
+            return self._failed_build_attempt.image_id, self._failed_build_attempt.client
+        if self._object_id is None:
+            raise InvalidError("Cannot fetch logs for an image that has not been built yet.")
+        if self._is_hydrated:
+            return self._object_id, self.client
+        # Use self._load_context_overrides to handle case of explicitly passed
+        # client in from_id
+        client = (await self._load_context_overrides.apply_defaults()).client
+        return self._object_id, client
+
+    async def _get_log_query_data(self) -> _ImageLogQueryData:
+        image_id, client = await self._resolve_image_id_client_for_logs()
+
+        if self._build_steps is None:
+            request = api_pb2.ImageBuildChainGetRequest(image_id=image_id)
+            response = await client.stub.ImageBuildChainGet(request)
+            self._build_steps = list(response.build_steps)
+        return _ImageLogQueryData(client, self._build_steps or [], image_id)
+
+    @property
+    def logs(self) -> _ImageLogsManager:
+        """Access logs for an `Image`.
+
+        Use [`fetch()`](#logsfetch)
+        to read logs for individual build layers and [`tail()`](#logstail)
+        to read the most recent logs.
+
+        See also:
+            - [`modal app logs`](https://modal.com/docs/cli/latest/app#modal-app-logs):
+              CLI access to logs for an App.
+        """
+        return _ImageLogsManager(self)

{modal-1.5.4.dev13 → modal-1.5.4.dev15}/modal/_logs.py

@@ -256,13 +256,16 @@ async def _refine_dense_ranges(
                 )
                 sub_resp = await client.stub.AppCountLogs(sub_req)
                 sub_ranges = _buckets_to_ranges(list(sub_resp.buckets), smaller_secs)
-                # Clamp the last sub-range to the parent's end. When bucket_secs
-                # doesn't evenly divide the parent duration, the last bucket
-                # boundary overshoots (e.g. parent (0,30) with 20s buckets
-                # produces (20,40)), causing overlaps with sibling ranges.
+                # Clamp the edge sub-ranges to the parent boundaries. Bucket
+                # alignment can make the first bucket begin before the parent
+                # (e.g. parent (6,12) with 4s buckets produces (4,8)) or make
+                # the last bucket end after it (e.g. parent (0,30) with 20s
+                # buckets produces (20,40)), causing overlaps with siblings.
                 if sub_ranges:
-                    s, _, c = sub_ranges[-1]
-                    sub_ranges[-1] = (s, min(s + smaller_secs, end), c)
+                    first_start, first_end, first_count = sub_ranges[0]
+                    sub_ranges[0] = (max(first_start, start), first_end, first_count)
+                    last_start, last_end, last_count = sub_ranges[-1]
+                    sub_ranges[-1] = (last_start, min(last_end, end), last_count)
                 return sub_ranges
 
         refine_set = {i for i, _ in to_refine}
@@ -410,7 +413,6 @@ async def fetch_logs(
 
     if until - since > _MAX_FETCH_RANGE:
         raise LogsFetchError(f"Time range cannot exceed {_MAX_FETCH_RANGE.days} days.")
-
     # Phase 1: Count logs per bucket
     bucket_secs = _pick_bucket_secs(since, until)
     count_req = api_pb2.AppCountLogsRequest(

{modal-1.5.4.dev13 → modal-1.5.4.dev15}/modal/_logs_manager.py

@@ -11,8 +11,8 @@ from datetime import datetime, timezone
 
 from grpclib.exceptions import StreamTerminatedError
 
-from modal._logs import fetch_logs, tail_logs
-from modal._supports_logs import _LogQueryData, _SupportsLogs
+from modal._logs import LogsFilters, fetch_logs, tail_logs
+from modal._supports_logs import _LogQueryData, _SupportsImageLogs, _SupportsLogs
 from modal._utils.async_utils import synchronize_api
 from modal._utils.grpc_utils import RETRYABLE_GRPC_STATUS_CODES as _RETRYABLE_STREAM_STATUSES
 from modal._utils.time_utils import locale_tz
@@ -38,6 +38,70 @@ class _StreamStopReason(enum.Enum):
     STOP_STREAM = "stop_stream"
 
 
+def _normalize_utc_datetime(value: datetime, name: str) -> datetime:
+    if not isinstance(value, datetime):
+        raise TypeError(f"{name} must be a datetime")
+    if value.tzinfo is None:
+        return value.replace(tzinfo=locale_tz()).astimezone(timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+def _entry_source(file_descriptor: api_pb2.FileDescriptor.ValueType) -> LogSource:
+    match file_descriptor:
+        case api_pb2.FILE_DESCRIPTOR_STDOUT:
+            return "stdout"
+        case api_pb2.FILE_DESCRIPTOR_STDERR:
+            return "stderr"
+        case _:
+            return "system"
+
+
+def _entry_timestamp(item: api_pb2.TaskLogs) -> datetime:
+    if item.timestamp_ns:
+        return datetime.fromtimestamp(item.timestamp_ns / 1_000_000_000, timezone.utc)
+    return datetime.fromtimestamp(item.timestamp, timezone.utc)
+
+
+def _resolve_source(source: LogSource | None) -> api_pb2.FileDescriptor.ValueType:
+    match source:
+        case "stderr":
+            return api_pb2.FILE_DESCRIPTOR_STDERR
+        case "stdout":
+            return api_pb2.FILE_DESCRIPTOR_STDOUT
+        case "system":
+            return api_pb2.FILE_DESCRIPTOR_INFO
+        case None:
+            return api_pb2.FILE_DESCRIPTOR_UNSPECIFIED
+        case _:
+            raise ValueError("source must be one of 'stdout', 'stderr', 'system', or None")
+
+
+def _entry_context_ids(object_id: str, item: api_pb2.TaskLogs, batch: api_pb2.TaskLogsBatch) -> list[str]:
+    match object_id[:2]:
+        case "fu":
+            context_ids = [
+                item.function_call_id,
+                item.input_id or batch.input_id,
+                item.container_id or batch.task_id,
+            ]
+        case "fc":
+            context_ids = [item.input_id or batch.input_id, item.container_id or batch.task_id]
+        case _:
+            context_ids = []
+    # filter for empty strings, can happen for Server which have function_ids but no input/container
+    return [c for c in context_ids if c]
+
+
+def _entry_from_item(object_id: str, item: api_pb2.TaskLogs, batch: api_pb2.TaskLogsBatch) -> LogEntry:
+    return LogEntry(
+        message=item.data,
+        timestamp=_entry_timestamp(item),
+        source=_entry_source(item.file_descriptor),
+        object_id=object_id,
+        context_ids=_entry_context_ids(object_id, item, batch),
+    )
+
+
 class _LogsManager:
     """mdmd:namespace"""
 
@@ -52,68 +116,6 @@ class _LogsManager:
             self._query_params = await self._source._get_log_query_data()
         return self._query_params
 
-    @staticmethod
-    def _resolve_source(source: LogSource | None) -> api_pb2.FileDescriptor.ValueType:
-        match source:
-            case "stderr":
-                return api_pb2.FILE_DESCRIPTOR_STDERR
-            case "stdout":
-                return api_pb2.FILE_DESCRIPTOR_STDOUT
-            case "system":
-                return api_pb2.FILE_DESCRIPTOR_INFO
-            case None:
-                return api_pb2.FILE_DESCRIPTOR_UNSPECIFIED
-            case _:
-                raise ValueError("source must be one of 'stdout', 'stderr', 'system', or None")
-
-    @staticmethod
-    def _normalize_utc_datetime(value: datetime, name: str) -> datetime:
-        if not isinstance(value, datetime):
-            raise TypeError(f"{name} must be a datetime")
-        if value.tzinfo is None:
-            return value.replace(tzinfo=locale_tz()).astimezone(timezone.utc)
-        return value.astimezone(timezone.utc)
-
-    @staticmethod
-    def _entry_source(file_descriptor: api_pb2.FileDescriptor.ValueType) -> LogSource:
-        match file_descriptor:
-            case api_pb2.FILE_DESCRIPTOR_STDOUT:
-                return "stdout"
-            case api_pb2.FILE_DESCRIPTOR_STDERR:
-                return "stderr"
-            case _:
-                return "system"
-
-    @staticmethod
-    def _entry_timestamp(item: api_pb2.TaskLogs) -> datetime:
-        if item.timestamp_ns:
-            return datetime.fromtimestamp(item.timestamp_ns / 1_000_000_000, timezone.utc)
-        return datetime.fromtimestamp(item.timestamp, timezone.utc)
-
-    def _entry_context_ids(self, item: api_pb2.TaskLogs, batch: api_pb2.TaskLogsBatch) -> list[str]:
-        match self._source.object_id[:2]:
-            case "fu":
-                context_ids = [
-                    item.function_call_id,
-                    item.input_id or batch.input_id,
-                    item.container_id or batch.task_id,
-                ]
-            case "fc":
-                context_ids = [item.input_id or batch.input_id, item.container_id or batch.task_id]
-            case _:
-                context_ids = []
-        # filter for empty strings, can happen for Server which have function_ids but no input/container
-        return [c for c in context_ids if c]
-
-    def _entry_from_item(self, item: api_pb2.TaskLogs, batch: api_pb2.TaskLogsBatch) -> LogEntry:
-        return LogEntry(
-            message=item.data,
-            timestamp=self._entry_timestamp(item),
-            source=self._entry_source(item.file_descriptor),
-            object_id=self._source.object_id,
-            context_ids=self._entry_context_ids(item, batch),
-        )
-
     async def _watch_stream_stop(self, deadline: _Deadline) -> _StreamStopReason | None:
         while True:
             if deadline.value is not None and time.monotonic() >= deadline.value:
@@ -135,13 +137,13 @@ class _LogsManager:
         search_text: str = "",
     ) -> AsyncGenerator[LogEntry, None]:
         """Fetch all associated logs corresponding to the date range and filters."""
-        since = self._normalize_utc_datetime(since, "since")
-        until = self._normalize_utc_datetime(until or datetime.now(timezone.utc), "until")
+        since = _normalize_utc_datetime(since, "since")
+        until = _normalize_utc_datetime(until or datetime.now(timezone.utc), "until")
         target = await self._params()
-        filters = dataclasses.replace(target.filters, source=self._resolve_source(source), search_text=search_text)
+        filters = dataclasses.replace(target.filters, source=_resolve_source(source), search_text=search_text)
         async for batch in fetch_logs(target.client, target.app_id, since=since, until=until, filters=filters):
             for item in batch.items:
-                yield self._entry_from_item(item, batch)
+                yield _entry_from_item(self._source.object_id, item, batch)
 
     async def tail(
         self,
@@ -151,7 +153,7 @@ class _LogsManager:
     ) -> AsyncGenerator[LogEntry, None]:
         """Fetch the most recent logs."""
         params = await self._params()
-        filters = dataclasses.replace(params.filters, source=self._resolve_source(source))
+        filters = dataclasses.replace(params.filters, source=_resolve_source(source))
         async for batch in tail_logs(
             params.client,
             params.app_id,
@@ -159,7 +161,7 @@ class _LogsManager:
             filters=filters,
         ):
             for item in batch.items:
-                yield self._entry_from_item(item, batch)
+                yield _entry_from_item(self._source.object_id, item, batch)
 
     def _create_log_stream(
         self, params: _LogQueryData, last_entry_id: str, timeout: float
@@ -180,7 +182,7 @@ class _LogsManager:
     def _stream_entries(self, batch: api_pb2.TaskLogsBatch):
         for item in batch.items:
             if item.data:
-                yield self._entry_from_item(item, batch)
+                yield _entry_from_item(self._source.object_id, item, batch)
 
     @staticmethod
     def _advance_batch(batch: api_pb2.TaskLogsBatch, last_entry_id: str) -> tuple[str, bool]:
@@ -668,3 +670,122 @@ class _FunctionCallLogsManager:
 
 
 FunctionCallLogsManager = synchronize_api(_FunctionCallLogsManager, target_module=__name__)
+
+
+class _ImageLogsManager:
+    """mdmd:namespace"""
+
+    _MAX_CONCURRENT_FETCHES = 10
+
+    def __init__(self, source: _SupportsImageLogs):
+        """mdmd:hidden"""
+        self._source = source
+
+    async def fetch(
+        self,
+        layers: int | None = 1,
+    ) -> AsyncGenerator[LogEntry, None]:
+        """Fetch logs for the most recent Image build steps.
+
+        Args:
+            layers: The number of build layers to fetch, counting backward
+                from the final Image. If None, logs are fetched for all build steps.
+        """
+        params = await self._source._get_log_query_data()
+        if layers is None:
+            layer_count = len(params.build_steps)
+        elif layers < 1:
+            raise ValueError("layers must be at least 1")
+        else:
+            layer_count = min(layers, len(params.build_steps))
+
+        selected_layers = params.build_steps[-layer_count:]
+
+        semaphore = asyncio.Semaphore(self._MAX_CONCURRENT_FETCHES)
+        queues = [asyncio.Queue(maxsize=100) for _ in selected_layers]
+        DONE = object()
+
+        async def _bounded_fetch(step: api_pb2.ImageBuildStep, queue: asyncio.Queue[LogEntry | object]) -> None:
+            cancelled = False
+            # Awkward but intentional double try/except to track whether the task was cancelled.
+            # In Python 3.11+ we can use Task.cancelling().
+            try:
+                try:
+                    async with semaphore:
+                        async for batch in fetch_logs(
+                            params.client,
+                            step.builder_app_id,
+                            # Protobuf timestamps represent UTC time.
+                            since=step.started_at.ToDatetime(tzinfo=timezone.utc),
+                            until=step.finished_at.ToDatetime(tzinfo=timezone.utc),
+                            filters=LogsFilters(
+                                task_id=step.builder_task_id,
+                            ),
+                        ):
+                            for item in batch.items:
+                                await queue.put(_entry_from_item(params.object_id, item, batch))
+                except Exception as e:
+                    await queue.put(e)
+            except asyncio.CancelledError:
+                cancelled = True
+                raise
+            finally:
+                if not cancelled:
+                    await queue.put(DONE)
+
+        tasks = [asyncio.create_task(_bounded_fetch(s, q)) for s, q in zip(selected_layers, queues)]
+
+        try:
+            for q in queues:
+                while (item := await q.get()) is not DONE:
+                    if isinstance(item, Exception):
+                        raise item
+                    yield item
+        finally:
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def tail(
+        self,
+        entries: int = 100,
+    ) -> AsyncGenerator[LogEntry, None]:
+        """Fetch the most recent Image logs.
+
+        Args:
+            entries: The number of log entries to return.
+        """
+        params = await self._source._get_log_query_data()
+        remaining_entries = entries
+        entries_by_step: list[list[LogEntry]] = []
+
+        for step in reversed(params.build_steps):
+            if remaining_entries <= 0:
+                break
+
+            step_entries: list[LogEntry] = []
+            async for batch in tail_logs(
+                params.client,
+                step.builder_app_id,
+                remaining_entries,
+                since=step.started_at.ToDatetime(tzinfo=timezone.utc),
+                until=step.finished_at.ToDatetime(tzinfo=timezone.utc),
+                filters=LogsFilters(task_id=step.builder_task_id),
+            ):
+                for item in batch.items:
+                    if len(step_entries) >= remaining_entries:
+                        break
+                    step_entries.append(_entry_from_item(params.object_id, item, batch))
+
+            if step_entries:
+                entries_by_step.append(step_entries)
+                remaining_entries -= len(step_entries)
+
+        # Steps are queried newest-to-oldest so we can stop as soon as we have
+        # enough entries, but results are exposed in chronological build order.
+        for step_entries in reversed(entries_by_step):
+            for entry in step_entries:
+                yield entry
+
+
+ImageLogsManager = synchronize_api(_ImageLogsManager, target_module=__name__)

{modal-1.5.4.dev13 → modal-1.5.4.dev15}/modal/_logs_manager.pyi

@@ -32,6 +32,17 @@ class _StreamStopReason(enum.Enum):
     IDLE_TIMEOUT = "idle_timeout"
     STOP_STREAM = "stop_stream"
 
+def _normalize_utc_datetime(value: datetime.datetime, name: str) -> datetime.datetime: ...
+def _entry_source(file_descriptor: int) -> typing.Literal["stdout", "stderr", "system"]: ...
+def _entry_timestamp(item: modal_proto.api_pb2.TaskLogs) -> datetime.datetime: ...
+def _resolve_source(source: typing.Optional[typing.Literal["stdout", "stderr", "system"]]) -> int: ...
+def _entry_context_ids(
+    object_id: str, item: modal_proto.api_pb2.TaskLogs, batch: modal_proto.api_pb2.TaskLogsBatch
+) -> list[str]: ...
+def _entry_from_item(
+    object_id: str, item: modal_proto.api_pb2.TaskLogs, batch: modal_proto.api_pb2.TaskLogsBatch
+) -> modal.types.LogEntry: ...
+
 class _LogsManager:
     """mdmd:namespace"""
     def __init__(
@@ -43,20 +54,6 @@ class _LogsManager:
         ...
 
     async def _params(self) -> modal._supports_logs._LogQueryData: ...
-    @staticmethod
-    def _resolve_source(source: typing.Optional[typing.Literal["stdout", "stderr", "system"]]) -> int: ...
-    @staticmethod
-    def _normalize_utc_datetime(value: datetime.datetime, name: str) -> datetime.datetime: ...
-    @staticmethod
-    def _entry_source(file_descriptor: int) -> typing.Literal["stdout", "stderr", "system"]: ...
-    @staticmethod
-    def _entry_timestamp(item: modal_proto.api_pb2.TaskLogs) -> datetime.datetime: ...
-    def _entry_context_ids(
-        self, item: modal_proto.api_pb2.TaskLogs, batch: modal_proto.api_pb2.TaskLogsBatch
-    ) -> list[str]: ...
-    def _entry_from_item(
-        self, item: modal_proto.api_pb2.TaskLogs, batch: modal_proto.api_pb2.TaskLogsBatch
-    ) -> modal.types.LogEntry: ...
     async def _watch_stream_stop(self, deadline: _Deadline) -> typing.Optional[_StreamStopReason]: ...
     def fetch(
         self,
@@ -927,3 +924,74 @@ class FunctionCallLogsManager:
             ...
 
     fetch: __fetch_spec
+
+class _ImageLogsManager:
+    """mdmd:namespace"""
+    def __init__(self, source: modal._supports_logs._SupportsImageLogs):
+        """mdmd:hidden"""
+        ...
+
+    def fetch(self, layers: typing.Optional[int] = 1) -> collections.abc.AsyncGenerator[modal.types.LogEntry, None]:
+        """Fetch logs for the most recent Image build steps.
+
+        Args:
+            layers: The number of build layers to fetch, counting backward
+                from the final Image. If None, logs are fetched for all build steps.
+        """
+        ...
+
+    def tail(self, entries: int = 100) -> collections.abc.AsyncGenerator[modal.types.LogEntry, None]:
+        """Fetch the most recent Image logs.
+
+        Args:
+            entries: The number of log entries to return.
+        """
+        ...
+
+class ImageLogsManager:
+    """mdmd:namespace"""
+    def __init__(self, source: modal._supports_logs._SupportsImageLogs):
+        """mdmd:hidden"""
+        ...
+
+    class __fetch_spec(typing_extensions.Protocol):
+        def __call__(self, /, layers: typing.Optional[int] = 1) -> typing.Generator[modal.types.LogEntry, None, None]:
+            """Fetch logs for the most recent Image build steps.
+
+            Args:
+                layers: The number of build layers to fetch, counting backward
+                    from the final Image. If None, logs are fetched for all build steps.
+            """
+            ...
+
+        def aio(
+            self, /, layers: typing.Optional[int] = 1
+        ) -> collections.abc.AsyncGenerator[modal.types.LogEntry, None]:
+            """Fetch logs for the most recent Image build steps.
+
+            Args:
+                layers: The number of build layers to fetch, counting backward
+                    from the final Image. If None, logs are fetched for all build steps.
+            """
+            ...
+
+    fetch: __fetch_spec
+
+    class __tail_spec(typing_extensions.Protocol):
+        def __call__(self, /, entries: int = 100) -> typing.Generator[modal.types.LogEntry, None, None]:
+            """Fetch the most recent Image logs.
+
+            Args:
+                entries: The number of log entries to return.
+            """
+            ...
+
+        def aio(self, /, entries: int = 100) -> collections.abc.AsyncGenerator[modal.types.LogEntry, None]:
+            """Fetch the most recent Image logs.
+
+            Args:
+                entries: The number of log entries to return.
+            """
+            ...
+
+    tail: __tail_spec

{modal-1.5.4.dev13 → modal-1.5.4.dev15}/modal/_supports_logs.py

@@ -5,6 +5,7 @@ from typing import Protocol
 
 from modal._logs import LogsFilters
 from modal.client import _Client
+from modal_proto import api_pb2
 
 
 @dataclasses.dataclass(frozen=True)
@@ -30,3 +31,22 @@ class _SupportsLogs(Protocol):
 
     @property
     def object_id(self) -> str: ...
+
+
+@dataclasses.dataclass(frozen=True)
+class _ImageLogQueryData:
+    """Resolved data needed to query logs for a Modal object.
+
+    Log managers lazily ask their source object for this data before the first
+    query.
+    """
+
+    client: _Client
+    build_steps: list[api_pb2.ImageBuildStep]
+    object_id: str
+
+
+class _SupportsImageLogs(Protocol):
+    """Protocol for objects that support log streaming and fetching and have build steps."""
+
+    async def _get_log_query_data(self) -> _ImageLogQueryData: ...