modal 1.5.1.dev14__tar.gz → 1.5.2.dev0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.5.1.dev14
+Version: 1.5.2.dev0
 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.dev0}/modal/_billing.py

@@ -9,24 +9,6 @@ from modal_proto import api_pb2
 from ._utils.deprecation import deprecation_warning
 from .client import _Client
 
-BILLING_DOCSTRING = """
-            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.
-
-            In most cases, billing data will be available in the database that this API queries within
-            minutes, although there may be collection delays. If completeness is important for your use
-            case, we recommend leaving a buffer after the end of the query interval.
-"""
-
 
 class WorkspaceBillingReportItem(TypedDict):
     object_id: str
@@ -115,10 +97,6 @@ async def _workspace_billing_report(
     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.
 
-    In most cases, billing data will be available in the database that this API queries within
-    minutes, although there may be collection delays. If completeness is important for your use
-    case, we recommend leaving a buffer after the end of the query interval.
-
     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.
@@ -127,7 +105,8 @@ async def _workspace_billing_report(
 
     deprecation_warning(
         (2026, 6, 18),
-        "`workspace_billing_report()` is deprecated. Use `Workspace.billing.report()` instead.",
+        "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

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

@@ -13,7 +13,7 @@ from synchronicity import classproperty
 
 from modal_proto import api_pb2
 
-from ._billing import BILLING_DOCSTRING, BillingReportItem
+from ._billing import BillingReportItem
 from ._load_context import LoadContext
 from ._object import _Object
 from ._resolver import Resolver
@@ -416,26 +416,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.dev0}/modal/_functions.py

@@ -1195,10 +1195,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 +1212,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.

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

@@ -2965,17 +2965,16 @@ class _Image(_Object, type_prefix="im"):
         """
         tag = _parse_named_image_ref(name)
 
-        if not self.is_hydrated:
+        if self._object_id is None:
             raise InvalidError("Cannot publish an image that has not been created yet. Call `.build()` first.")
 
-        _client = client or self._client
-        assert _client is not None
+        _client = client or await _Client.from_env()
 
         resolved_env = environment_name or config.get("environment") or ""
 
         await _client.stub.ImagePublish(
             api_pb2.ImagePublishRequest(
-                image_id=self.object_id,
+                image_id=self._object_id,
                 environment_name=resolved_env,
                 is_public=False,
                 tag=tag,

{modal-1.5.1.dev14 → modal-1.5.2.dev0}/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.dev0}/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.dev0}/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.2.dev0/modal/_utils/curl_utils.py

@@ -0,0 +1,115 @@
+# Copyright Modal Labs 2026
+from urllib.parse import urlparse
+
+# Short curl flags (single dash, single letter) that consume the following argument.
+_CURL_SHORT_VALUE_FLAGS = frozenset("AbCcDdEeFHhKmoQrTtUuwXxYyz")
+
+# Long curl flags that consume the following argument (when given as `--flag value`).
+# Flags given as `--flag=value` are self-contained and handled generically.
+_CURL_LONG_VALUE_FLAGS = frozenset(
+    {
+        "--cacert",
+        "--capath",
+        "--cert",
+        "--cert-type",
+        "--config",
+        "--connect-timeout",
+        "--connect-to",
+        "--continue-at",
+        "--cookie",
+        "--cookie-jar",
+        "--data",
+        "--data-ascii",
+        "--data-binary",
+        "--data-raw",
+        "--data-urlencode",
+        "--dump-header",
+        "--form",
+        "--form-string",
+        "--header",
+        "--interface",
+        "--key",
+        "--key-type",
+        "--limit-rate",
+        "--max-filesize",
+        "--max-redirs",
+        "--max-time",
+        "--oauth2-bearer",
+        "--output",
+        "--pass",
+        "--proxy",
+        "--proxy-user",
+        "--range",
+        "--referer",
+        "--request",
+        "--resolve",
+        "--retry",
+        "--retry-delay",
+        "--retry-max-time",
+        "--unix-socket",
+        "--upload-file",
+        "--url",
+        "--user",
+        "--user-agent",
+        "--write-out",
+    }
+)
+
+
+def endpoint_cache_host(url: str) -> str:
+    parsed = urlparse(url if "://" in url else f"https://{url}")
+    return (parsed.hostname or url).lower().rstrip(".")
+
+
+def is_modal_direct_url(url: str) -> bool:
+    # Only fetch token for app.server() functions
+    host = endpoint_cache_host(url)
+    return host.endswith("modal.direct") or host.endswith("modal-dev.direct")
+
+
+def _is_modal_direct_candidate(arg: str) -> bool:
+    try:
+        return is_modal_direct_url(arg)
+    except ValueError:
+        return False
+
+
+def find_url(curl_args: tuple[str, ...]) -> str | None:
+    """Find the Modal direct URL operand within a curl argument list.
+
+    Parses the args the way curl does well enough to skip over flag values, so that
+    a `modal.direct` host appearing as e.g. a header or data value is not mistaken
+    for the request URL.
+    """
+    i = 0
+    n = len(curl_args)
+    while i < n:
+        arg = curl_args[i]
+
+        if arg.startswith("--"):
+            flag, sep, value = arg.partition("=")
+            if sep:
+                # `--flag=value`: the value is self-contained.
+                if flag == "--url" and _is_modal_direct_candidate(value):
+                    return value
+            elif flag in _CURL_LONG_VALUE_FLAGS:
+                # `--flag value`: the next argument is this flag's value.
+                value = curl_args[i + 1] if i + 1 < n else ""
+                if flag == "--url" and _is_modal_direct_candidate(value):
+                    return value
+                i += 2
+                continue
+        elif arg.startswith("-") and len(arg) >= 2:
+            last = arg[-1]
+            if len(arg) == 2 and last in _CURL_SHORT_VALUE_FLAGS:
+                # `-X value`: the next argument is this flag's value.
+                i += 2
+                continue
+            # `-Xvalue` (attached value) or a cluster of boolean flags: nothing to skip.
+        elif _is_modal_direct_candidate(arg):
+            # A bare (positional) URL operand.
+            return arg
+
+        i += 1
+
+    return None