modal 1.5.6.dev12__tar.gz → 1.5.6.dev14__tar.gz

{modal-1.5.6.dev12 → modal-1.5.6.dev14}/PKG-INFO

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

{modal-1.5.6.dev12 → modal-1.5.6.dev14}/modal/_functions.py

@@ -8,6 +8,7 @@ import warnings
 from collections import OrderedDict
 from collections.abc import AsyncGenerator, AsyncIterator, Callable, Collection, Sequence
 from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
 from pathlib import PurePosixPath
 from typing import TYPE_CHECKING, Any
 
@@ -64,7 +65,7 @@ from ._utils.function_utils import (
     parse_gpu_config,
     validate_target_concurrency,
 )
-from ._utils.grpc_utils import Retry, RetryWarningMessage
+from ._utils.grpc_utils import Retry, RetryWarningMessage, is_class_function_lookup_error
 from ._utils.mount_utils import validate_network_file_systems, validate_volumes, validate_volumes_by_object_id
 from .call_graph import InputInfo, _reconstruct_call_graph
 from .client import _Client
@@ -99,7 +100,12 @@ from .proxy import _Proxy
 from .retries import Retries, RetryManager
 from .schedule import Schedule
 from .secret import _Secret
-from .types import FunctionAutoscalerSettings, FunctionStats, ServerAutoscalerSettings
+from .types import (
+    FunctionAutoscalerSettings,
+    FunctionCurrentStats,
+    FunctionStats,
+    ServerAutoscalerSettings,
+)
 from .volume import _Volume, _volume_to_mount_proto
 
 if TYPE_CHECKING:
@@ -1361,9 +1367,13 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
                 env_context = (
                     f" (in the '{load_context.environment_name}' environment)" if load_context.environment_name else ""
                 )
-                raise NotFoundError(
-                    f"Lookup failed for Function '{name}' from the '{app_name}' app{env_context}: {exc}."
-                ) from None
+                msg = f"Lookup failed for Function '{name}' from the '{app_name}' app{env_context}: {exc}."
+                if is_class_function_lookup_error(exc):
+                    msg = (
+                        f"Function '{name}' from the '{app_name}' app{env_context} is a modal.Cls. "
+                        f"Use `modal.Cls.from_name` instead."
+                    )
+                raise NotFoundError(msg) from None
 
             print_server_warnings(response.server_warnings)
 
@@ -2144,23 +2154,61 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
         return self._raw_f
 
     @live_method
-    async def get_current_stats(self) -> FunctionStats:
-        """Return a `FunctionStats` object describing the current function's queue and runner counts.
+    async def get_current_stats(self) -> FunctionCurrentStats:
+        """Return a snapshot of the Function's current input and container state.
 
         Returns:
-            Snapshot counts for backlog, runners, and running inputs.
+            A `FunctionCurrentStats` object containing live input and container counts.
         """
         resp = await self.client.stub.FunctionGetCurrentStats(
             api_pb2.FunctionGetCurrentStatsRequest(function_id=self.object_id),
             retry=Retry(total_timeout=10.0),
         )
-        return FunctionStats(
+        return FunctionCurrentStats(
             backlog=resp.backlog,
             num_total_runners=resp.num_total_tasks,
             num_running_inputs=resp.num_running_inputs,
             input_headroom=resp.input_headroom,
         )
 
+    @live_method
+    async def stats(
+        self, *, since: datetime | None = None, until: datetime | None = None, container: str | None = None
+    ) -> FunctionStats:
+        """Return statistics for a modal Function.
+
+        The default time range is the most recent hour. The maximum time range is 7 days.
+
+        Args:
+            since: The beginning of the time range, inclusive. If omitted, this defaults to an hour before `until`.
+               Values without a timezone are interpeted as local time.
+            until: The end of the time range, exclusive. If omitted, this defaults to current time.
+                Values without a timezone are interpeted as local time.
+            container: If passed in, the stats are computed for only this container. Default None.
+
+        Returns:
+            A `FunctionStats` object
+        """
+        until = until or datetime.now(timezone.utc)
+        if until.tzinfo is None:
+            until = until.astimezone()
+        until = until.astimezone(timezone.utc)
+
+        since = since or until - timedelta(hours=1)
+        if since.tzinfo is None:
+            since = since.astimezone()
+        since = since.astimezone(timezone.utc)
+        if since >= until:
+            raise InvalidError("`since` must be before `until`.")
+
+        historical_request = api_pb2.FunctionGetTimeRangeStatsRequest(function_id=self.object_id)
+        historical_request.since.FromDatetime(since)
+        historical_request.until.FromDatetime(until)
+        if container:
+            historical_request.container_id = container
+        stats = await self.client.stub.FunctionGetTimeRangeStats(historical_request)
+        return FunctionStats._from_proto(stats)
+
     @live_method
     async def _get_schema(self) -> api_pb2.FunctionSchema:
         """Returns recorded schema for function, internal use only for now"""

{modal-1.5.6.dev12 → modal-1.5.6.dev14}/modal/_output/status.py

@@ -46,16 +46,17 @@ class FunctionCreationStatus:
 
         if not self.response:
             self.status_row.finish(f"Unknown error when creating function {self.tag}")
+            return
 
-        elif web_url := self.response.handle_metadata.web_url:
+        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
             requires_proxy_auth = self.response.function.webhook_config.requires_proxy_auth
             proxy_auth_suffix = " 🔑" if requires_proxy_auth else ""
             # Ensure terms used here match terms used in modal.com/docs/guide/webhook-urls doc.
             suffix = _get_suffix_from_web_url_info(url_info)
-            # TODO: this is only printed when we're showing progress. Maybe move this somewhere else.
-            for warning in self.response.server_warnings:
-                self.status_row.warn(warning)
             self.status_row.finish(
                 f"Created web function {self.tag} => [magenta underline]{web_url}[/magenta underline]"
                 f"{proxy_auth_suffix}{suffix}"
@@ -78,8 +79,6 @@ class FunctionCreationStatus:
                 )
 
         else:
-            for warning in self.response.server_warnings:
-                self.status_row.warn(warning)
             self.status_row.finish(f"Created function {self.tag}.")
             if self.response.function.method_definitions_set:
                 for method_definition in self.response.function.method_definitions.values():

{modal-1.5.6.dev12 → modal-1.5.6.dev14}/modal/_utils/auth_token_manager.py

@@ -4,6 +4,7 @@ import base64
 import json
 import random
 import time
+from collections.abc import Awaitable, Callable
 from typing import Any
 
 from modal._utils.grpc_utils import DEFAULT_MAX_RETRIES, Retry
@@ -15,8 +16,15 @@ from .logger import logger
 AUTH_DENIED_EXCEPTIONS = (AuthError, PermissionDeniedError)
 
 
+TokenFetcher = Callable[[Retry], Awaitable[str]]
+
+
 class _AuthTokenManager:
-    """Handles fetching and refreshing of the input plane auth token."""
+    """Handles fetching and refreshing of a short-lived JWT.
+
+    Defaults to the input plane auth token (`AuthTokenGet`); pass `fetch` to manage a different token with the
+    same caching and refresh behavior.
+    """
 
     # Fraction of the token's lifetime to use before refreshing.
     REFRESH_FRACTION = 0.5
@@ -26,7 +34,7 @@ class _AuthTokenManager:
     # only ever delays a refresh, so the margin before expiry stays at no less than
     # 1 - REFRESH_FRACTION - REFRESH_JITTER of the lifetime.
     REFRESH_JITTER = 0.1
-    # Bound each AuthTokenGet attempt so a refresh can't hang.
+    # Bound each fetch attempt so a refresh can't hang.
     AUTH_TOKEN_TIMEOUT = 5.0
     AUTH_TOKEN_RETRY_TOTAL_TIMEOUT = 3 * AUTH_TOKEN_TIMEOUT
     # After a failed refresh, wait before hitting the server again, growing exponentially with
@@ -36,8 +44,9 @@ class _AuthTokenManager:
     # If the token doesn't have an expiry field, default to current time plus this value (not expected).
     DEFAULT_EXPIRY_OFFSET = 20 * 60
 
-    def __init__(self, stub: "modal_api_grpc.ModalClientModal"):
+    def __init__(self, stub: "modal_api_grpc.ModalClientModal", fetch: TokenFetcher | None = None):
         self._stub = stub
+        self._fetch = fetch or self._fetch_auth_token
         self._token = ""
         self._expiry = 0.0
         self._refresh_at = 0.0
@@ -105,31 +114,33 @@ class _AuthTokenManager:
             # Retrieve the exception, if any, so a failure isn't logged as unhandled when no caller is waiting.
             task.exception()
 
+    async def _fetch_auth_token(self, retry: Retry) -> str:
+        resp: api_pb2.AuthTokenGetResponse = await self._stub.AuthTokenGet(api_pb2.AuthTokenGetRequest(), retry=retry)
+        return resp.token
+
     async def _fetch_token(self):
-        """Make the AuthTokenGet request and cache its token, or arm the failure backoff."""
+        """Fetch a new token and cache it, or arm the failure backoff."""
         try:
-            resp: api_pb2.AuthTokenGetResponse = await self._stub.AuthTokenGet(
-                api_pb2.AuthTokenGetRequest(),
-                # No cached token to fall back on, so a failure is user-visible: retry transient errors.
-                # Otherwise one attempt, and _retry_after handles the cooldown.
-                retry=Retry(
-                    attempt_timeout=self.AUTH_TOKEN_TIMEOUT,
-                    total_timeout=self.AUTH_TOKEN_RETRY_TOTAL_TIMEOUT,
-                    max_retries=0 if self._token else DEFAULT_MAX_RETRIES,
-                ),
+            # No cached token to fall back on, so a failure is user-visible: retry transient errors.
+            # Otherwise one attempt, and _retry_after handles the cooldown.
+            retry = Retry(
+                attempt_timeout=self.AUTH_TOKEN_TIMEOUT,
+                total_timeout=self.AUTH_TOKEN_RETRY_TOTAL_TIMEOUT,
+                max_retries=0 if self._token else DEFAULT_MAX_RETRIES,
             )
-            if not resp.token:
+            token = await self._fetch(retry)
+            if not token:
                 # Not expected
                 raise ExecutionError(
                     "Internal error: Did not receive auth token from server. Please contact Modal support."
                 )
-            if exp := self._decode_jwt(resp.token).get("exp"):
+            if exp := self._decode_jwt(token).get("exp"):
                 expiry = float(exp)
             else:
                 # This should never happen.
-                logger.warning("x-modal-auth-token does not contain exp field")
+                logger.warning("Auth token does not contain exp field")
                 expiry = time.time() + self.DEFAULT_EXPIRY_OFFSET
-            self._token = resp.token
+            self._token = token
             self._set_expiry(expiry)
             self._retry_after = 0.0
             self._backoff = self.FAILURE_BACKOFF_BASE

{modal-1.5.6.dev12 → modal-1.5.6.dev14}/modal/_utils/grpc_utils.py

@@ -25,7 +25,7 @@ from grpclib.encoding.base import CodecBase, StatusDetailsCodecBase
 from grpclib.exceptions import StreamTerminatedError
 from grpclib.protocol import H2Protocol
 
-from modal.exception import ClientClosed, ConnectionError
+from modal.exception import ClientClosed, ConnectionError, NotFoundError
 from modal_proto import api_pb2
 from modal_version import __version__
 
@@ -121,12 +121,12 @@ class ModalChannel(grpclib.client.Channel):
         self.__target_host = host
         self.__target_port = port
         self.__ssl_context = ssl_context
-        self.__closed = False
-        self.__closed_error_message = closed_error_message
+        self._permanently_closed = False
+        self._closed_error_message = closed_error_message
 
     async def __connect__(self):
-        if self.__closed and self.__closed_error_message is not None:
-            raise ClientClosed(self.__closed_error_message)
+        if self._permanently_closed and self._closed_error_message is not None:
+            raise ClientClosed(self._closed_error_message)
         return await super().__connect__()
 
     async def _create_connection(self) -> H2Protocol:
@@ -161,8 +161,13 @@ class ModalChannel(grpclib.client.Channel):
             and not self._protocol.connection.is_closing()
         )
 
+    def release_connection(self):
+        """Release the connection while leaving the channel reusable."""
+        return super().close()
+
     def close(self):
-        self.__closed = True
+        """Close the channel permanently."""
+        self._permanently_closed = True
         return super().close()
 
 
@@ -450,6 +455,15 @@ async def retry_transient_errors(
     return await _retry_transient_errors(fn, req, retry=Retry(max_retries=max_retries))
 
 
+def is_class_function_lookup_error(exc: NotFoundError) -> bool:
+    """Whether a function lookup failed because the requested name identifies a class."""
+    return any(
+        isinstance(detail, api_pb2.FunctionLookupError)
+        and detail.reason == api_pb2.FunctionLookupError.REASON_CLASS_NAME_USED
+        for detail in (getattr(exc, "_grpc_details", None) or [])
+    )
+
+
 def get_server_retry_policy(exc: Exception) -> api_pb2.RPCRetryPolicy | None:
     """Get server retry policy."""
     if not isinstance(exc, GRPCError) or not exc.details:

modal-1.5.6.dev14/modal/_utils/idle_countdown.py

@@ -0,0 +1,64 @@
+# Copyright Modal Labs 2025
+import asyncio
+from collections.abc import Callable
+
+
+class IdleCountdown:
+    """An extendable idle timeout tracker."""
+
+    def __init__(self, loop: asyncio.AbstractEventLoop) -> None:
+        self._loop = loop
+        self._handle: asyncio.TimerHandle | None = None
+        self._retired = False
+        self._expire_on_idle = False
+        self._release: Callable[[], None] | None = None
+
+    def _assert_owning_loop(self) -> None:
+        assert asyncio.get_running_loop() is self._loop, "Idle bookkeeping must run on its owning event loop"
+
+    def expire_when_idle(self) -> None:
+        """Release at the current or next idle boundary, even if the timeout is disabled.
+
+        Must run on the owning event loop without yielding control.
+        """
+        self._assert_owning_loop()
+        self._expire_on_idle = True
+        if self._release is not None and not self._retired:
+            release = self._release
+            self.stop()
+            release()
+
+    def stop(self) -> None:
+        """Cancel the countdown on the owning event loop without yielding control."""
+        self._assert_owning_loop()
+        self._release = None
+        if self._handle is not None:
+            self._handle.cancel()
+            self._handle = None
+
+    def retire(self) -> None:
+        """Stop the countdown and refuse every subsequent arm.
+
+        Must run on the owning event loop without yielding control.
+        """
+        self._assert_owning_loop()
+        self._retired = True
+        self.stop()
+
+    def arm(self, timeout_secs: float, release: Callable[[], None]) -> None:
+        """Start the countdown again, calling `release` when it elapses.
+
+        Must run on the owning event loop without yielding control.
+        A timeout of zero or less never fires unless `expire_when_idle` was
+        requested. `release` runs as a plain callback on the event loop, so it
+        must not block.
+        """
+        self.stop()
+        if self._retired:
+            return
+        self._release = release
+        if self._expire_on_idle:
+            timeout_secs = 0
+        elif timeout_secs <= 0:
+            return
+        self._handle = self._loop.call_later(timeout_secs, release)