modal 1.6.2.dev7__py3-none-any.whl → 1.6.2.dev9__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/_workspace.py

@@ -9,6 +9,7 @@ from typing import Optional
 from google.protobuf.empty_pb2 import Empty
 
 from modal.exception import DeprecationError, InvalidError
+from modal.types import ServiceUserInfo
 from modal_proto import api_pb2
 
 from ._load_context import LoadContext
@@ -129,6 +130,15 @@ class _Workspace(_Object, type_prefix="ac"):
         """Namespace for Workspace settings APIs."""
         return _WorkspaceSettingsManager(self)
 
+    @property
+    def service_users(self) -> "_WorkspaceServiceUserManager":
+        """Namespace for managing Service Users in a Workspace.
+
+        See [the guide](https://modal.com/docs/guide/service-users) for more information about Service
+        Users.
+        """
+        return _WorkspaceServiceUserManager(self)
+
 
 class _WorkspaceProxyTokenManager:
     """mdmd:namespace"""
@@ -556,3 +566,169 @@ class _WorkspaceSettingsManager:
                 await self._set_default_environment(value)
             case _:
                 raise ValueError(f"Unknown setting {name!r}. Valid settings: {', '.join(self._valid_settings())}")
+
+
+class _WorkspaceServiceUserManager:
+    """mdmd:namespace"""
+
+    def __init__(self, workspace: _Workspace):
+        """mdmd:hidden"""
+        self._workspace = workspace
+
+    async def create(self, name: str, *, expires_in: int | None) -> TokenData:
+        """Create a new Service User in the current workspace.
+
+        To call this function, you are required to have Manager permissions in the Workspace.
+
+        Args:
+            name: The name of the new Service User. Must consistent only of alphanumeric, '-', or '_'
+                characters.
+            expires_in: An expiration time, in seconds, after which the token will stop working. If
+                `None`, the token will never expire.
+
+        Returns:
+            A `TokenData` dataclass containing the credentials for the Service User. Note that this
+            is the only time you will be able to view these credentials.
+
+        Examples:
+
+        ```python notest
+        ws = modal.Workspace.from_context()
+
+        # Creates a Service User named "test-service-user", whose credentials expire after one year.
+        service_user_token_data = ws.service_users.create(
+            "test-service-user",
+            expires_in=datetime.timedelta(days=365).total_seconds(),
+        )
+        ```
+        """
+        if not self._workspace._is_hydrated:
+            await self._workspace.hydrate()
+
+        if expires_in is None:
+            req = api_pb2.ServiceUserCreateRequest(name=name)
+        else:
+            req = api_pb2.ServiceUserCreateRequest(name=name, expires_in_seconds=expires_in)
+
+        resp = await self._workspace.client._stub.ServiceUserCreate(req)
+
+        return TokenData(token_id=resp.token_id, token_secret=resp.token_secret)
+
+    async def set_role(
+        self,
+        service_user_name: str,
+        environment_name: str,
+        *,
+        role: str,
+    ) -> None:
+        """Set the role of a specified Service User within an Environment.
+
+        To call this function, you are required to have Manager permissions in the Workspace.
+
+        Args:
+            service_user_name: The name of the Service User.
+            environment_name: The name of the Environment to which the Service User's new role will
+                apply.
+            role: The access level to grant this Service User. Must be one of the strings `"no-access"`,
+                `"viewer"`, or `"contributor"`.
+
+        Examples:
+
+        ```python notest
+        ws = modal.Workspace.from_context()
+        # Grants Service User "test-service-user" the Viewer role in Environment "production"
+        ws.service_users.set_role("test-service-user", "production", role="viewer")
+
+        # Revokes access to "production" from Service User "test-service-user"
+        ws.service_users.set_role("test-service-user", "production", role="no-access")
+        ```
+        """
+
+        if not self._workspace._is_hydrated:
+            await self._workspace.hydrate()
+
+        from ._environments import _Environment
+
+        env = _Environment.from_name(environment_name, client=self._workspace.client)
+        await env.hydrate()
+
+        await self._workspace.client._stub.EnvironmentRoleSet(
+            api_pb2.EnvironmentRoleSetRequest(
+                service_user_name=service_user_name,
+                environment_id=env.object_id,
+                role_str=role,
+            )
+        )
+
+    async def info(self, name: str) -> ServiceUserInfo:
+        """Get information about a specific Service User.
+
+        To call this function, you are required to have Manager permissions in the Workspace.
+
+        Args:
+            name: The name of the Service User to introspect.
+
+        Returns:
+            A `ServiceUserInfo` dataclass containing information about the Service User.
+
+        Examples:
+
+        ```python notest
+        ws = modal.Workspace.from_context()
+        service_user = ws.service_users.info("test-service-user")
+        ```
+        """
+
+        if not self._workspace._is_hydrated:
+            await self._workspace.hydrate()
+
+        resp = await self._workspace.client._stub.ServiceUserInfo(
+            api_pb2.ServiceUserInfoRequest(service_user_name=name)
+        )
+
+        return ServiceUserInfo._from_proto(resp.service_user)
+
+    async def list(self) -> list[ServiceUserInfo]:
+        """List all Service Users in the current workspace.
+
+        To call this function, you are required to have Manager permissions in the Workspace.
+
+        Returns:
+            A list of `ServiceUserInfo` dataclasses.
+
+        Examples:
+
+        ```python notest
+        ws = modal.Workspace.from_context()
+        for service_user in ws.service_users.list():
+            print(service_user.name)
+        ```
+        """
+
+        if not self._workspace._is_hydrated:
+            await self._workspace.hydrate()
+
+        resp = await self._workspace.client._stub.ServiceUserList(Empty())
+
+        return [ServiceUserInfo._from_proto(su) for su in resp.service_users]
+
+    async def delete(self, name: str) -> None:
+        """Permanently delete a Service User.
+
+        To call this function, you are required to have Manager permissions in the Workspace.
+
+        Args:
+            name: The name of the Service User to delete.
+
+        Examples:
+
+        ```python notest
+        ws = modal.Workspace.from_context()
+        ws.service_users.delete("test-service-user")
+        ```
+        """
+
+        if not self._workspace._is_hydrated:
+            await self._workspace.hydrate()
+
+        await self._workspace.client._stub.ServiceUserDelete(api_pb2.ServiceUserDeleteRequest(service_user_name=name))

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/import_refs.py

@@ -7,11 +7,14 @@ or the app lookup of `modal deploy some_file.py`.
 These functions are only called by the Modal CLI, not in tasks.
 """
 
+import atexit
 import dataclasses
 import importlib
 import importlib.util
 import inspect
+import shutil
 import sys
+import tempfile
 import typing
 from collections import defaultdict
 from dataclasses import dataclass
@@ -60,15 +63,40 @@ def parse_import_ref(object_ref: str, use_module_mode: bool = False, command: st
 
 DEFAULT_APP_NAME = "app"
 
+STDIN_REF = "-"
+STDIN_MODULE_NAME = "modal_stdin_app"
 
-def import_file_or_module(import_ref: ImportRef, base_cmd: str = ""):
+
+def _write_stdin_script() -> str:
+    if sys.stdin is None or sys.stdin.isatty():
+        raise InvalidError("No script was piped on stdin. Usage: `cat my_app.py | modal run -`")
+    source = sys.stdin.read()
+    # The file must outlive the import: the entrypoint mount is built from it when the App runs.
+    tmp_dir = tempfile.mkdtemp(prefix="modal-stdin-")
+    atexit.register(shutil.rmtree, tmp_dir, ignore_errors=True)
+    script_path = Path(tmp_dir) / f"{STDIN_MODULE_NAME}.py"
+    script_path.write_text(source)
+    return str(script_path)
+
+
+def import_file_or_module(import_ref: ImportRef, base_cmd: str = "", allow_stdin: bool = False):
     if "" not in sys.path:
         # When running from a CLI like `modal run`
         # the current working directory isn't added to sys.path
         # so we add it in order to make module path specification possible
         sys.path.insert(0, "")  # "" means the current working directory
 
-    if not import_ref.file_or_module.endswith(".py") or import_ref.use_module_mode:
+    from_stdin = import_ref.file_or_module == STDIN_REF
+    if from_stdin:
+        if not allow_stdin:
+            raise InvalidError(f"`{base_cmd}` does not support reading a script from stdin.")
+        if import_ref.use_module_mode:
+            raise InvalidError("Reading a script from stdin (`-`) can't be combined with the -m flag.")
+        script_path = _write_stdin_script()
+    else:
+        script_path = import_ref.file_or_module
+
+    if not script_path.endswith(".py") or import_ref.use_module_mode:
         if not import_ref.use_module_mode:
             raise InvalidError(
                 "Python module paths must be specified with the -m flag. "
@@ -82,7 +110,7 @@ def import_file_or_module(import_ref: ImportRef, base_cmd: str = ""):
     else:
         # when using a script path, that scripts directory should also be on the path as it is
         # with `python some/script.py`
-        full_path = Path(import_ref.file_or_module).resolve()
+        full_path = Path(script_path).resolve()
         if "." in full_path.name.removesuffix(".py"):
             raise InvalidError(
                 f"Invalid Modal source filename: {full_path.name!r}."
@@ -90,10 +118,10 @@ def import_file_or_module(import_ref: ImportRef, base_cmd: str = ""):
             )
         sys.path.insert(0, str(full_path.parent))
 
-        module_name = inspect.getmodulename(import_ref.file_or_module)
+        module_name = inspect.getmodulename(script_path)
         assert module_name is not None
         # Import the module - see https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly
-        spec = importlib.util.spec_from_file_location(module_name, import_ref.file_or_module)
+        spec = importlib.util.spec_from_file_location(module_name, script_path)
         assert spec is not None
         module = importlib.util.module_from_spec(spec)
         sys.modules[module_name] = module
@@ -103,7 +131,7 @@ def import_file_or_module(import_ref: ImportRef, base_cmd: str = ""):
                 spec.loader.exec_module(module)
         except Exception as exc:
             if isinstance(exc, ImportError) and "attempted relative import with no known parent package" in str(exc):
-                if import_ref.file_or_module and import_ref.command and not import_ref.use_module_mode:
+                if import_ref.command and not import_ref.use_module_mode and not from_stdin:
                     file_path = Path(import_ref.file_or_module)
                     suggested_module_path = ".".join(file_path.parts).removesuffix(".py").lstrip(".")
                     suffix = f"::{import_ref.object_path}" if import_ref.object_path else ""
@@ -356,6 +384,7 @@ def import_and_filter(
     accept_local_entrypoint=True,
     accept_webhook=False,
     accept_service_functions=False,
+    allow_stdin=False,
 ) -> tuple[Runnable | None, list[CLICommand]]:
     """Takes a function ref string and returns a single determined "runnable" to use, and a list of all available
     runnables.
@@ -371,7 +400,7 @@ def import_and_filter(
     3. if there is a single method (within a class) that one is used
     """
     # all commands:
-    module = import_file_or_module(import_ref, base_cmd)
+    module = import_file_or_module(import_ref, base_cmd, allow_stdin=allow_stdin)
     cli_commands = list_cli_commands(
         dict(inspect.getmembers(module)),
         include_service_functions=accept_service_functions,