modal 1.6.1.dev3__tar.gz → 1.6.2__tar.gz

{modal-1.6.1.dev3 → modal-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.6.1.dev3
+Version: 1.6.2
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0
@@ -12,7 +12,7 @@ Keywords: modal,client,cloud,serverless,infrastructure
 Classifier: Topic :: System :: Distributed Computing
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Requires-Python: <3.15,>=3.10
+Requires-Python: <3.16,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp
@@ -29,6 +29,7 @@ Requires-Dist: types-certifi
 Requires-Dist: types-toml
 Requires-Dist: watchfiles
 Requires-Dist: typing_extensions~=4.6
+Requires-Dist: typing_extensions>=4.14; python_version >= "3.15"
 Provides-Extra: api-proxy-support
 Requires-Dist: python-socks[asyncio]>=2.5; extra == "api-proxy-support"
 Requires-Dist: aiohttp-socks>=0.8; extra == "api-proxy-support"
@@ -52,7 +53,7 @@ a [user guide](https://modal.com/docs/guide), and the detailed
 
 ## Installation
 
-**This library requires Python 3.10 – 3.14.**
+**This library requires Python 3.10 – 3.15.**
 
 Install the package with `uv` or `pip`:
 

{modal-1.6.1.dev3 → modal-1.6.2}/README.md

@@ -16,7 +16,7 @@ a [user guide](https://modal.com/docs/guide), and the detailed
 
 ## Installation
 
-**This library requires Python 3.10 – 3.14.**
+**This library requires Python 3.10 – 3.15.**
 
 Install the package with `uv` or `pip`:
 

{modal-1.6.1.dev3 → modal-1.6.2}/modal/__init__.py

@@ -3,8 +3,8 @@ import sys
 
 if sys.version_info[:2] < (3, 10):
     raise RuntimeError("This version of Modal requires at least Python 3.10")
-if sys.version_info[:2] >= (3, 15):
-    raise RuntimeError("This version of Modal does not support Python 3.15+")
+if sys.version_info[:2] >= (3, 16):
+    raise RuntimeError("This version of Modal does not support Python 3.16+")
 
 from modal_version import __version__
 
@@ -43,11 +43,11 @@ try:
     from .queue import Queue
     from .retries import Retries
     from .sandbox import Probe, Sandbox
+    from .sandbox.sandbox import SandboxSnapshot
     from .schedule import Cron, Period
     from .scheduler_placement import SchedulerPlacement
     from .secret import Secret
     from .server import Server
-    from .snapshot import SandboxSnapshot
     from .volume import Volume
     from .workspace import Workspace
 except Exception:

{modal-1.6.1.dev3 → modal-1.6.2}/modal/_environments.py

@@ -54,7 +54,7 @@ class _EnvironmentManager:
         modal.Environment.objects.create("my-environment")
         ```
         """
-        check_environment_name(name)
+        check_environment_name(name, allow_periods=False)
 
         client = await _Client.from_env() if client is None else client
         request = api_pb2.EnvironmentCreateRequest(name=name, is_managed=restricted)
@@ -464,7 +464,7 @@ class _Environment(_Object, type_prefix="en"):
         client: _Client | None = None,
     ) -> "_Environment":
         """Look up an Environment object using its name."""
-        check_environment_name(name)
+        check_environment_name(name, allow_periods=True)
         return _Environment._get_or_create(
             name=name,
             repr=f"Environment.from_name({name!r})",

{modal-1.6.1.dev3 → modal-1.6.2}/modal/_functions.py

@@ -27,6 +27,7 @@ from ._image import _Image
 from ._load_context import LoadContext
 from ._logs import LogsFilters
 from ._logs_manager import _FunctionCallLogsManager, _FunctionLogsManager
+from ._metrics import _FunctionMetricsManager
 from ._object import _Object, live_method, live_method_gen
 from ._output.pty import get_pty_info
 from ._output.status import FunctionCreationStatus
@@ -50,6 +51,7 @@ from ._utils.async_utils import (
 )
 from ._utils.auth_token_manager import _AuthTokenManager
 from ._utils.blob_utils import MAX_ASYNC_OBJECT_SIZE_BYTES, MAX_OBJECT_SIZE_BYTES
+from ._utils.deprecation import deprecation_warning
 from ._utils.function_utils import (
     ATTEMPT_TIMEOUT_GRACE_PERIOD,
     OUTPUTS_TIMEOUT,
@@ -661,6 +663,11 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
             source_object_id=self.object_id,
         )
 
+    @property
+    def metrics(self) -> "_FunctionMetricsManager":
+        """Access metric samples with `export()` and series definitions with `schema()`."""
+        return _FunctionMetricsManager(self)
+
     @property
     def logs(self) -> _FunctionLogsManager:
         """Access logs for a `Function`.
@@ -819,8 +826,8 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
             raise InvalidError(
                 f"`min_containers` ({min_containers}) cannot be greater than `max_containers` ({max_containers})"
             )
-        if scaledown_window is not None and scaledown_window <= 0:
-            raise InvalidError("`scaledown_window` must be > 0")
+        if scaledown_window is not None and not (2 <= scaledown_window <= 3600):
+            raise InvalidError("`scaledown_window` must be between 2 and 3600 (inclusive)")
 
         autoscaler_settings = api_pb2.AutoscalerSettings(
             min_containers=min_containers,
@@ -1390,6 +1397,13 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
             ```
 
         """
+
+        deprecation_warning(
+            (2026, 10, 16),
+            "`Function.update_autoscaler()` is deprecated and will be removed in a future version "
+            "of `modal`. Use `Function.autoscaler.update()` instead.",
+        )
+
         # Assert .update_autoscaler() is not called on a method as opposed to the Object. Applicable for Cls only.
         if self._is_method:
             raise InvalidError("Cannot call .update_autoscaler() on a method. Call it on the class instance instead.")
@@ -2306,6 +2320,11 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
         assert self._metadata
         return self._metadata.function_schema
 
+    @property
+    def autoscaler(self) -> "_FunctionAutoscalerManager":
+        """Namespace for Function autoscaler APIs."""
+        return _FunctionAutoscalerManager(self)
+
     # A bit hacky - but the map-style functions need to not be synchronicity-wrapped
     # in order to not execute their input iterators on the synchronicity event loop.
     # We still need to wrap them using MethodWithAio to maintain a synchronicity-like
@@ -2559,3 +2578,130 @@ class _FunctionCall(typing.Generic[ReturnType], _Object, type_prefix="fc"):
         except Exception as exc:
             # TODO: kill all running function calls
             raise exc
+
+
+UNSET_PARAMETER = -1
+
+
+class _FunctionAutoscalerManager:
+    """mdmd:namespace"""
+
+    def __init__(self, function: _Function):
+        """mdmd:hidden"""
+        self._function = function
+
+    async def settings(self) -> FunctionAutoscalerSettings:
+        """View the current Autoscaler settings for this Function.
+
+        Returns:
+            A `FunctionAutoscalerSettings` dataclass.
+
+        Examples:
+
+            ```python notest
+            fn = modal.Function.from_name("my-app", "my_function")
+            settings = fn.autoscaler.settings()
+            ```
+        """
+
+        if not self._function._is_hydrated:
+            await self._function.hydrate()
+
+        response = await self._function.client._stub.FunctionGetSchedulingParams(
+            api_pb2.FunctionGetSchedulingParamsRequest(function_id=self._function.object_id)
+        )
+
+        ret = FunctionAutoscalerSettings._from_proto(response.autoscaler_configuration.settings)
+        if ret.max_containers == 0:
+            ret = dataclasses.replace(ret, max_containers=None)
+
+        return ret
+
+    async def update(
+        self,
+        *,
+        min_containers: int | None = UNSET_PARAMETER,
+        max_containers: int | None = UNSET_PARAMETER,
+        buffer_containers: int | None = UNSET_PARAMETER,
+        scaledown_window: int = UNSET_PARAMETER,
+    ) -> FunctionAutoscalerSettings:
+        """Override the current Autoscaler settings for this Function.
+
+        All parameters to this function are optional; not passing an argument for a given parameter
+        will not update its value.
+
+        Note that re-deploying the App containing this Function will wipe any overrides and revert
+        its Autoscaler settings back to those defined on the Function at creation time.
+
+        Args:
+            min_containers: Minimum number of containers to keep running. Must be a nonnegative
+                integer, or `None`. Passing `None` is equivalent to setting the minimum to 0.
+            max_containers: Maximum concurrent containers. Must be a positive integer, or `None`.
+                Passing `None` is equivalent to disabling the upper bound on container concurrency at
+                the Function level (note that Environment and Workspace level container upper limits
+                still apply.)
+            buffer_containers: Extra containers to keep warm beyond current demand. Must be a
+                nonnegative integer, or `None`. Passing `None` is equivalent to setting the buffer to
+                0.
+            scaledown_window: Maximum duration (in seconds) idle containers wait before scaling down.
+                Must be a positive integer between 2 and 3600, inclusive.
+
+        Returns:
+            A `FunctionAutoscalerSettings` dataclass.
+
+        Examples:
+
+            Update `my_function` so that 2 containers are always active.
+
+            ```python notest
+            fn = modal.Function.from_name("my-app", "my_function")
+            fn.autoscaler.update(min_containers=2)
+            ```
+
+            Update `my_function` so that there is no Function-level limit on `max_containers`:
+
+            ```python notest
+            fn = modal.Function.from_name("my-app", "my_function")
+            fn.autoscaler.update(max_containers=None)
+            ```
+        """
+
+        if not self._function._is_hydrated:
+            await self._function.hydrate()
+
+        settings: api_pb2.AutoscalerSettings = api_pb2.AutoscalerSettings()
+
+        if min_containers != UNSET_PARAMETER:
+            min_containers = min_containers if min_containers is not None else 0
+            if min_containers < 0:
+                raise InvalidError("Invalid argument: `min_containers` must be a nonnegative integer or `None`.")
+
+            settings.min_containers = min_containers
+
+        if buffer_containers != UNSET_PARAMETER:
+            buffer_containers = buffer_containers if buffer_containers is not None else 0
+            if buffer_containers < 0:
+                raise InvalidError("Invalid argument: `buffer_containers` must be a nonnegative integer or `None`.")
+
+            settings.buffer_containers = buffer_containers
+
+        if max_containers != UNSET_PARAMETER:
+            if max_containers is not None and max_containers <= 0:
+                raise InvalidError("Invalid argument: `max_containers` must be a postive integer or `None`.")
+
+            settings.max_containers = max_containers if max_containers is not None else 0
+
+        if scaledown_window != UNSET_PARAMETER:
+            if not (2 <= scaledown_window <= 3600):
+                raise InvalidError("Invalid argument: `scaledown_window` must be between 2 and 3600 (inclusive)")
+
+            settings.scaledown_window = scaledown_window
+
+        request = api_pb2.FunctionUpdateSchedulingParamsRequest(function_id=self._function.object_id, settings=settings)
+        response = await self._function.client._stub.FunctionUpdateSchedulingParams(request)
+
+        ret = FunctionAutoscalerSettings._from_proto(response.current_settings)
+        if ret.max_containers == 0:
+            ret = dataclasses.replace(ret, max_containers=None)
+
+        return ret

{modal-1.6.1.dev3 → modal-1.6.2}/modal/_image.py

@@ -76,8 +76,8 @@ 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.10", "3.11", "3.12", "3.13", "3.14", "3.14t"],
-    "2025.06": ["3.10", "3.11", "3.12", "3.13", "3.14", "3.14t"],
+    "PREVIEW": ["3.10", "3.11", "3.12", "3.13", "3.14", "3.14t", "3.15", "3.15t"],
+    "2025.06": ["3.10", "3.11", "3.12", "3.13", "3.14", "3.14t", "3.15", "3.15t"],
     "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"],

{modal-1.6.1.dev3 → modal-1.6.2}/modal/_logs.py

@@ -3,9 +3,9 @@ from __future__ import annotations
 
 import asyncio
 import dataclasses
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Awaitable, Callable
 from datetime import datetime, timedelta, timezone
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Sequence, TypeVar
 
 from google.protobuf.timestamp_pb2 import Timestamp
 
@@ -13,6 +13,9 @@ from modal._utils.async_utils import TaskContext
 from modal.exception import LogsFetchError
 from modal_proto import api_pb2
 
+_T = TypeVar("_T")
+_CountRanges = Callable[[float, float, int], Awaitable[list[tuple[float, float, int]]]]
+
 if TYPE_CHECKING:
     from modal.client import _Client
 
@@ -194,6 +197,32 @@ def _next_smaller_bucket_secs(current_bucket_secs: int) -> int | None:
     return None
 
 
+async def _count_log_ranges(
+    client: _Client,
+    app_id: str,
+    since: float,
+    until: float,
+    bucket_secs: int,
+    filters: LogsFilters,
+) -> list[tuple[float, float, int]]:
+    count_req = api_pb2.AppCountLogsRequest(
+        app_id=app_id,
+        since=_seconds_to_timestamp(since),
+        until=_seconds_to_timestamp(until),
+        bucket_secs=bucket_secs,
+        source=filters.source,
+        function_id=filters.function_id,
+        parametrized_function_id=filters.parametrized_function_id,
+        function_call_id=filters.function_call_id,
+        task_id=filters.task_id,
+        sandbox_id=filters.sandbox_id,
+        search_text=filters.search_text,
+    )
+    count_resp: api_pb2.AppCountLogsResponse = await client._stub.AppCountLogs(count_req)
+
+    return _buckets_to_ranges(list(count_resp.buckets), bucket_secs)
+
+
 async def _refine_dense_ranges(
     client: _Client,
     app_id: str,
@@ -201,6 +230,19 @@ async def _refine_dense_ranges(
     filters: LogsFilters,
     max_ranges: int,
     max_iterations: int,
+) -> list[tuple[float, float, int]]:
+    async def count_ranges(start: float, end: float, bucket_secs: int) -> list[tuple[float, float, int]]:
+        return await _count_log_ranges(client, app_id, start, end, bucket_secs, filters)
+
+    return await _refine_ranges(ranges, count_ranges, max_ranges, max_iterations)
+
+
+async def _refine_ranges(
+    ranges: list[tuple[float, float, int]],
+    count_ranges: _CountRanges,
+    max_ranges: int,
+    max_iterations: int,
+    max_concurrent_counts: int = _MAX_CONCURRENT_COUNTS,
 ) -> list[tuple[float, float, int]]:
     """Refine ranges exceeding _FETCH_LIMIT by subdividing with smaller buckets.
 
@@ -239,25 +281,11 @@ async def _refine_dense_ranges(
             break
 
         # Fire off all re-count RPCs in parallel with bounded concurrency
-        semaphore = asyncio.Semaphore(_MAX_CONCURRENT_COUNTS)
+        semaphore = asyncio.Semaphore(max_concurrent_counts)
 
         async def _recount(start: float, end: float, smaller_secs: int) -> list[tuple[float, float, int]]:
             async with semaphore:
-                sub_req = api_pb2.AppCountLogsRequest(
-                    app_id=app_id,
-                    since=_seconds_to_timestamp(start),
-                    until=_seconds_to_timestamp(end),
-                    bucket_secs=smaller_secs,
-                    source=filters.source,
-                    function_id=filters.function_id,
-                    parametrized_function_id=filters.parametrized_function_id,
-                    function_call_id=filters.function_call_id,
-                    task_id=filters.task_id,
-                    sandbox_id=filters.sandbox_id,
-                    search_text=filters.search_text,
-                )
-                sub_resp = await client._stub.AppCountLogs(sub_req)
-                sub_ranges = _buckets_to_ranges(list(sub_resp.buckets), smaller_secs)
+                sub_ranges = await count_ranges(start, end, smaller_secs)
                 # 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
@@ -418,26 +446,34 @@ 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(
-        app_id=app_id,
-        since=_datetime_to_timestamp(since),
-        until=_datetime_to_timestamp(until),
-        bucket_secs=bucket_secs,
-        source=filters.source,
-        function_id=filters.function_id,
-        parametrized_function_id=filters.parametrized_function_id,
-        function_call_id=filters.function_call_id,
-        task_id=filters.task_id,
-        sandbox_id=filters.sandbox_id,
-        search_text=filters.search_text,
-    )
-    count_resp: api_pb2.AppCountLogsResponse = await client._stub.AppCountLogs(count_req)
 
-    ranges = _buckets_to_ranges(list(count_resp.buckets), bucket_secs)
-    total_logs = sum(count for _, _, count in ranges)
-    if total_logs == 0:
+    async def count_ranges(start: float, end: float, bucket_secs: int) -> list[tuple[float, float, int]]:
+        return await _count_log_ranges(client, app_id, start, end, bucket_secs, filters)
+
+    async def fetch_interval(start: float, end: float, limit: int) -> list[api_pb2.TaskLogsBatch]:
+        return await _fetch_interval(client, app_id, start, end, limit, filters)
+
+    async for batch in _fetch_time_range(
+        since,
+        until,
+        count_ranges,
+        fetch_interval,
+    ):
+        yield batch
+
+
+async def _fetch_time_range(
+    since: datetime,
+    until: datetime,
+    count_ranges: _CountRanges,
+    fetch_interval: Callable[[float, float, int], Awaitable[Sequence[_T]]],
+    *,
+    max_concurrent_counts: int = _MAX_CONCURRENT_COUNTS,
+) -> AsyncGenerator[_T]:
+    """Count, refine, and fetch time intervals with bounded concurrency and ordered results."""
+    ranges = await count_ranges(since.timestamp(), until.timestamp(), _pick_bucket_secs(since, until))
+    total_records = sum(count for _, _, count in ranges)
+    if total_records == 0:
         return
 
     # Trim leading/trailing empty buckets so they don't consume refinement
@@ -449,19 +485,17 @@ async def fetch_logs(
 
     # Phase 1b: Refine any ranges that exceed the per-fetch limit.
     # Budget: at most _MAX_FETCHES intervals, each fetching up to _FETCH_LIMIT entries.
-    ranges = await _refine_dense_ranges(
-        client,
-        app_id,
+    ranges = await _refine_ranges(
         ranges,
-        filters,
+        count_ranges,
         max_ranges=_MAX_FETCHES,
         max_iterations=_MAX_REFINE_ITERATIONS,
+        max_concurrent_counts=max_concurrent_counts,
     )
-    fetch_error_message = "Too many logs to fetch in time range. Consider narrowing the range or adding filters."
     # Check that all ranges fit within the per-fetch limit.
     over_limit = [r for r in ranges if r[2] > _FETCH_LIMIT]
     if over_limit:
-        raise LogsFetchError(fetch_error_message)
+        raise LogsFetchError("Too many logs to fetch in time range. Consider narrowing the range or adding filters.")
 
     # Phase 2: Build intervals from non-empty ranges and fetch in parallel
     since_secs = since.timestamp()
@@ -476,24 +510,17 @@ async def fetch_logs(
         return
 
     if len(intervals) > _MAX_FETCHES:
-        raise LogsFetchError(fetch_error_message)
+        raise LogsFetchError("Too many logs to fetch in time range. Consider narrowing the range or adding filters.")
 
     # Fetch all intervals concurrently (bounded by semaphore), but yield
-    # results in interval order so logs stay chronological. Awaiting each
+    # results in interval order so records stay chronological. Awaiting each
     # task in sequence lets us stream batches to the caller as soon as all
     # preceding intervals have completed.
     semaphore = asyncio.Semaphore(_MAX_CONCURRENT_FETCHES)
 
-    async def _bounded_fetch(since_s: float, until_s: float) -> list[api_pb2.TaskLogsBatch]:
+    async def _bounded_fetch(since_s: float, until_s: float) -> Sequence[_T]:
         async with semaphore:
-            return await _fetch_interval(
-                client,
-                app_id,
-                since_s,
-                until_s,
-                _FETCH_LIMIT,
-                filters,
-            )
+            return await fetch_interval(since_s, until_s, _FETCH_LIMIT)
 
     tasks = [asyncio.create_task(_bounded_fetch(s, u)) for s, u in intervals]
 
@@ -504,3 +531,4 @@ async def fetch_logs(
     finally:
         for task in tasks:
             task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)