modal 1.5.6.dev23__tar.gz → 1.5.6.dev25__tar.gz

{modal-1.5.6.dev23 → modal-1.5.6.dev25}/PKG-INFO

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

{modal-1.5.6.dev23 → modal-1.5.6.dev25}/modal/__init__.py

@@ -9,7 +9,7 @@ if sys.version_info[:2] >= (3, 15):
 from modal_version import __version__
 
 try:
-    from . import billing, types
+    from . import billing, experimental, types
     from ._runtime.execution_context import current_function_call_id, current_input_id, interact, is_local
     from ._tunnel import Tunnel, forward
     from .app import App
@@ -96,6 +96,7 @@ __all__ = [
     "enable_output",
     "enter",
     "exit",
+    "experimental",
     "fastapi_endpoint",
     "forward",
     "is_local",

{modal-1.5.6.dev23 → modal-1.5.6.dev25}/modal/_functions.py

@@ -10,7 +10,7 @@ from collections.abc import AsyncGenerator, AsyncIterator, Callable, Collection,
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from pathlib import PurePosixPath
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 import typing_extensions
 from google.protobuf.message import Message
@@ -945,7 +945,7 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
             self._hydrate(response.function_id, load_context.client, response.handle_metadata)
 
         async def _load(self: _Function, resolver: Resolver, load_context: LoadContext, existing_object_id: str | None):
-            with FunctionCreationStatus(tag) as function_creation_status:
+            with FunctionCreationStatus("Server" if is_server else "Function", tag) as function_creation_status:
                 timeout_secs = timeout
 
                 if app and app._is_interactive_ and not is_builder_function:
@@ -1388,6 +1388,72 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
             _load_remote, rep, skip_reload=True, hydrate_lazily=True, load_context_overrides=load_context_overrides
         )
 
+    @classmethod
+    def _from_id(
+        cls,
+        function_id: str,
+        *,
+        load_context_overrides: LoadContext,
+        called_from: Literal["Function", "Server"] = "Function",
+    ):
+        # internal function lookup implementation that allows lookup of class "service functions"
+        # in addition to non-class functions
+        async def _load_remote(
+            self: _Function, resolver: Resolver, load_context: LoadContext, existing_object_id: str | None
+        ):
+            request = api_pb2.FunctionGetByIdRequest(function_id=function_id)
+            try:
+                response = await load_context.client.stub.FunctionGetById(request)
+            except NotFoundError as exc:
+                # refine the error message
+                msg = f"Lookup failed for {called_from} '{function_id}': {exc}."
+                raise NotFoundError(msg) from None
+            if called_from == "Function" and (response.function.is_server or response.function.is_class):
+                if response.function.is_server:
+                    raise InvalidError(f"{function_id} is a Server. Use \n ``modal.Server.from_id('{function_id}')``")
+                raise InvalidError(f"{function_id} is a Cls and cannot be loaded with Function.from_id().")
+            if called_from == "Server" and not response.function.is_server:
+                if response.function.is_class:
+                    raise InvalidError(f"{function_id} is a Cls and cannot be loaded with Server.from_id().")
+                raise InvalidError(f"{function_id} is a Function. Use \n ``modal.Function.from_id('{function_id}')``")
+            self._hydrate(function_id, load_context.client, response.handle_metadata)
+            self._function_info = FunctionInfo._from_function_proto(response.function)
+
+        rep = f"modal.Function.from_id('{function_id}')"
+        return cls._from_loader(
+            _load_remote, rep, skip_reload=True, hydrate_lazily=True, load_context_overrides=load_context_overrides
+        )
+
+    @classmethod
+    def from_id(
+        cls: type["_Function"],
+        function_id: str,
+        *,
+        client: _Client | None = None,
+    ):
+        """Reference a Function from a deployed or running App by its ID.
+
+        This is a lazy method that defers hydrating the local
+        object with metadata from Modal servers until the first
+        time it is actually used.
+
+        Args:
+            function_id: ID of the function.
+            client: Modal client to use; defaults to `Client.from_env()` when omitted.
+
+        Returns:
+            A lazy `Function` handle.
+
+        Examples:
+            ```python
+            f = modal.Function.from_id("fu-123")
+            ```
+        """
+        return cls._from_id(
+            function_id,
+            load_context_overrides=LoadContext(client=client),
+        )
+
     @classmethod
     def from_name(
         cls: type["_Function"],

{modal-1.5.6.dev23 → modal-1.5.6.dev25}/modal/_output/manager.py

@@ -58,6 +58,11 @@ class StatusRow(ABC):
         """Append a warning message associated with this row."""
         ...
 
+    @abstractmethod
+    def details(self, message: str) -> None:
+        """Append additional details to the row."""
+        ...
+
     @abstractmethod
     def finish(self, message: str) -> None:
         """Mark the row as finished with the given message."""
@@ -73,6 +78,9 @@ class DisabledStatusRow(StatusRow):
     def warn(self, warning: "api_pb2.Warning") -> None:
         pass
 
+    def details(self, message: str) -> None:
+        pass
+
     def finish(self, message: str) -> None:
         pass
 

{modal-1.5.6.dev23 → modal-1.5.6.dev25}/modal/_output/rich.py

@@ -194,6 +194,10 @@ class RichStatusRow(StatusRow):
         if self._spinner is not None:
             self._spinner.update(text=message)
 
+    def details(self, message: str) -> None:
+        if self._step_node is not None:
+            self._step_node.add(f"{message}")
+
     def warn(self, warning: api_pb2.Warning) -> None:
         if self._step_node is not None:
             self._step_node.add(f"[yellow]:warning:[/yellow] {warning.message}")
@@ -201,7 +205,7 @@ class RichStatusRow(StatusRow):
     def finish(self, message: str) -> None:
         if self._step_node is not None and self._spinner is not None:
             self._spinner.update(text=message)
-            self._step_node.label = f"🔨 {message}"
+            self._step_node.label = f"[green]✓[/green] {message}"
 
 
 _LOG_FLUSH_THRESHOLD = 32768  # 32KB — flush batched log output roughly every ~400 lines

modal-1.5.6.dev25/modal/_output/status.py

@@ -0,0 +1,92 @@
+# Copyright Modal Labs 2022
+"""Function creation status tracking for Modal CLI.
+
+This module contains the FunctionCreationStatus context manager used to
+track and display function creation progress.
+"""
+
+from __future__ import annotations
+
+from modal_proto import api_pb2
+
+from .manager import OutputManager
+
+
+def _get_annotation_for_web_url(url_info: api_pb2.WebUrlInfo) -> str:
+    if url_info.truncated:
+        suffix = " [grey70](label truncated)[/grey70]"
+    elif url_info.label_stolen:
+        suffix = " [grey70](label stolen)[/grey70]"
+    else:
+        suffix = ""
+    return suffix
+
+
+class FunctionCreationStatus:
+    """Context manager for tracking and displaying function creation progress."""
+
+    type: str
+    name: str
+    response: api_pb2.FunctionCreateResponse | None = None
+
+    def __init__(self, type: str, name: str):
+        self.type = type
+        self.name = name
+        self._output_mgr = OutputManager.get()
+
+    def __enter__(self):
+        self.status_row = self._output_mgr.add_status_row()
+        self.status_row.message(f"Creating {self.type} {self.name}...")
+        return self
+
+    def set_response(self, resp: api_pb2.FunctionCreateResponse):
+        self.response = resp
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type:
+            raise exc_val
+
+        if not self.response:
+            self.status_row.finish(f"Unknown error when creating {self.type} {self.name}")
+            return
+
+        for warning in self.response.server_warnings:
+            self.status_row.warn(warning)
+
+        if web_url := self.response.handle_metadata.web_url:
+            url_info = self.response.function.web_url_info
+            authenticated = self.response.function.webhook_config.requires_proxy_auth
+            auth_suffix = " 🔑" if authenticated else " [yellow](unauthenticated)[/yellow]"
+            suffix = _get_annotation_for_web_url(url_info)
+
+            self.status_row.finish(f"Created {self.type} [green]{self.name}[/green]")
+            self.status_row.details(f"[dim underline]{web_url}[/dim underline]{auth_suffix}{suffix}")
+            for custom_domain in self.response.function.custom_domain_info:
+                self.status_row.details(f"Custom domain: [dim underline]{custom_domain.url}[/dim underline]")
+
+        elif self.response.function.flash_service_urls:
+            # Despite the gRPC API types, Servers only have one URL
+            authenticated = self.response.function.is_server and not self.response.function.http_config.unauthenticated
+            auth_suffix = " 🔑" if authenticated else " [yellow](unauthenticated)[/yellow]"
+            self.status_row.finish(f"Created {self.type} [green]{self.name}[/green]")
+            url = self.response.function.flash_service_urls[0]
+            self.status_row.details(f"[dim underline]{url}[/dim underline]{auth_suffix}")
+
+        else:
+            self.status_row.finish(f"Created {self.type} [green]{self.name}[/green].")
+            if self.response.function.method_definitions_set:
+                for method_definition in self.response.function.method_definitions.values():
+                    if method_definition.web_url:
+                        url_info = method_definition.web_url_info
+                        suffix = _get_annotation_for_web_url(url_info)
+                        authenticated = method_definition.webhook_config.requires_proxy_auth
+                        auth_suffix = " 🔑" if authenticated else " [yellow](unauthenticated)[/yellow]"
+                        self.status_row.details(
+                            f"{method_definition.function_name} -> "
+                            f"[dim underline]{method_definition.web_url}[/dim underline]{auth_suffix}{suffix}"
+                        )
+                        for custom_domain in method_definition.custom_domain_info:
+                            indent = len(method_definition.function_name) * " "
+                            self.status_row.details(
+                                f"{indent} -> [dim underline]{custom_domain.url}[/dim underline]{auth_suffix}"
+                            )

{modal-1.5.6.dev23 → modal-1.5.6.dev25}/modal/_server.py

@@ -273,6 +273,38 @@ class _Server:
         )
         return server
 
+    @classmethod
+    def from_id(
+        cls: type["_Server"],
+        server_id: str,
+        *,
+        client: _Client | None = None,
+    ):
+        """Reference a Server from a deployed or running App by its ID.
+
+        This is a lazy method that defers hydrating the local
+        object with metadata from Modal servers until the first
+        time it is actually used.
+
+        Args:
+            server_id: The ID of the server.
+            client: Modal client instance for this session.
+
+        Examples:
+            ```python notest
+            server = modal.Server.from_id("fu-456")
+            ```
+        """
+        load_context_overrides = LoadContext(client=client)
+
+        server = _Server()
+        server._service_function = _Function._from_id(
+            server_id,
+            load_context_overrides=load_context_overrides,
+            called_from="Server",
+        )
+        return server
+
     def _is_local(self) -> bool:
         """Returns True if this Server has local source code available."""
         return self._user_cls is not None

{modal-1.5.6.dev23 → modal-1.5.6.dev25}/modal/_traceback.py

@@ -123,13 +123,25 @@ def print_exception(exc: type[BaseException] | None, value: BaseException | None
         print(*notes, sep="\n", file=sys.stderr)  # noqa: T201
 
 
-def print_server_warnings(server_warnings: Iterable[api_pb2.Warning]):
+_server_warning_registry: dict[Any, Any] = {}
+SERVER_WARNING_REGISTRY_LIMIT = 2048
+
+
+def print_server_warning(message: str):
     """Issue a warning originating from the server with empty metadata about local origin.
 
     When using the Modal CLI, these warnings should get caught and coerced into Rich panels.
     """
+    if len(_server_warning_registry) > SERVER_WARNING_REGISTRY_LIMIT:
+        # Start over instead of going quiet: overflow costs a repeat, never a hidden warning.
+        _server_warning_registry.clear()
+    warnings.warn_explicit(message, ServerWarning, "<modal-server>", 0, registry=_server_warning_registry)
+
+
+def print_server_warnings(server_warnings: Iterable[api_pb2.Warning]):
+    """Issue warnings that the server attached to a response message."""
     for warning in server_warnings:
-        warnings.warn_explicit(warning.message, ServerWarning, "<modal-server>", 0)
+        print_server_warning(warning.message)
 
 
 # for some reason, the traceback cleanup here can't be moved into a context manager :(

{modal-1.5.6.dev23 → modal-1.5.6.dev25}/modal/_utils/grpc_utils.py

@@ -24,12 +24,13 @@ from grpclib.config import Configuration
 from grpclib.encoding.base import CodecBase, StatusDetailsCodecBase
 from grpclib.exceptions import StreamTerminatedError
 from grpclib.protocol import H2Protocol
+from h2.exceptions import ProtocolError as H2ProtocolError
 
 from modal.exception import ClientClosed, ConnectionError, NotFoundError
 from modal_proto import api_pb2
 from modal_version import __version__
 
-from .._traceback import suppress_tb_frame
+from .._traceback import print_server_warning, suppress_tb_frame
 from ..config import config
 from .async_utils import TaskContext, retry
 from .logger import logger
@@ -130,6 +131,24 @@ class ModalChannel(grpclib.client.Channel):
         return await super().__connect__()
 
     async def _create_connection(self) -> H2Protocol:
+        target = self._path if self.__use_unix_socket else f"{self.__target_host}:{self.__target_port}"
+        tls = self.__ssl_context is not None
+        started_at = time.monotonic()
+        # Logged before awaiting: a reconnect is invisible until it resolves, which
+        # can be long after the RPC waiting on it appears to hang.
+        logger.debug(f"Starting connection attempt to {target} (TLS={tls})")
+        try:
+            protocol = await self._open_connection()
+        except (asyncio.CancelledError, Exception) as exc:
+            outcome = "cancelled" if isinstance(exc, asyncio.CancelledError) else "failed"
+            elapsed = time.monotonic() - started_at
+            logger.debug(f"Connection attempt to {target} {outcome} after {elapsed:.3f}s: {exc!r}")
+            raise
+        elapsed = time.monotonic() - started_at
+        logger.debug(f"Connection to {target} established after {elapsed:.3f}s")
+        return protocol
+
+    async def _open_connection(self) -> H2Protocol:
         if self.__use_unix_socket:
             return await super()._create_connection()
 
@@ -308,6 +327,20 @@ def create_channel_config(*, sustained_keepalive: bool = False) -> grpclib.confi
     )
 
 
+# Header the server uses to attach a non-fatal message to any response, one entry per
+# percent-encoded warning. It rides in the trailing metadata, which grpclib also
+# surfaces for trailers-only responses, i.e. failed requests.
+SERVER_WARNING_HEADER = "x-modal-warning"
+
+
+def _issue_server_warnings(metadata: Any) -> None:
+    """Issue the warnings in a response's metadata, which `print_server_warning` deduplicates."""
+    for key, encoded_message in metadata.items():
+        if key != SERVER_WARNING_HEADER:
+            continue
+        print_server_warning(urllib.parse.unquote(encoded_message))
+
+
 def create_channel(
     server_url: str,
     metadata: dict[str, str] = {},
@@ -356,6 +389,12 @@ def create_channel(
 
     grpclib.events.listen(channel, grpclib.events.SendRequest, send_request)
 
+    # Surface warnings the server attached to any response on this channel.
+    async def recv_trailing_metadata(event: grpclib.events.RecvTrailingMetadata) -> None:
+        _issue_server_warnings(event.metadata)
+
+    grpclib.events.listen(channel, grpclib.events.RecvTrailingMetadata, recv_trailing_metadata)
+
     return channel
 
 
@@ -496,6 +535,8 @@ def process_exception_before_retry(
                 raise ConnectionError(str(exc))
             elif isinstance(exc, asyncio.TimeoutError):
                 raise ConnectionError(str(exc))
+            elif isinstance(exc, H2ProtocolError):
+                raise ConnectionError(str(exc))
             else:
                 raise exc
 
@@ -583,6 +624,7 @@ async def _retry_transient_errors(
             OSError,
             asyncio.TimeoutError,
             AttributeError,
+            H2ProtocolError,
         ) as exc:
             # Note that we only catch AttributeError to handle a specific case that works around a bug
             # in grpclib<=0.4.7. See above (search for `write_appdata`).

{modal-1.5.6.dev23 → modal-1.5.6.dev25}/modal/_utils/task_command_router_client.py

@@ -89,6 +89,11 @@ def _parse_jwt_expiration(jwt_token: str) -> float | None:
     return None
 
 
+# Enough consecutive failures to distinguish a connection that keeps breaking from
+# an isolated blip, without leaving a stuck call silent for long.
+RETRY_WARNING_THRESHOLD = 3
+
+
 async def call_with_retries_on_transient_errors(
     func,
     *,
@@ -97,6 +102,9 @@ async def call_with_retries_on_transient_errors(
     max_retries: int | None = 10,
     exclude_status_codes: list[Status] | None = None,
     timeout_deadline: float | None = None,
+    rpc_name: str = "RPC",
+    exec_id: str | None = None,
+    warning_message: str | None = None,
 ):
     """Call func() with transient error retries and exponential backoff.
 
@@ -113,10 +121,18 @@ async def call_with_retries_on_transient_errors(
             exception (e.g., into a TimeoutError) based on the deadline check.
             The caller is also responsible for propagating the remaining budget
             into `func()` (typically as the per-call gRPC timeout).
+        rpc_name: RPC name to include in retry diagnostics.
+        exec_id: Execution ID to include in retry diagnostics, for correlating
+            the retries of concurrent executions.
+        warning_message: Optional warning to emit once after
+            RETRY_WARNING_THRESHOLD consecutive non-timeout failures.
     """
     delay_secs = base_delay_secs
     num_retries = 0
+    consecutive_failures = 0
+    warned = False
     exclude_status_codes = exclude_status_codes or []
+    called_for = f" for exec {exec_id}" if exec_id is not None else ""
 
     def is_retryable_status(status: Status) -> bool:
         return status in RETRYABLE_GRPC_STATUS_CODES and status not in exclude_status_codes
@@ -128,25 +144,41 @@ async def call_with_retries_on_transient_errors(
             return False
         return True
 
-    async def sleep_and_advance(e: Exception):
-        nonlocal delay_secs, num_retries
+    async def sleep_and_advance(e: Exception, *, count_failure: bool = True):
+        nonlocal delay_secs, num_retries, consecutive_failures, warned
         # Clamp the backoff sleep to the remaining deadline so we don't sleep
         # past it just to fail on the next iteration's deadline check.
         sleep_for = delay_secs
         if timeout_deadline is not None:
             sleep_for = min(sleep_for, max(0.0, timeout_deadline - time.monotonic()))
-        logger.debug(f"Retrying RPC with delay {sleep_for}s due to error: {e}")
+        elapsed = time.monotonic() - attempt_started_at
+        logger.debug(
+            f"{rpc_name}{called_for} attempt {num_retries + 1} failed after {elapsed:.3f}s, "
+            f"retrying in {sleep_for}s: {e!r}"
+        )
+        if count_failure:
+            consecutive_failures += 1
+            if warning_message is not None and consecutive_failures >= RETRY_WARNING_THRESHOLD and not warned:
+                logger.warning(
+                    f"{warning_message} Retrying after {consecutive_failures} consecutive failures. "
+                    "Set MODAL_LOGLEVEL=DEBUG for details."
+                )
+                warned = True
+        else:
+            consecutive_failures = 0
         await asyncio.sleep(sleep_for)
         delay_secs *= delay_factor
         num_retries += 1
 
     while True:
+        attempt_started_at = time.monotonic()
         try:
             return await func()
         except GRPCError as e:
             if not is_retryable_status(e.status) or not can_retry():
                 raise
-            await sleep_and_advance(e)
+            # Long-poll deadlines can expire while the process is still running on a healthy connection.
+            await sleep_and_advance(e, count_failure=e.status != Status.DEADLINE_EXCEEDED)
         except AttributeError as e:
             # StreamTerminatedError are not properly raised in grpclib<=0.4.7
             # fixed in https://github.com/vmagamedov/grpclib/issues/185
@@ -165,7 +197,9 @@ async def call_with_retries_on_transient_errors(
                 # `timeout_deadline` can further translate this based on
                 # whether the deadline has elapsed.
                 raise ConnectionError(str(e))
-            await sleep_and_advance(e)
+            # A client-side timeout says nothing about the connection's health, so it
+            # doesn't count toward the warning.
+            await sleep_and_advance(e, count_failure=not isinstance(e, asyncio.TimeoutError))
 
 
 _StdioReq = TypeVar("_StdioReq")
@@ -828,6 +862,12 @@ class TaskCommandRouterClient:
                         #   infinitely retry. For callers without an exec deadline, this
                         #   could hang indefinitely.
                         lambda: self._call_with_auth_retry(self._stub.TaskExecWait, request, timeout=60),
+                        rpc_name="TaskExecWait",
+                        exec_id=exec_id,
+                        warning_message=(
+                            f"Cannot retrieve the exit status for exec {exec_id} due to connection or service errors. "
+                            "The command may have already exited."
+                        ),
                         base_delay_secs=1,  # Retry after 1s since total time is expected to be long.
                         delay_factor=1,  # Fixed delay.
                         max_retries=None,  # Retry forever.

{modal-1.5.6.dev23 → modal-1.5.6.dev25}/modal/cli/config.py

@@ -1,5 +1,5 @@
 # Copyright Modal Labs 2022
-import json
+from json import dumps
 
 import click
 
@@ -21,11 +21,12 @@ config_cli = ModalGroup(
 )
 
 
-@config_cli.command("show", help="Show current configuration values (debugging command).")
+@config_cli.command("show", help="Show current configuration values.")
 @click.option("--redact/--no-redact", default=True, help="Redact secret credential values.")
-def show(redact: bool):
-    # This is just a test command
-    config_dict = config.to_dict()
+@click.option("--include-internal", is_flag=True, help="Include internal feature flags.", hidden=True)
+@click.option("--json", is_flag=True, default=False)
+def show(redact: bool, include_internal: bool, json: bool):
+    config_dict = config.to_dict(include_internal=include_internal)
     if redact and config_dict.get("token_secret"):
         config_dict["token_secret"] = "***"
     if redact and config_dict.get("oauth_refresh_token"):
@@ -33,7 +34,8 @@ def show(redact: bool):
     if redact and config_dict.get("oauth_client_secret"):
         config_dict["oauth_client_secret"] = "***"
 
-    OutputManager.get().print_json(json.dumps(config_dict))
+    # Accept --json as a no-op for consistency; we may change the default formatting later
+    OutputManager.get().print_json(dumps(config_dict))
 
 
 SET_DEFAULT_ENV_HELP = """Set the default Modal environment for the active profile