modal 1.5.1.dev14__tar.gz → 1.5.2__tar.gz

{modal-1.5.1.dev14 → modal-1.5.2}/PKG-INFO

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

{modal-1.5.1.dev14 → modal-1.5.2}/modal/__init__.py

@@ -9,7 +9,7 @@ if sys.version_info[:2] >= (3, 15):
 from modal_version import __version__
 
 try:
-    from . import billing
+    from . import billing, types
     from ._runtime.execution_context import current_function_call_id, current_input_id, interact, is_local
     from ._tunnel import Tunnel, forward
     from .app import App
@@ -100,6 +100,7 @@ __all__ = [
     "interact",
     "method",
     "parameter",
+    "types",
     "web_endpoint",
     "web_server",
     "wsgi_app",

modal-1.5.2/modal/_billing.py

@@ -0,0 +1,83 @@
+# Copyright Modal Labs 2025
+from datetime import datetime
+from decimal import Decimal
+from typing import TypedDict
+
+from ._utils.deprecation import deprecation_warning
+from .client import _Client
+
+
+class WorkspaceBillingReportItem(TypedDict):
+    object_id: str
+    description: str
+    environment_name: str
+    interval_start: datetime
+    cost: Decimal
+    tags: dict[str, str]
+
+
+async def _workspace_billing_report(
+    *,
+    start: datetime,  # Start of the report, inclusive
+    end: datetime | None = None,  # End of the report, exclusive
+    resolution: str = "d",  # Resolution, e.g. "d" for daily or "h" for hourly
+    tag_names: list[str] | None = None,  # Optional additional metadata to include
+    client: _Client | None = None,
+) -> list[WorkspaceBillingReportItem]:
+    """Generate a tabular report of workspace usage by object and time.
+
+    The result will be a list of dictionaries for each interval (determined by `resolution`)
+    between the `start` and `end` limits. The dictionary represents a single Modal object
+    that billing can be attributed to (e.g., an App) along with metadata (including user-defined
+    tags) for identifying that object. The dictionary also contains a breakdown of the cost value
+    attributed to individual resources (for an App, this can be CPU, Memory, specific GPU types,
+    etc.). The specific resource types included in the breakdown are subject to change as
+    Modal's billing model evolves.
+
+    The `start` and `end` parameters are required to either have a UTC timezone or to be
+    timezone-naive (which will be interpreted as UTC times). The timestamps in the result will
+    be in UTC. Cost will be reported for full intervals, even if the provided `start` or `end`
+    parameters are partial: `start` will be rounded to the beginning of its interval, while
+    partial `end` intervals will be excluded.
+
+    Additional user-provided metadata can be included in the report if the objects have tags
+    and `tag_names` (i.e., keys) are specified in the request. Alternatively, pass `tag_names=["*"]`
+    to include all tags in the report. Note that tags will be attributed to the entire interval even
+    if they were added or removed at some point within it. If the tag name was not in use during an
+    interval, it will be absent from the tags dictionary in that output row.
+
+    It's also possible to generate reports using the
+    [`modal billing report`](https://modal.com/docs/cli/latest/billing) CLI command. The CLI
+    has a few convenience features for generating reports across relative time ranges.
+
+    """
+
+    deprecation_warning(
+        (2026, 6, 18),
+        "The `modal.billing.workspace_billing_report()` function is deprecated. "
+        "Use the `workspace.billing.report()` method on the `modal.Workspace` object instead.",
+    )
+
+    from ._workspace import _Workspace
+
+    data = await _Workspace.from_context(client=client).billing.report(
+        start=start,
+        end=end,
+        resolution=resolution,
+        tag_names=tag_names,
+    )
+
+    res: list[WorkspaceBillingReportItem] = []
+    for datum in data:
+        item: WorkspaceBillingReportItem = {
+            "object_id": datum.object_id,
+            "description": datum.description,
+            "environment_name": datum.environment_name,
+            "interval_start": datum.interval_start,
+            "cost": Decimal(datum.cost),
+            "tags": dict(datum.tags),
+        }
+
+        res.append(item)
+
+    return res

{modal-1.5.1.dev14 → modal-1.5.2}/modal/_environments.py

@@ -13,7 +13,6 @@ from synchronicity import classproperty
 
 from modal_proto import api_pb2
 
-from ._billing import BILLING_DOCSTRING, BillingReportItem
 from ._load_context import LoadContext
 from ._object import _Object
 from ._resolver import Resolver
@@ -21,6 +20,7 @@ from ._utils.name_utils import check_environment_name
 from .client import _Client
 from .config import config, logger
 from .exception import InvalidError, WorkspaceManagementError
+from .types import BillingReportItem
 
 
 @dataclass(frozen=True)
@@ -103,9 +103,6 @@ class _EnvironmentManager:
         await client.stub.EnvironmentDelete(api_pb2.EnvironmentDeleteRequest(name=name))
 
 
-MemberRole = Literal["viewer", "contributor"]
-
-
 def _role_to_proto(role: str) -> "api_pb2.EnvironmentRole.ValueType":
     match role:
         case "viewer":
@@ -116,7 +113,7 @@ def _role_to_proto(role: str) -> "api_pb2.EnvironmentRole.ValueType":
             raise InvalidError(f"Invalid Environment role: {role!r} (expected 'viewer' or 'contributor')")
 
 
-def _role_from_proto(proto_value: int) -> MemberRole:
+def _role_from_proto(proto_value: int) -> str:
     match proto_value:
         case api_pb2.ENVIRONMENT_ROLE_VIEWER:
             return "viewer"
@@ -137,7 +134,7 @@ class _EnvironmentMembersManager:
         """mdmd:hidden"""
         self._environment = environment
 
-    async def list(self) -> dict[Literal["users", "service_users"], dict[str, MemberRole]]:
+    async def list(self) -> dict[Literal["users", "service_users"], dict[str, str]]:
         """Return the members of a restricted Environment with their roles.
 
         **Examples:**
@@ -155,8 +152,8 @@ class _EnvironmentMembersManager:
         req = api_pb2.EnvironmentGetManagedRequest(environment_id=self._environment.object_id)
         resp = await self._environment.client.stub.EnvironmentGetManaged(req)
 
-        users: dict[str, MemberRole] = {}
-        service_users: dict[str, MemberRole] = {}
+        users: dict[str, str] = {}
+        service_users: dict[str, str] = {}
         for principal in resp.principal_roles:
             role = _role_from_proto(principal.role)
             if principal.user_id:
@@ -169,8 +166,8 @@ class _EnvironmentMembersManager:
     async def update(
         self,
         *,
-        users: Mapping[str, MemberRole] | None = None,
-        service_users: Mapping[str, MemberRole] | None = None,
+        users: Mapping[str, str] | None = None,
+        service_users: Mapping[str, str] | None = None,
     ) -> None:
         """Add or modify roles for members of a restricted Environment.
 
@@ -416,26 +413,33 @@ class _EnvironmentBillingManager:
         resolution: str = "d",  # Resolution, e.g. "d" for daily or "h" for hourly
         tag_names: list[str] | None = None,  # Optional additional metadata to include
     ) -> list[BillingReportItem]:
-        (
-            """Return a report of workspace usage by object and time, scoped to the calling Environment.
-
-            The result will be a list of dataclasses for each interval (determined by `resolution`)
-            between the `start` and `end` limits. Each item represents a single (Modal object, time interval)
-            pair that billing can be attributed to (e.g., an App) along with metadata (including user-defined
-            tags) to identify that object. The dataclass also contains a breakdown of the cost value
-            attributed to individual resources (for an App, this can be CPU, Memory, specific GPU types,
-            etc.). The specific resource types included in the breakdown are subject to change as
-            Modal's billing model evolves.
-
-            It's also possible to generate reports using the
-            [`modal environment billing report`](https://modal.com/docs/cli/latest/environment#modal-environment-billing-report)
-            CLI command.  The CLI has a few convenience features for generating
-            reports across relative time ranges.
-
-            """
-            + BILLING_DOCSTRING
-        )
+        """Return a cost report for Environment usage, broken down by object and time.
+
+        Args:
+            start: Start of the report, inclusive and rounded to the beginning of the interval.
+                Must be in UTC or timezone-naive (interpreted as UTC).
+            end: End of the report, exclusive. Must be in UTC or timezone-naive. Partial final
+                intervals will be excluded from the report.
+            resolution: Resolution, e.g. "d" for daily or "h" for hourly.
+            tag_names: List of tag names; each row will include the tag name and value in use
+                for that object during the relevant time interval. Pass `["*"]` to include all
+                tags in the report.
+
+        Returns:
+            A list of `BillingReportItem` dataclasses. Each item reports the cost attributed to
+            a specific Modal object during a given time interval. Cost is further broken down by
+            the resource type that generated it (e.g. CPU, Memory, specific GPU usage).
+            Note that the specific resource types included in the breakdown are subject to change
+            as Modal's billing model evolves.
+
+        See also:
+            - [`modal environment billing report`](https://modal.com/docs/cli/latest/environment#modal-environment-billing-report):
+              An environment report CLI that has convenience features around relative time range queries
+              and JSON/CSV output.
+            - [`Workspace.billing.report()`](https://modal.com/docs/sdk/py/latest/modal.Workspace#billingreport):
+              An analogous report API for the entire Workspace.
 
+        """
         if tag_names is None:
             tag_names = []
 

{modal-1.5.1.dev14 → modal-1.5.2}/modal/_function_variants.py

@@ -51,6 +51,7 @@ class _FunctionOptions:
     target_concurrent_inputs: int | None = None
     batch_max_size: int | None = None
     batch_wait_ms: int | None = None
+    routing_region: str | None = None
 
     @classmethod
     def new(
@@ -73,6 +74,7 @@ class _FunctionOptions:
         target_concurrent_inputs: int | None = None,
         batch_max_size: int | None = None,
         batch_wait_ms: int | None = None,
+        routing_region: str | None = None,
     ) -> "_FunctionOptions":
         """Internal constructor that validates and normalizes public parameters."""
         retry_policy = _parse_retries(retries)
@@ -119,6 +121,7 @@ class _FunctionOptions:
             target_concurrent_inputs=target_concurrent_inputs,
             batch_max_size=batch_max_size,
             batch_wait_ms=batch_wait_ms,
+            routing_region=routing_region,
         )
 
     def merge_options(self, new_options: "_FunctionOptions") -> "_FunctionOptions":
@@ -182,6 +185,7 @@ class _FunctionOptions:
             batch_linger_ms=self.batch_wait_ms,
             scheduler_placement=self.scheduler_placement,
             cloud_provider_str=self.cloud,
+            routing_region=self.routing_region,
         )
 
 

{modal-1.5.1.dev14 → modal-1.5.2}/modal/_functions.py

@@ -90,6 +90,7 @@ from .proxy import _Proxy
 from .retries import Retries, RetryManager
 from .schedule import Schedule
 from .secret import _Secret
+from .types import FunctionStats
 from .volume import _Volume, _volume_to_mount_proto
 
 if TYPE_CHECKING:
@@ -541,17 +542,6 @@ class _InputPlaneInvocation:
         return [("x-modal-input-plane-region", input_plane_region), ("x-modal-auth-token", token)]
 
 
-# Wrapper type for api_pb2.FunctionStats
-@dataclass(frozen=True)
-class FunctionStats:
-    """Simple data structure storing stats for a running function."""
-
-    backlog: int
-    num_total_runners: int
-    num_running_inputs: int
-    input_headroom: int
-
-
 @dataclass
 class _FunctionSpec:
     """
@@ -1195,10 +1185,10 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
         its static configuration.
 
         Args:
-            min_containers: Minimum number of containers to keep running, or `None` to leave unchanged.
-            max_containers: Maximum concurrent containers, or `None` to leave unchanged.
-            buffer_containers: Extra containers to keep warm beyond demand, or `None` to leave unchanged.
-            scaledown_window: Seconds idle containers wait before scaling down, or `None` to leave unchanged.
+            min_containers: Minimum number of containers to keep running.
+            max_containers: Maximum concurrent containers.
+            buffer_containers: Extra containers to keep warm beyond current demand.
+            scaledown_window: Maximum duration (in seconds) idle containers wait before scaling down.
 
         Examples:
             ```python notest
@@ -1212,7 +1202,7 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
 
             # Extend the scaledown window to increase the amount of time that idle containers stay alive
             f.update_autoscaler(scaledown_window=300)
-        ```
+            ```
 
         """
         # Assert .update_autoscaler() is not called on a method as opposed to the Object. Applicable for Cls only.
@@ -1519,6 +1509,7 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
         timeout: int | None = None,
         region: str | Sequence[str] | None = None,
         cloud: str | None = None,
+        routing_region: str | None = None,
     ) -> "_Function[P, ReturnType, OriginalReturnType]":
         """Dynamically override the static Function configuration with invocation-specific values.
 
@@ -1567,6 +1558,7 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
             timeout=timeout,
             region=region,
             cloud=cloud,
+            routing_region=routing_region,
         )
 
         return self._apply_dynamic_config(options, "with_options")

{modal-1.5.1.dev14 → modal-1.5.2}/modal/_image.py

@@ -117,13 +117,34 @@ def _validate_image_tag(tag: str) -> None:
     check_object_name(tag, "Image tag")
 
 
-def _parse_named_image_ref(name: str) -> str:
+def _parse_named_image_ref(name: str) -> tuple[str, str]:
+    """Parse an image reference, returning (namespace_prefix, name_tag).
+
+    If the name contains a '/', the part before the last '/' is extracted as
+    a namespace prefix (intended for environment/name or workspace/env/name
+    syntax). The actual image name (after the last '/') is validated as a
+    standard object name.
+
+    Returns a tuple of (prefix, "full_name:tag") where prefix is empty string
+    if no '/' is present.
+    """
     image_name, sep, tag = name.partition(":")
     if not sep:
         tag = "latest"
+
+    prefix = ""
+    if "/" in image_name:
+        prefix, image_name = image_name.rsplit("/", 1)
+        if not prefix:
+            raise InvalidError("Invalid Image name: '/' prefix must be non-empty.")
+        if not image_name:
+            raise InvalidError("Invalid Image name: name after '/' must be non-empty.")
+
     _validate_image_name(image_name)
     _validate_image_tag(tag)
-    return f"{image_name}:{tag}"
+
+    full_name = f"{prefix}/{image_name}" if prefix else image_name
+    return prefix, f"{full_name}:{tag}"
 
 
 def _validate_python_version(
@@ -1022,7 +1043,7 @@ class _Image(_Object, type_prefix="im"):
             ```
         """
         if app.app_id is None:
-            raise InvalidError("App has not been initialized yet. Use the content manager `app.run()` or `App.lookup`")
+            raise InvalidError("App has not been initialized yet. Use the context manager `app.run()` or `App.lookup`")
 
         resolver = Resolver()
         async with TaskContext() as tc:
@@ -2923,12 +2944,15 @@ class _Image(_Object, type_prefix="im"):
             ...
         ```
         """
-        tag = _parse_named_image_ref(name)
+        namespace_prefix, tag = _parse_named_image_ref(name)
+
+        if namespace_prefix and environment_name:
+            raise InvalidError("Cannot specify 'environment_name' when the image name contains a '/'.")
 
         async def _load(self: _Image, resolver: Resolver, load_context: LoadContext, existing_object_id: str | None):
             req = api_pb2.ImageGetByTagRequest(
                 tag=tag,
-                environment_name=load_context.environment_name,
+                environment_name="" if namespace_prefix else load_context.environment_name,
             )
             response = await load_context.client.stub.ImageGetByTag(req)
             self._hydrate(response.image_id, load_context.client, None)
@@ -2963,21 +2987,25 @@ class _Image(_Object, type_prefix="im"):
         image.publish("my-image-with-numpy:v1")
         ```
         """
-        tag = _parse_named_image_ref(name)
+        namespace_prefix, tag = _parse_named_image_ref(name)
 
-        if not self.is_hydrated:
-            raise InvalidError("Cannot publish an image that has not been created yet. Call `.build()` first.")
+        if namespace_prefix:
+            if environment_name:
+                raise InvalidError("Cannot specify 'environment_name' when the image name contains a '/'.")
+            resolved_env = ""
+        else:
+            resolved_env = environment_name or config.get("environment") or ""
 
-        _client = client or self._client
-        assert _client is not None
+        if self._object_id is None:
+            raise InvalidError("Cannot publish an image that has not been created yet. Call `.build()` first.")
 
-        resolved_env = environment_name or config.get("environment") or ""
+        _client = client or await _Client.from_env()
 
         await _client.stub.ImagePublish(
             api_pb2.ImagePublishRequest(
-                image_id=self.object_id,
+                image_id=self._object_id,
                 environment_name=resolved_env,
-                is_public=False,
+                allow_public=False,
                 tag=tag,
             )
         )

{modal-1.5.1.dev14 → modal-1.5.2}/modal/_runtime/container_io_manager.py

@@ -264,7 +264,7 @@ class IOContext:
         if not inspect.isasyncgen(expected_async_gen):
             raise InvalidError(f"Async generator function returned value of type {type(expected_async_gen)}")
 
-        async with aclosing(expected_async_gen) as gen:
+        async with aclosing(cast(AsyncGenerator[Any, None], expected_async_gen)) as gen:
             async for result in gen:
                 yield result
         logger.debug(f"Finished generator input {self.input_ids}")

{modal-1.5.1.dev14 → modal-1.5.2}/modal/_runtime/gpu_memory_snapshot.py

@@ -17,6 +17,11 @@ from modal.config import config, logger
 
 CUDA_CHECKPOINT_PATH: str = config.get("cuda_checkpoint_path")
 
+# Exit code used to signal to modal-runtime that a GPU memory snapshot restore failed
+# and the task should be retried without a snapshot. This is a sentinel value that must
+# stay in sync with `GPU_SNAPSHOT_RESTORE_FAILED_EXIT_CODE` in runner.rs.
+SNAPSHOT_RESTORE_FAILED_EXIT_CODE: int = 222
+
 # Maximum total duration for each individual `cuda-checkpoint` invocation.
 CUDA_CHECKPOINT_TIMEOUT: float = 3 * 60.0
 

{modal-1.5.1.dev14 → modal-1.5.2}/modal/_runtime/task_lifecycle_manager.py

@@ -180,10 +180,15 @@ class _TaskLifecycleManager:
         if self.function_def._experimental_enable_gpu_snapshot and self.function_def.resources.gpu_config.gpu_type:
             logger.debug("GPU memory snapshot enabled. Attempting to restore GPU memory.")
 
-            assert self._cuda_checkpoint_session, (
-                "CudaCheckpointSession not found when attempting to restore GPU memory"
-            )
-            self._cuda_checkpoint_session.restore()
+            try:
+                if self._cuda_checkpoint_session is None:
+                    raise gpu_memory_snapshot.CudaCheckpointException("CudaCheckpointSession not found")
+                self._cuda_checkpoint_session.restore()
+            except gpu_memory_snapshot.CudaCheckpointException as exc:
+                logger.warning(f"GPU memory snapshot restore failed; retrying task without snapshot. Error: {exc}")
+                sys.stderr.flush()
+                # Exit with a sentinel code that the runtime will use to retry the task without a snapshot.
+                os._exit(gpu_memory_snapshot.SNAPSHOT_RESTORE_FAILED_EXIT_CODE)
 
         self._client = await _Client.from_env()
 

{modal-1.5.1.dev14 → modal-1.5.2}/modal/_server.py

@@ -46,7 +46,7 @@ def validate_http_server_config(
 class _Server:
     """Server runs an HTTP server started in an `@modal.enter` method.
 
-    See [lifecycle hooks](https://modal.com/docs/guide/lifecycle-functions) for more information.
+    See the [guide](https://modal.com/docs/guide/servers) for more information.
 
     Generally, you will not construct a Server directly.
     Instead, use the [`@app.server()`](https://modal.com/docs/sdk/py/latest/modal.App#server) decorator.
@@ -77,6 +77,7 @@ class _Server:
 
     @property
     def object_id(self) -> str:
+        """Modal's internal ID for this Server instance."""
         return self._service_function.object_id
 
     @staticmethod
@@ -91,6 +92,7 @@ class _Server:
 
     @live_method
     async def get_url(self) -> str | None:
+        """The URL for making requests to this Server."""
         urls = await self._get_service_function()._experimental_get_flash_urls()
         # Return the first URL if it exists. Servers should only have one URL
         # since they only have one region.
@@ -101,16 +103,28 @@ class _Server:
     async def update_autoscaler(
         self,
         *,
+        target_concurrency: int | None = None,
         min_containers: int | None = None,
         max_containers: int | None = None,
         buffer_containers: int | None = None,
         scaleup_window: int | None = None,
         scaledown_window: int | None = None,
-        target_concurrency: int | None = None,
     ) -> None:
         """Override the current autoscaler behavior for this Server.
 
-        Unspecified parameters will retain their current value.
+        Unspecified parameters will retain their current value, i.e. either the static value
+        from the `@app.server()` decorator, or an override value from a previous call to this method.
+
+        Subsequent deployments of the App containing this Server will reset the autoscaler back to
+        its static configuration.
+
+        Args:
+            target_concurrency: Target number of concurrent requests per container.
+            min_containers: Minimum number of containers to keep running regardless of demand.
+            max_containers: Limit on the number of containers that can be concurrently running.
+            buffer_containers: Extra containers to scale up beyond current demand.
+            scaleup_window: Seconds of sustained demand required before scaling up new containers.
+            scaledown_window: Maximum duration (in seconds) idle containers wait before scaling down.
 
         Examples:
             ```python notest
@@ -130,7 +144,7 @@ class _Server:
 
             # Disable the Server autoscaling by setting target_concurrency to 0
             server.update_autoscaler(target_concurrency=0)
-        ```
+            ```
 
         """
         return await self._get_service_function()._update_autoscaler(
@@ -144,6 +158,13 @@ class _Server:
 
     # ============ Hydration ============
     async def hydrate(self, client: _Client | None = None) -> "_Server":
+        """Synchronize the local object with its identity on the Modal server.
+
+        It is rarely necessary to call this method explicitly, as most operations will
+        lazily hydrate when needed. The main use case is when you need to access object
+        metadata, such as its ID.
+
+        """
         # This is required since we want to support @livemethod() decorated methods
         service_function = self._get_service_function()
         await service_function.hydrate(client)
@@ -183,6 +204,12 @@ class _Server:
         object with metadata from Modal servers until the first
         time it is actually used.
 
+        Args:
+            app_name: Name of the App containing the Server.
+            name: Name of the Server within the App.
+            environment_name: Name of the Environment where the App is deployed.
+            client: Modal client instance for this session.
+
         ```python notest
         server = modal.Server.from_name("other-app", "Server")
         ```

{modal-1.5.1.dev14 → modal-1.5.2}/modal/_utils/blob_utils.py

@@ -138,6 +138,13 @@ async def _upload_to_s3_url(
                     text = await resp.text()
                 except Exception:
                     text = "<no body>"
+
+                if "The Content-MD5 you specified did not match what we received." in text:
+                    raise ExecutionError(
+                        "Hash mismatch during upload. This may be caused by files changing while an upload is in "
+                        "progress. Please try again."
+                    )
+
                 raise ExecutionError(f"Put to url {upload_url} failed with status {resp.status}: {text}")
 
             # client side ETag checksum verification