modal 1.5.6.dev22__tar.gz → 1.5.6.dev23__tar.gz

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

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

{modal-1.5.6.dev22 → modal-1.5.6.dev23}/modal/_function_variants.py

@@ -4,12 +4,15 @@ from collections.abc import Collection, Sequence, Sized
 from pathlib import PurePosixPath
 from typing import TYPE_CHECKING, Any
 
+import google.protobuf.message
+
 from modal.types import CloudBucketMountInfo, FunctionInfo, VolumeMountInfo
 from modal_proto import api_pb2
 
 from ._resources import convert_fn_config_to_resources_config
 from ._serialization import (
     apply_defaults,
+    deserialize_proto_params,
     serialize,
     serialize_proto_params,
     validate_parameter_values,
@@ -17,11 +20,14 @@ from ._serialization import (
 from ._utils.function_utils import _parse_retries
 from ._utils.mount_utils import validate_volumes, validate_volumes_by_object_id
 from .cloud_bucket_mount import _CloudBucketMount, cloud_bucket_mounts_to_proto
+from .exception import InvalidError
 from .retries import Retries
 from .secret import _Secret
 from .volume import _Volume, _volume_to_mount_proto
 
 if TYPE_CHECKING:
+    from modal.client import _Client
+
     from ._functions import _Function
     from ._load_context import LoadContext
     from ._object import _Object
@@ -190,6 +196,157 @@ class _FunctionOptions:
         )
 
 
+@dataclasses.dataclass(frozen=True)
+class _FunctionOptionsInfo:
+    """Configuration overrides applied to a Function variant.
+
+    Fields are named after the parameters of the builder methods that set them: `.with_options()`,
+    `.with_concurrency()` (`max_inputs`, `target_inputs`), and `.with_batching()` (`max_batch_size`,
+    `wait_ms`). Fields are None when the variant does not override that setting.
+    """
+
+    cpu: float | tuple[float, float] | None = None
+    memory: int | tuple[int, int] | None = None
+    gpu: str | None = None
+    secrets: list[str] | None = None
+    volumes: dict[str, VolumeMountInfo] | None = None  # mount path -> volume and its mount options
+    cloud_bucket_mounts: dict[str, CloudBucketMountInfo] | None = None  # mount path -> bucket mount
+    retries: Retries | None = None
+    max_containers: int | None = None
+    buffer_containers: int | None = None
+    scaledown_window: int | None = None
+    timeout: int | None = None
+    region: str | list[str] | None = None
+    cloud: str | None = None
+    routing_region: str | None = None
+    max_inputs: int | None = None
+    target_inputs: int | None = None
+    max_batch_size: int | None = None
+    wait_ms: int | None = None
+
+    @classmethod
+    def _from_proto(cls, proto: api_pb2.FunctionOptions) -> "_FunctionOptionsInfo":
+        cpu: float | tuple[float, float] | None = None
+        memory: int | tuple[int, int] | None = None
+        gpu: str | None = None
+        if proto.HasField("resources"):
+            resources = proto.resources
+            if resources.milli_cpu_max > 0:
+                cpu = (resources.milli_cpu / 1000, resources.milli_cpu_max / 1000)
+            elif resources.milli_cpu > 0:
+                cpu = resources.milli_cpu / 1000
+
+            if resources.memory_mb_max > 0:
+                memory = (resources.memory_mb, resources.memory_mb_max)
+            elif resources.memory_mb > 0:
+                memory = resources.memory_mb
+
+            if resources.gpu_config.count > 0:
+                gpu_config = resources.gpu_config
+                gpu = gpu_config.gpu_type if gpu_config.count == 1 else f"{gpu_config.gpu_type}:{gpu_config.count}"
+
+        retries: Retries | None = None
+        if proto.HasField("retry_policy"):
+            retry_policy = proto.retry_policy
+            retries = Retries(
+                max_retries=retry_policy.retries,
+                backoff_coefficient=retry_policy.backoff_coefficient or 2.0,
+                initial_delay=retry_policy.initial_delay_ms / 1000,
+                max_delay=retry_policy.max_delay_ms / 1000 or 60.0,
+            )
+
+        region: str | list[str] | None = None
+        if proto.HasField("scheduler_placement") and proto.scheduler_placement.regions:
+            region = list(proto.scheduler_placement.regions)
+
+        return cls(
+            cpu=cpu,
+            memory=memory,
+            gpu=gpu,
+            secrets=list(proto.secret_ids) or None,
+            volumes={
+                vm.mount_path: VolumeMountInfo(
+                    name=None,  # The mount records which Volume, not what it was called.
+                    volume_id=vm.volume_id,
+                    read_only=vm.read_only,
+                    sub_path=vm.sub_path if vm.HasField("sub_path") else None,
+                )
+                for vm in proto.volume_mounts
+            }
+            or None,
+            cloud_bucket_mounts={
+                cbm.mount_path: CloudBucketMountInfo._from_proto(cbm) for cbm in proto.cloud_bucket_mounts
+            }
+            or None,
+            retries=retries,
+            max_containers=proto.concurrency_limit if proto.HasField("concurrency_limit") else None,
+            buffer_containers=proto.buffer_containers if proto.HasField("buffer_containers") else None,
+            scaledown_window=proto.task_idle_timeout_secs if proto.HasField("task_idle_timeout_secs") else None,
+            timeout=proto.timeout_secs if proto.HasField("timeout_secs") else None,
+            region=region,
+            cloud=proto.cloud_provider_str if proto.HasField("cloud_provider_str") else None,
+            routing_region=proto.routing_region if proto.HasField("routing_region") else None,
+            max_inputs=proto.max_concurrent_inputs if proto.HasField("max_concurrent_inputs") else None,
+            target_inputs=proto.target_concurrent_inputs if proto.HasField("target_concurrent_inputs") else None,
+            max_batch_size=proto.batch_max_size if proto.HasField("batch_max_size") else None,
+            wait_ms=proto.batch_linger_ms if proto.HasField("batch_linger_ms") else None,
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class _FunctionVariantInfo:
+    """Information about a variant of a Function, created by parametrization or `.with_options()`."""
+
+    function_id: str
+    parameters: dict[str, str | int | bytes | bool] | None  # None when the parameters can't be decoded
+    options: _FunctionOptionsInfo | None
+
+    @classmethod
+    def _from_proto(cls, proto: api_pb2.FunctionVariantInfo) -> "_FunctionVariantInfo":
+        parameters: dict[str, str | int | bytes | bool] | None
+        try:
+            parameters = deserialize_proto_params(proto.serialized_params)
+        except (google.protobuf.message.DecodeError, InvalidError):
+            parameters = None
+
+        return cls(
+            function_id=proto.function_id,
+            parameters=parameters,
+            options=_FunctionOptionsInfo._from_proto(proto.function_options)
+            if proto.HasField("function_options")
+            else None,
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class _FunctionVariantListing:
+    """The variants of a Function, and how the server chose to order them."""
+
+    variants: list[_FunctionVariantInfo]
+    # True when the variants are ordered by how many tasks each is running, busiest first.
+    ordered_by_task_count: bool
+
+
+async def _list_function_variants(
+    client: "_Client", function_id: str, *, limit: int | None = None
+) -> _FunctionVariantListing:
+    variants: list[_FunctionVariantInfo] = []
+    ordered_by_task_count = False
+    cursor = None
+    while True:
+        request = api_pb2.FunctionListVariantsRequest(function_id=function_id, cursor=cursor, limit=limit or 0)
+        response = await client.stub.FunctionListVariants(request)
+        # An ordered listing arrives as a single response, so there is nothing to reconcile across
+        # pages: every response of a multi-page listing reports itself unordered.
+        ordered_by_task_count = response.ordered_by_task_count
+        variants.extend(_FunctionVariantInfo._from_proto(info) for info in response.infos)
+        if limit is not None and len(variants) >= limit:
+            return _FunctionVariantListing(variants[:limit], ordered_by_task_count)
+        if not response.HasField("next_cursor"):
+            return _FunctionVariantListing(variants, ordered_by_task_count)
+        cursor = response.next_cursor
+
+
 async def _function_bind_params_cached(
     base_function: "_Function",
     req: api_pb2.FunctionBindParamsRequest,

{modal-1.5.6.dev22 → modal-1.5.6.dev23}/modal/cli/function.py

@@ -1,18 +1,23 @@
 # Copyright Modal Labs 2026
+import dataclasses
 import json as json_lib
 from datetime import datetime, timedelta, timezone
-from typing import cast
+from typing import Any, cast
 
 import click
 from click import UsageError
+from rich.table import Column
 from rich.text import Text
 
 from modal._environments import ensure_env
+from modal._function_variants import _FunctionOptionsInfo, _list_function_variants
 from modal._object import _get_environment_name
 from modal._utils.async_utils import synchronizer
 from modal._utils.time_utils import parse_duration
 from modal.client import _Client
 from modal.output import OutputManager
+from modal.retries import Retries
+from modal.types import CloudBucketMountInfo, VolumeMountInfo
 from modal_proto import api_pb2
 
 from ._help import ModalGroup
@@ -32,7 +37,7 @@ from ._stats import (
     stats_style,
     success_style,
 )
-from .utils import _resolve_function_id, env_option
+from .utils import _resolve_function_id, display_table, env_option, humanize_filesize
 
 function_cli = ModalGroup(name="function", help="Inspect Modal Functions.")
 
@@ -406,6 +411,7 @@ async def logs(
     function_id, metadata = await _resolve_function_id(
         client, function_ref, env, object_type="Function", command="logs"
     )
+    app_id = metadata.app_id
 
     prefix_fields: list[str] = []
     if show_function_id:
@@ -430,3 +436,206 @@ async def logs(
         timestamps=timestamps,
         prefix_fields=prefix_fields,
     )
+
+
+def _overridden_options(options: _FunctionOptionsInfo | None) -> list[tuple[str, Any]]:
+    """Return the settings a variant overrides, keyed by the builder-method parameter name."""
+    if options is None:
+        return []
+    fields = ((field.name, getattr(options, field.name)) for field in dataclasses.fields(options))
+    return [(name, value) for name, value in fields if value is not None]
+
+
+def _variant_overrides_json(options: _FunctionOptionsInfo | None) -> dict[str, Any]:
+    """Return the overridden settings in a form that can be serialized as JSON."""
+    overrides: dict[str, Any] = {}
+    for name, value in _overridden_options(options):
+        if isinstance(value, Retries):
+            value = {
+                "max_retries": value.max_retries,
+                "backoff_coefficient": value.backoff_coefficient,
+                "initial_delay": value.initial_delay.total_seconds(),
+                "max_delay": value.max_delay.total_seconds(),
+            }
+        elif isinstance(value, tuple):
+            value = list(value)
+        elif name in ("cloud_bucket_mounts", "volumes"):
+            value = {path: dataclasses.asdict(mount) for path, mount in value.items()}
+        overrides[name] = value
+    return overrides
+
+
+def _format_bucket_mount(mount: CloudBucketMountInfo) -> str:
+    """Render a cloud bucket mount as a URI, which is the part that identifies it at a glance."""
+    uri = f"{mount.bucket_type}://{mount.bucket_name}"
+    if mount.key_prefix:
+        uri = f"{uri}/{mount.key_prefix}"
+    return f"{uri} (ro)" if mount.read_only else uri
+
+
+def _format_volume_mount(mount: VolumeMountInfo) -> str:
+    """Render a volume mount as its ID plus whatever `.with_mount_options()` changed about it."""
+    volume = mount.volume_id or mount.name or ""
+    if mount.sub_path:
+        volume = f"{volume}:{mount.sub_path}"
+    return f"{volume} (ro)" if mount.read_only else volume
+
+
+def _format_override(value: Any) -> str:
+    if isinstance(value, dict):
+        return "{" + ", ".join(f"{k}: {_format_override(v)}" for k, v in value.items()) + "}"
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(_format_override(v) for v in value) + "]"
+    return str(value)
+
+
+def _variant_cell(text: str, style: str = "") -> Text:
+    """Render one table cell that is truncated rather than wrapped, so one variant stays in one row."""
+    return Text(text, style=style, no_wrap=True, overflow="ellipsis")
+
+
+def _format_parameter(value: Any) -> str:
+    if isinstance(value, bytes):
+        # A bytes parameter is an opaque payload; its size is the only part that reads well in a table.
+        return f"<bytes: {humanize_filesize(len(value))}>"
+    return repr(value)
+
+
+def _parameters_cell(parameters: dict[str, Any] | None) -> Text:
+    if parameters is None:
+        return _variant_cell("unavailable", style="dim")
+    return _variant_cell(", ".join(f"{name}={_format_parameter(value)}" for name, value in parameters.items()))
+
+
+def _options_cell(options: _FunctionOptionsInfo | None) -> Text:
+    parts = []
+    for name, value in _overridden_options(options):
+        if isinstance(value, Retries):
+            # The retry count is the useful part of a retry policy at a glance.
+            value = value.max_retries
+        elif name == "cloud_bucket_mounts":
+            value = {path: _format_bucket_mount(mount) for path, mount in value.items()}
+        elif name == "volumes":
+            value = {path: _format_volume_mount(mount) for path, mount in value.items()}
+        parts.append(f"{name}={_format_override(value)}")
+    return _variant_cell(", ".join(parts))
+
+
+@function_cli.command("variants", no_args_is_help=True)
+@click.argument("function_ref", metavar="FUNCTION")
+@click.option(
+    "-n",
+    "--limit",
+    "limit",
+    default=200,
+    show_default=True,
+    type=int,
+    help="Show at most N variants, those running the most containers first. Use 0 to list every variant, newest first.",
+)
+@click.option("--json", "json", is_flag=True, default=False, help="Output as JSON.")
+@env_option
+@synchronizer.create_blocking
+async def variants(
+    function_ref: str,
+    limit: int = 200,
+    json: bool = False,
+    env: str | None = None,
+):
+    """List the variants of a modal Function.
+
+    Variants are the parameterized instances of a `modal.Cls` and the Functions created with
+    `.with_options()`. FUNCTION may be a Function ID or a deployed Function name in the form
+    ``APP_NAME/FUNCTION_NAME``.
+
+    By default, the busiest variants are listed first. If you ask for more variants than can be
+    ranked, or for all of them, they are listed newest first instead.
+
+    Examples:
+
+    List the busiest variants of a deployed Function:
+
+    ```
+    modal function variants my-app/my-function
+    ```
+
+    List the parameterized instances of a deployed `modal.Cls`:
+
+    ```
+    modal function variants 'my-app/MyClass.*'
+    ```
+
+    Show only the ten busiest variants:
+
+    ```
+    modal function variants my-app/my-function --limit 10
+    ```
+
+    List every variant of a Function ID as JSON:
+
+    ```
+    modal function variants fu-abc123 --limit 0 --json
+    ```
+    """
+    if limit < 0:
+        raise UsageError("--limit cannot be negative.")
+
+    environment_name = _get_environment_name(ensure_env(env))
+    client = await _Client.from_env()
+    function_id, handle_metadata = await _resolve_function_id(
+        client,
+        function_ref,
+        environment_name,
+        command="variants",
+    )
+    # A variant has no variants of its own, so resolving one lists the family it belongs to.
+    base_function_id = handle_metadata.base_function_id or function_id
+    effective_limit = limit or None
+    listing = await _list_function_variants(client, base_function_id, limit=effective_limit)
+    function_variants = listing.variants
+    show_parameters = bool(handle_metadata.method_handle_metadata)
+
+    output = OutputManager.get()
+    if json:
+        payload: list[dict[str, Any]] = []
+        for variant in function_variants:
+            entry: dict[str, Any] = {"function_id": variant.function_id}
+            if show_parameters:
+                entry["parameters"] = variant.parameters
+            entry["options"] = _variant_overrides_json(variant.options)
+            payload.append(entry)
+        # Parameter values may include bytes, which have no JSON representation of their own.
+        output.print_json(json_lib.dumps(payload, default=repr))
+        return
+
+    if not function_variants:
+        output.print(f"No variants found for {base_function_id}.")
+        return
+
+    rows: list[list[Text | str | None]] = []
+    for variant in function_variants:
+        options_cell = _options_cell(variant.options)
+        if show_parameters:
+            rows.append(
+                [
+                    variant.function_id,
+                    _parameters_cell(variant.parameters),
+                    options_cell,
+                ]
+            )
+        else:
+            rows.append([variant.function_id, options_cell])
+
+    id_column = Column("Function ID", no_wrap=True)
+    columns = (
+        [id_column, Column("Parameters"), Column("Options")] if show_parameters else [id_column, Column("Options")]
+    )
+    ordering = f"{len(rows)} busiest" if listing.ordered_by_task_count else f"{len(rows)} newest"
+    display_table(columns, rows, title=f"Variants of {base_function_id} · {ordering}")
+
+    if effective_limit is not None and len(function_variants) == effective_limit:
+        output.print(
+            Text(
+                f"Showing {effective_limit} variants; use --limit 0 to list every variant.",
+                style="dim",
+            )
+        )

{modal-1.5.6.dev22 → modal-1.5.6.dev23}/modal/cli/utils.py

@@ -132,6 +132,18 @@ async def _fetch_app_logs(
     await _drain_batches(output_mgr, batches, prefix_fields or [], filters.search_text)
 
 
+def humanize_filesize(value: int) -> str:
+    if value < 0:
+        raise ValueError("value should be >= 0")
+    base = 1024
+    size = float(value)
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB"):
+        if size < base:
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= base
+    return f"{size:.1f} ZiB"
+
+
 def _plain(text: "Text | str | bool | None") -> "str | bool | None":
     return text.plain if isinstance(text, Text) else text
 
@@ -216,7 +228,7 @@ async def _resolve_function_id(
     environment_name: str,
     *,
     object_type: Literal["Function", "Server"] = "Function",
-    command: Literal["logs", "stats"],
+    command: Literal["logs", "stats", "variants"],
 ) -> tuple[str, api_pb2.FunctionHandleMetadata]:
     identifier_label = object_type.upper()
     usage = (

{modal-1.5.6.dev22 → modal-1.5.6.dev23}/modal/cli/volume.py

@@ -13,7 +13,7 @@ from modal._utils.async_utils import synchronizer
 from modal._utils.browser_utils import open_url_and_display
 from modal._utils.time_utils import timestamp_to_localized_str
 from modal.cli._download import _volume_download
-from modal.cli.utils import display_table, env_option, yes_option
+from modal.cli.utils import display_table, env_option, humanize_filesize, yes_option
 from modal.output import OutputManager
 from modal.volume import _AbstractVolumeUploadContextManager, _Volume
 from modal_proto import api_pb2
@@ -30,18 +30,6 @@ volume_cli = ModalGroup(
 )
 
 
-def humanize_filesize(value: int) -> str:
-    if value < 0:
-        raise ValueError("value should be >= 0")
-    base = 1024
-    size = float(value)
-    for unit in ("B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB"):
-        if size < base:
-            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
-        size /= base
-    return f"{size:.1f} ZiB"
-
-
 @volume_cli.command("create", help="Create a named, persistent modal.Volume.", panel="Management", no_args_is_help=True)
 @click.argument("name")
 @env_option

{modal-1.5.6.dev22 → modal-1.5.6.dev23}/modal/client.pyi

@@ -77,7 +77,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.5.6.dev22",
+        version: str = "1.5.6.dev23",
         *,
         oauth_credentials: typing.Optional[_OAuthCredentials] = None,
     ):
@@ -277,7 +277,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.5.6.dev22",
+        version: str = "1.5.6.dev23",
         *,
         oauth_credentials: typing.Optional[_OAuthCredentials] = None,
     ):

{modal-1.5.6.dev22 → modal-1.5.6.dev23}/modal/functions.pyi

@@ -653,7 +653,7 @@ class Function(
 
     _call_generator: ___call_generator_spec
 
-    class __remote_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class __remote_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> ReturnType_INNER:
             """Calls the function remotely, executing it with the given arguments and returning the execution's result.
 
@@ -678,7 +678,7 @@ class Function(
             """
             ...
 
-    remote: __remote_spec[modal._functions.P, modal._functions.ReturnType]
+    remote: __remote_spec[modal._functions.ReturnType, modal._functions.P]
 
     class __remote_gen_spec(typing_extensions.Protocol):
         def __call__(self, /, *args, **kwargs) -> typing.Generator[typing.Any, None, None]:
@@ -728,7 +728,7 @@ class Function(
         """
         ...
 
-    class ___experimental_spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class ___experimental_spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """[Experimental] Calls the function with the given arguments, without waiting for the results.
 
@@ -761,7 +761,7 @@ class Function(
             """
             ...
 
-    _experimental_spawn: ___experimental_spawn_spec[modal._functions.P, modal._functions.ReturnType]
+    _experimental_spawn: ___experimental_spawn_spec[modal._functions.ReturnType, modal._functions.P]
 
     class ___spawn_map_inner_spec(typing_extensions.Protocol[P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> None: ...
@@ -769,7 +769,7 @@ class Function(
 
     _spawn_map_inner: ___spawn_map_inner_spec[modal._functions.P]
 
-    class __spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class __spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """Calls the function with the given arguments, without waiting for the results.
 
@@ -802,7 +802,7 @@ class Function(
             """
             ...
 
-    spawn: __spawn_spec[modal._functions.P, modal._functions.ReturnType]
+    spawn: __spawn_spec[modal._functions.ReturnType, modal._functions.P]
 
     def get_raw_f(self) -> collections.abc.Callable[..., typing.Any]:
         """Return the inner Python object wrapped by this Modal Function.

{modal-1.5.6.dev22 → modal-1.5.6.dev23}/modal.egg-info/PKG-INFO

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

{modal-1.5.6.dev22 → modal-1.5.6.dev23}/modal_version/__init__.py

@@ -1,4 +1,4 @@
 # Copyright Modal Labs 2026
 """Supplies the current version of the modal client library."""
 
-__version__ = "1.5.6.dev22"
+__version__ = "1.5.6.dev23"