modal 1.6.2.dev7__py3-none-any.whl → 1.6.2.dev8__py3-none-any.whl

modal/_utils/async_utils.py

@@ -378,7 +378,7 @@ def retry(
 
     Usage:
 
-    ```
+    ```python notest
     @retry
     async def may_fail_default():
         # ...
@@ -907,8 +907,10 @@ async def asyncnullcontext(*args, **kwargs):
     Note that for Python 3.10+ you can use contextlib.nullcontext() instead.
 
     Usage:
+    ```python notest
     async with asyncnullcontext():
         pass
+    ```
     """
     yield
 

modal/_utils/blob_utils.py

@@ -18,6 +18,7 @@ from typing import (
 )
 from urllib.parse import urlparse
 
+from google.protobuf.timestamp_pb2 import Timestamp
 from typing_extensions import Self
 
 from modal_proto import api_pb2
@@ -451,6 +452,7 @@ class FileUploadSpec:
     size: int
     content: bytes | None = None  # Set for very small files to avoid double-read
     exists_in_store: bool | None = None  # set after existence check
+    checked_at: Timestamp | None = None  # server time of the existence check, set alongside exists_in_store
 
     def read_content(self) -> bytes:
         """Read content from source."""

modal/cli/_logs.py

@@ -19,7 +19,7 @@ _SOURCE_OPTIONS = {
 }
 
 
-def _parse_time_arg(value: str | None, default: datetime, *, now: datetime | None = None) -> datetime:
+def _parse_time_arg(value: str | None, default: datetime, *, now: datetime) -> datetime:
     """Parse a time argument that can be a relative duration (e.g. '2h', '30m') or ISO 8601 datetime.
 
     Naive datetime values are interpreted in the user's local timezone.
@@ -33,7 +33,7 @@ def _parse_time_arg(value: str | None, default: datetime, *, now: datetime | Non
     except ValueError:
         pass
     else:
-        return (now or datetime.now(timezone.utc)) - duration
+        return now - duration
 
     try:
         dt = datetime.fromisoformat(value)
@@ -62,7 +62,7 @@ def _parse_fetch_range(since: str | None, until: str | None) -> tuple[datetime,
         try:
             duration = parse_duration(value)
         except ValueError:
-            result = _parse_time_arg(value, default=default)
+            result = _parse_time_arg(value, default=default, now=now)
         else:
             result = now - duration
         if result.astimezone(timezone.utc).microsecond:
@@ -124,8 +124,8 @@ async def _run_logs_command(
         return
 
     now = datetime.now(timezone.utc)
-    since_dt = _parse_time_arg(since, default=now) if since else None
-    until_dt = _parse_time_arg(until, default=now) if until else None
+    since_dt = _parse_time_arg(since, default=now, now=now) if since else None
+    until_dt = _parse_time_arg(until, default=now, now=now) if until else None
     if since_dt is not None:
         effective_until = until_dt or now
         if since_dt >= effective_until:

modal/cli/container.py

@@ -248,8 +248,8 @@ async def logs(
             since_dt = default_since_dt
             until_dt = default_until_dt
         else:
-            since_dt = _parse_time_arg(since, default=default_since_dt)
-            until_dt = _parse_time_arg(until, default=default_until_dt)
+            since_dt = _parse_time_arg(since, default=default_since_dt, now=now)
+            until_dt = _parse_time_arg(until, default=default_until_dt, now=now)
 
         if since is not None and until is not None and since_dt >= until_dt:
             # User provided both --since and --until, but did so incorrectly

modal/cli/function.py

@@ -7,6 +7,7 @@ from typing import Any, AsyncGenerator, Sequence, cast
 
 import click
 from click import UsageError
+from rich.box import SIMPLE
 from rich.table import Column, Table
 from rich.text import Text
 
@@ -16,7 +17,7 @@ from modal._functions import _Function
 from modal._logs import _fetch_time_range, _seconds_to_timestamp, _timestamp_to_seconds
 from modal._object import _get_environment_name
 from modal._utils.async_utils import async_map_ordered, synchronizer
-from modal._utils.time_utils import parse_duration
+from modal._utils.time_utils import parse_duration, timestamp_to_localized_str
 from modal.client import _Client
 from modal.exception import LogsFetchError, NotFoundError
 from modal.output import OutputManager
@@ -50,10 +51,12 @@ from .utils import (
     env_option,
     grouped_utc_timestamp,
     humanize_filesize,
+    parse_int,
 )
 
 function_cli = ModalGroup(name="function", help="Inspect Modal Functions.")
 
+
 _INPUT_METRIC_ORDER = ("Execution time (s)", "End-to-end latency (s)")
 _CONTAINER_METRIC_ORDER = (
     "Startup time (s)",
@@ -705,8 +708,8 @@ async def stats(
     ```
     """
     now = datetime.now(timezone.utc)
-    until_dt = _parse_time_arg(until, default=now)
-    since_dt = _parse_time_arg(since, default=until_dt - _DEFAULT_STATS_WINDOW)
+    until_dt = _parse_time_arg(until, default=now, now=now)
+    since_dt = _parse_time_arg(since, default=until_dt - _DEFAULT_STATS_WINDOW, now=now)
     if since_dt >= until_dt:
         raise UsageError("--since must be before --until.")
 
@@ -1288,6 +1291,241 @@ async def variants(
         )
 
 
+autoscaler_cli = ModalGroup(name="autoscaler", help="View and Configure Autoscaler settings for Modal Functions.")
+function_cli.add_command(autoscaler_cli)
+
+
+@autoscaler_cli.command("settings", no_args_is_help=True)
+@click.argument("function_identifier", metavar="FUNCTION")
+@click.option("--json", "json", is_flag=True, default=False, help="Output as JSON.")
+@env_option
+@synchronizer.create_blocking
+async def autoscaler_info(function_identifier: str, json: bool = False, env: str | None = None):
+    """Show the current Autsocaling settings for the provided Function.
+
+    In addition to the current settings, this command also shows any active overrides to these
+    settings, along with metadata about who overrode the setting, and when. FUNCTION may be a
+    Function ID or a deployed Function name in the form ``APP_NAME/FUNCTION_NAME``.
+
+    If a setting's value is the default and not overridden, its value is omitted in the output.
+
+    Examples:
+
+    Show autoscaling settings for a deployed Function:
+
+    ```
+    modal function autoscaler settings my-app/my-function
+    ```
+
+    Show autoscaling settings using a Function ID:
+
+    ```
+    modal function autoscaler settings fu-1234
+    ```
+    """
+
+    environment_name = _get_environment_name(ensure_env(env))
+    client = await _Client.from_env()
+    function_id, handle_metadata, _ = await _resolve_function_id(
+        client,
+        function_identifier,
+        environment_name,
+        object_type="Function",
+        command="autoscaler settings",
+    )
+
+    if not handle_metadata.base_function_id and len(handle_metadata.class_parameter_info.schema) > 0:
+        raise ValueError(
+            f"`{function_identifier}` is a modal.Cls with parameters. Provide a specific "
+            "parameterization via a Function ID. See `modal function variants`."
+        )
+
+    autoscaler_response = await client._stub.FunctionGetSchedulingParams(
+        api_pb2.FunctionGetSchedulingParamsRequest(function_id=function_id)
+    )
+
+    autoscaler_settings = FunctionAutoscalerSettings._from_proto(autoscaler_response.autoscaler_configuration.settings)
+    override_events = autoscaler_response.autoscaler_configuration.override_events
+
+    output_manager = OutputManager.get()
+
+    if json:
+        current_settings = dataclasses.asdict(autoscaler_settings)
+
+        override_events_json: list[dict[str, str]] = []
+        for k, v in override_events.items():
+            if v.user_id:
+                obj = {
+                    "setting": k,
+                    "updated_at": str(v.timestamp),
+                    "actor_name": v.requested_by,
+                    "actor_id": v.user_id,
+                    "actor_type": "user",
+                }
+            elif v.service_user_id:
+                obj = {
+                    "setting": k,
+                    "updated_at": str(v.timestamp),
+                    "actor_name": v.requested_by,
+                    "actor_id": v.service_user_id,
+                    "actor_type": "service-user",
+                }
+            else:
+                obj = {
+                    "setting": k,
+                    "updated_at": str(v.timestamp),
+                    "actor_id": "unknown",
+                    "actor_name": "unknown",
+                    "actor_type": "unknown",
+                }
+
+            override_events_json.append(obj)
+
+        output_manager.print_json(
+            json_lib.dumps(
+                {
+                    "current_settings": current_settings,
+                    "override_events": override_events_json,
+                }
+            )
+        )
+
+        return
+
+    human_readable = {
+        "min_containers": "Min Containers",
+        "max_containers": "Max Containers",
+        "buffer_containers": "Buffer Containers",
+        "scaledown_window": "Scaledown Window",
+    }
+
+    if override_events:
+        t = Table("Setting", "Value", "Overridden By", box=SIMPLE)
+    else:
+        t = Table("Setting", "Value", box=SIMPLE)
+
+    for key, pretty in human_readable.items():
+        value = getattr(autoscaler_settings, key)
+        value_str = str(value)
+
+        override_meta = "-"
+        if key in override_events:
+            override = override_events[key]
+            override_meta = f"{override.requested_by} at {timestamp_to_localized_str(override.timestamp, isotz=False)}"
+
+        if key == "scaledown_window":
+            value_str = f"{value} seconds"
+
+        if key not in override_events and not value:
+            value_str = "-"
+
+        if override_events:
+            t.add_row(pretty, value_str, override_meta)
+        else:
+            t.add_row(pretty, value_str)
+
+    output_manager.print(t)
+
+
+@autoscaler_cli.command("update", no_args_is_help=True)
+@click.argument("function_identifier", metavar="FUNCTION")
+@click.option("--max-containers", "max_containers", default=None, help="Maximum concurrent containers.")
+@click.option("--min-containers", "min_containers", default=None, help="Minimum number of containers to keep running.")
+@click.option(
+    "--buffer-containers",
+    "buffer_containers",
+    default=None,
+    help="Extra containers to keep warm beyond current demand.",
+)
+@click.option(
+    "--scaledown-window",
+    "scaledown_window",
+    default=None,
+    help="Maximum duration (in seconds) idle containers wait before scaling down.",
+)
+@env_option
+@synchronizer.create_blocking
+async def autoscaler_update(
+    function_identifier: str,
+    max_containers: str | None = None,
+    min_containers: str | None = None,
+    buffer_containers: str | None = None,
+    scaledown_window: str | None = None,
+    env: str | None = None,
+):
+    """Update the current Autsocaling settings for the provided Function.
+
+    FUNCTION may be a Function ID or a deployed Function name in the form ``APP_NAME/FUNCTION_NAME``.
+
+    Settings can be modified using the `--max-containers`, `--min-containers`, `--buffer-containers`,
+    and `--scaledown-window` options.
+
+    If provided, Max Containers should be a positive integer, Min/Buffer Containers should be
+    nonnegative integers, and Scaledown window should be a positive integer measured in seconds.
+
+    Examples:
+
+    Update Max Containers for a deployed Function:
+
+    ```
+    modal function autoscaler update my-app/my-function --max-containers 10
+    ```
+
+    Update both Min and Buffer Containers for a Function by ID:
+
+    ```
+    modal function autoscaler update fu-1234 --min-containers 3 --buffer-containers 2
+    ```
+    """
+
+    environment_name = _get_environment_name(ensure_env(env))
+    client = await _Client.from_env()
+
+    updates: dict[str, int] = {}
+    for k, v in {
+        "min_containers": min_containers,
+        "max_containers": max_containers,
+        "buffer_containers": buffer_containers,
+        "scaledown_window": scaledown_window,
+    }.items():
+        if v is None:
+            continue
+
+        try:
+            updates[k] = parse_int(
+                v,
+                allow_negative=False,
+                allow_zero=k in {"min_containers", "buffer_containers"},
+            )
+        except ValueError as e:
+            option_name = f"--{k.replace('_', '-')}"
+            raise click.UsageError(f"Invalid input for {option_name!r}: {e}")
+
+    output_manager = OutputManager.get()
+    if not updates:
+        output_manager.print("No autoscaler settings specified.")
+        return
+
+    function_id, handle_metadata, _ = await _resolve_function_id(
+        client,
+        function_identifier,
+        environment_name,
+        object_type="Function",
+        command="autoscaler update",
+    )
+
+    if not handle_metadata.base_function_id and len(handle_metadata.class_parameter_info.schema) > 0:
+        raise ValueError(
+            f"`{function_identifier}` is a modal.Cls with parameters. Provide a specific "
+            "parameterization via a Function ID. See `modal function variants`."
+        )
+
+    f: _Function = _Function._new_hydrated(function_id, client, handle_metadata)
+    await f.update_autoscaler(**updates)
+
+    output_manager.print(f"[green]✓[/green] Updated autoscaler settings for Function {handle_metadata.function_name}")
+
+
 @function_cli.command("metrics", no_args_is_help=True)
 @click.argument("identifier", metavar="FUNCTION")
 @click.option("--since", help="Start time: ISO 8601 or relative duration (e.g. 2h). Naive times are local.")

modal/cli/server.py

@@ -9,6 +9,7 @@ from typing import AsyncGenerator, Sequence, cast
 
 import click
 from click import UsageError
+from rich.box import SIMPLE
 from rich.table import Column, Table
 from rich.text import Text
 
@@ -17,7 +18,7 @@ from modal._logs import _fetch_time_range, _seconds_to_timestamp, _timestamp_to_
 from modal._object import _get_environment_name
 from modal._server import _Server
 from modal._utils.async_utils import async_map_ordered, synchronizer
-from modal._utils.time_utils import parse_duration
+from modal._utils.time_utils import parse_duration, timestamp_to_localized_str
 from modal.cli.utils import humanize_filesize
 from modal.client import _Client
 from modal.exception import LogsFetchError, NotFoundError
@@ -51,6 +52,7 @@ from .utils import (
     display_table,
     env_option,
     grouped_utc_timestamp,
+    parse_int,
 )
 
 server_cli = ModalGroup(name="server", help="Inspect Modal Servers.")
@@ -671,8 +673,8 @@ def _render_inference(history: api_pb2.ServerGetTimeRangeStatsResponse, use_colo
 
 def _server_stats_time_range(since: str | None, until: str | None) -> tuple[datetime, datetime, timedelta]:
     now = datetime.now(timezone.utc)
-    until_dt = _parse_time_arg(until, default=now)
-    since_dt = _parse_time_arg(since, default=until_dt - _DEFAULT_STATS_WINDOW)
+    until_dt = _parse_time_arg(until, default=now, now=now)
+    since_dt = _parse_time_arg(since, default=until_dt - _DEFAULT_STATS_WINDOW, now=now)
     if since_dt >= until_dt:
         raise UsageError("--since must be before --until.")
 
@@ -1086,6 +1088,281 @@ async def requests(
     )
 
 
+autoscaler_cli = ModalGroup(name="autoscaler", help="View and Configure Autoscaler settings for Modal Servers.")
+server_cli.add_command(autoscaler_cli)
+
+
+@autoscaler_cli.command("settings", no_args_is_help=True)
+@click.argument("server_identifier", metavar="FUNCTION")
+@click.option("--json", "json", is_flag=True, default=False, help="Output as JSON.")
+@env_option
+@synchronizer.create_blocking
+async def autoscaler_info(server_identifier: str, json: bool = False, env: str | None = None):
+    """Show the current Autsocaling settings for the provided Server.
+
+    In addition to the current settings, this command also shows any active overrides to these
+    settings, along with metadata about who overrode the setting, and when. SERVER may be a
+    Server ID or a deployed Server name in the form ``APP_NAME/SERVER_NAME``.
+
+    If a setting's value is the default and not overridden, its value is omitted in the output.
+
+    Examples:
+
+    Show autoscaling settings for a deployed Server:
+
+    ```
+    modal server autoscaler settings my-app/my-server
+    ```
+
+    Show autoscaling settings using an ID:
+
+    ```
+    modal server autoscaler settings fu-1234
+    ```
+    """
+
+    environment_name = _get_environment_name(ensure_env(env))
+    client = await _Client.from_env()
+    function_id, _, _ = await _resolve_function_id(
+        client,
+        server_identifier,
+        environment_name,
+        object_type="Server",
+        command="autoscaler settings",
+    )
+
+    autoscaler_response = await client._stub.FunctionGetSchedulingParams(
+        api_pb2.FunctionGetSchedulingParamsRequest(function_id=function_id)
+    )
+
+    autoscaler_settings = ServerAutoscalerSettings._from_proto(autoscaler_response.autoscaler_configuration.settings)
+    override_events = autoscaler_response.autoscaler_configuration.override_events
+
+    output_manager = OutputManager.get()
+
+    if json:
+        current_settings = dataclasses.asdict(autoscaler_settings)
+        if current_settings["target_concurrency"] == 0:
+            current_settings["target_concurrency"] = None
+
+        override_events_json: list[dict[str, str]] = []
+        for k, v in override_events.items():
+            if k == "target_concurrency_float":
+                continue
+
+            if v.user_id:
+                obj = {
+                    "setting": k,
+                    "updated_at": str(v.timestamp),
+                    "actor_name": v.requested_by,
+                    "actor_id": v.user_id,
+                    "actor_type": "user",
+                }
+            elif v.service_user_id:
+                obj = {
+                    "setting": k,
+                    "updated_at": str(v.timestamp),
+                    "actor_name": v.requested_by,
+                    "actor_id": v.service_user_id,
+                    "actor_type": "service-user",
+                }
+            else:
+                obj = {
+                    "setting": k,
+                    "updated_at": str(v.timestamp),
+                    "actor_id": "unknown",
+                    "actor_name": "unknown",
+                    "actor_type": "unknown",
+                }
+
+            override_events_json.append(obj)
+
+        output_manager.print_json(
+            json_lib.dumps(
+                {
+                    "current_settings": current_settings,
+                    "override_events": override_events_json,
+                }
+            )
+        )
+
+        return
+
+    human_readable = {
+        "min_containers": "Min Containers",
+        "max_containers": "Max Containers",
+        "buffer_containers": "Buffer Containers",
+        "scaledown_window": "Scaledown Window",
+        "scaleup_window": "Scaleup Window",
+        "target_concurrency": "Target Concurrency",
+    }
+
+    if override_events:
+        t = Table("Setting", "Value", "Overridden By", box=SIMPLE)
+    else:
+        t = Table("Setting", "Value", box=SIMPLE)
+
+    for key, pretty in human_readable.items():
+        value = getattr(autoscaler_settings, key)
+        value_str = str(value)
+
+        override_meta = "-"
+        if key in override_events:
+            override = override_events[key]
+            override_meta = f"{override.requested_by} at {timestamp_to_localized_str(override.timestamp, isotz=False)}"
+
+        if key in {"scaledown_window", "scaleup_window"}:
+            value_str = f"{value} seconds"
+
+        if key == "target_concurrency":
+            value_str = f"{value} requests/container"
+
+        if not value and (key == "target_concurrency" or key not in override_events):
+            value_str = "-"
+
+        if override_events:
+            t.add_row(pretty, value_str, override_meta)
+        else:
+            t.add_row(pretty, value_str)
+
+    output_manager.print(t)
+
+
+@autoscaler_cli.command("update", no_args_is_help=True)
+@click.argument("server_identifier", metavar="SERVER")
+@click.option("--max-containers", "max_containers", default=None, help="Maximum concurrent containers.")
+@click.option("--min-containers", "min_containers", default=None, help="Minimum number of containers to keep running.")
+@click.option(
+    "--buffer-containers",
+    "buffer_containers",
+    default=None,
+    help="Extra containers to keep warm beyond current demand.",
+)
+@click.option(
+    "--scaledown-window",
+    "scaledown_window",
+    default=None,
+    help="Maximum duration (in seconds) idle containers wait before scaling down.",
+)
+@click.option(
+    "--scaleup-window",
+    "scaleup_window",
+    default=None,
+    help="Seconds of sustained demand required before scaling up new containers. ",
+)
+@click.option(
+    "--target-concurrency",
+    "target_concurrency",
+    default=None,
+    help="Target number of concurrent requests per container. May be fractional.",
+)
+@env_option
+@synchronizer.create_blocking
+async def autoscaler_update(
+    server_identifier: str,
+    max_containers: str | None = None,
+    min_containers: str | None = None,
+    buffer_containers: str | None = None,
+    scaledown_window: str | None = None,
+    scaleup_window: str | None = None,
+    target_concurrency: str | None = None,
+    env: str | None = None,
+):
+    """Update the current Autsocaling settings for the provided Server.
+
+    SERVER may be a Server ID or a deployed Server name in the form ``APP_NAME/SERVER_NAME``.
+
+    Settings can be modified using the `--max-containers`, `--min-containers`, `--buffer-containers`,
+    `--scaledown-window`, `--scaleup-window`, and `--target-concurrency` options.
+
+    If provided, Max Containers should be a positive integer, Min and Buffer Containers should be
+    nonnegative integers, Scaledown and Scaleup windows should be positive integers measured in seconds,
+    and Target Concurrency should either be a positive floating point number, or the string "none".
+
+    Examples:
+
+    Update Max Containers for a deployed Server:
+
+    ```
+    modal server autoscaler update my-app/my-server --max-containers 10
+    ```
+
+    Update both Min Containers and Target Concurrency for a Server by ID:
+
+    ```
+    modal server autoscaler update fu-1234 --min-containers 3 --target-concurrency 2.5
+    ```
+
+    Set Target Concurrency to "none" (disabling autoscaling for the Server)
+
+    ```
+    modal server autoscaler update my-app/my-server --target-concurrency none
+    ```
+    """
+
+    environment_name = _get_environment_name(ensure_env(env))
+    client = await _Client.from_env()
+
+    updates: dict[str, int | float] = {}
+    for k, v in {
+        "min_containers": min_containers,
+        "max_containers": max_containers,
+        "buffer_containers": buffer_containers,
+        "scaledown_window": scaledown_window,
+        "scaleup_window": scaleup_window,
+        "target_concurrency": target_concurrency,
+    }.items():
+        if v is None:
+            continue
+
+        if k == "target_concurrency":
+            error_message = (
+                f"Invalid input for '--target-concurrency': {v!r} must be a positive float or the string \"none\""
+            )
+
+            if v == "none":
+                updates[k] = 0
+                continue
+
+            try:
+                updates[k] = float(v)
+            except ValueError as e:
+                raise click.UsageError(error_message) from e
+
+            if updates[k] <= 0:
+                raise click.UsageError(error_message)
+
+            continue
+
+        try:
+            updates[k] = parse_int(
+                v,
+                allow_negative=False,
+                allow_zero=k in {"min_containers", "buffer_containers"},
+            )
+        except ValueError as e:
+            option_name = f"--{k.replace('_', '-')}"
+            raise click.UsageError(f"Invalid input for {option_name!r}: {e}")
+
+    output_manager = OutputManager.get()
+    if not updates:
+        output_manager.print("No autoscaler settings specified.")
+        return
+
+    function_id, handle_metadata, _ = await _resolve_function_id(
+        client,
+        server_identifier,
+        environment_name,
+        object_type="Server",
+        command="autoscaler update",
+    )
+
+    s = _Server._new_from_function(function_id, client, handle_metadata)
+    await s.update_autoscaler(**updates)  # type: ignore
+
+    output_manager.print(f"[green]✓[/green] Updated autoscaler settings for Server {handle_metadata.function_name}")
+
+
 @server_cli.command("metrics", no_args_is_help=True)
 @click.argument("identifier", metavar="SERVER")
 @click.option("--since", help="Start time: ISO 8601 or relative duration (e.g. 2h). Naive times are local.")