modal 1.0.3.dev10__py3-none-any.whl → 1.2.3.dev7__py3-none-any.whl

modal/environments.py

@@ -8,11 +8,10 @@ from google.protobuf.wrappers_pb2 import StringValue
 
 from modal_proto import api_pb2
 
+from ._load_context import LoadContext
 from ._object import _Object
 from ._resolver import Resolver
 from ._utils.async_utils import synchronize_api, synchronizer
-from ._utils.deprecation import deprecation_warning
-from ._utils.grpc_utils import retry_transient_errors
 from ._utils.name_utils import check_object_name
 from .client import _Client
 from .config import config, logger
@@ -54,6 +53,7 @@ class _Environment(_Object, type_prefix="en"):
         name: str,
         *,
         create_if_missing: bool = False,
+        client: Optional[_Client] = None,
     ):
         if name:
             # Allow null names for the case where we want to look up the "default" environment,
@@ -63,7 +63,9 @@ class _Environment(_Object, type_prefix="en"):
             # environments as part of public API when we make this class more useful.
             check_object_name(name, "Environment")
 
-        async def _load(self: _Environment, resolver: Resolver, existing_object_id: Optional[str]):
+        async def _load(
+            self: _Environment, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]
+        ):
             request = api_pb2.EnvironmentGetOrCreateRequest(
                 deployment_name=name,
                 object_creation_type=(
@@ -72,31 +74,17 @@ class _Environment(_Object, type_prefix="en"):
                     else api_pb2.OBJECT_CREATION_TYPE_UNSPECIFIED
                 ),
             )
-            response = await retry_transient_errors(resolver.client.stub.EnvironmentGetOrCreate, request)
+            response = await load_context.client.stub.EnvironmentGetOrCreate(request)
             logger.debug(f"Created environment with id {response.environment_id}")
-            self._hydrate(response.environment_id, resolver.client, response.metadata)
-
-        # TODO environment name (and id?) in the repr? (We should make reprs consistently more useful)
-        return _Environment._from_loader(_load, "Environment()", is_another_app=True, hydrate_lazily=True)
-
-    @staticmethod
-    async def lookup(
-        name: str,
-        client: Optional[_Client] = None,
-        create_if_missing: bool = False,
-    ):
-        deprecation_warning(
-            (2025, 1, 27),
-            "`modal.Environment.lookup` is deprecated and will be removed in a future release."
-            " It can be replaced with `modal.Environment.from_name`."
-            "\n\nSee https://modal.com/docs/guide/modal-1-0-migration for more information.",
+            self._hydrate(response.environment_id, load_context.client, response.metadata)
+
+        return _Environment._from_loader(
+            _load,
+            f"Environment.from_name({name!r})",
+            is_another_app=True,
+            hydrate_lazily=True,
+            load_context_overrides=LoadContext(client=client),
         )
-        obj = _Environment.from_name(name, create_if_missing=create_if_missing)
-        if client is None:
-            client = await _Client.from_env()
-        resolver = Resolver(client=client)
-        await resolver.load(obj)
-        return obj
 
 
 Environment = synchronize_api(_Environment)
@@ -109,7 +97,7 @@ ENVIRONMENT_CACHE: dict[str, _Environment] = {}
 async def _get_environment_cached(name: str, client: _Client) -> _Environment:
     if name in ENVIRONMENT_CACHE:
         return ENVIRONMENT_CACHE[name]
-    environment = await _Environment.from_name(name).hydrate(client)
+    environment = await _Environment.from_name(name, client=client).hydrate()
     ENVIRONMENT_CACHE[name] = environment
     return environment
 

modal/environments.pyi

@@ -7,45 +7,60 @@ import typing
 import typing_extensions
 
 class EnvironmentSettings:
+    """EnvironmentSettings(image_builder_version: str, webhook_suffix: str)"""
+
     image_builder_version: str
     webhook_suffix: str
 
-    def __init__(self, image_builder_version: str, webhook_suffix: str) -> None: ...
-    def __repr__(self): ...
-    def __eq__(self, other): ...
-    def __setattr__(self, name, value): ...
-    def __delattr__(self, name): ...
-    def __hash__(self): ...
+    def __init__(self, image_builder_version: str, webhook_suffix: str) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
+
+    def __setattr__(self, name, value):
+        """Implement setattr(self, name, value)."""
+        ...
+
+    def __delattr__(self, name):
+        """Implement delattr(self, name)."""
+        ...
+
+    def __hash__(self):
+        """Return hash(self)."""
+        ...
 
 class _Environment(modal._object._Object):
     _settings: EnvironmentSettings
 
-    def __init__(self): ...
+    def __init__(self):
+        """mdmd:hidden"""
+        ...
+
     def _hydrate_metadata(self, metadata: google.protobuf.message.Message): ...
     @staticmethod
-    def from_name(name: str, *, create_if_missing: bool = False): ...
-    @staticmethod
-    async def lookup(
-        name: str, client: typing.Optional[modal.client._Client] = None, create_if_missing: bool = False
+    def from_name(
+        name: str, *, create_if_missing: bool = False, client: typing.Optional[modal.client._Client] = None
     ): ...
 
 class Environment(modal.object.Object):
     _settings: EnvironmentSettings
 
-    def __init__(self): ...
+    def __init__(self):
+        """mdmd:hidden"""
+        ...
+
     def _hydrate_metadata(self, metadata: google.protobuf.message.Message): ...
     @staticmethod
-    def from_name(name: str, *, create_if_missing: bool = False): ...
-
-    class __lookup_spec(typing_extensions.Protocol):
-        def __call__(
-            self, /, name: str, client: typing.Optional[modal.client.Client] = None, create_if_missing: bool = False
-        ): ...
-        async def aio(
-            self, /, name: str, client: typing.Optional[modal.client.Client] = None, create_if_missing: bool = False
-        ): ...
-
-    lookup: __lookup_spec
+    def from_name(
+        name: str, *, create_if_missing: bool = False, client: typing.Optional[modal.client.Client] = None
+    ): ...
 
 async def _get_environment_cached(name: str, client: modal.client._Client) -> _Environment: ...
 
@@ -93,6 +108,13 @@ class __list_environments_spec(typing_extensions.Protocol):
 
 list_environments: __list_environments_spec
 
-def ensure_env(environment_name: typing.Optional[str] = None) -> str: ...
+def ensure_env(environment_name: typing.Optional[str] = None) -> str:
+    """Override config environment with environment from environment_name
+
+    This is necessary since a cli command that runs Modal code, without explicit
+    environment specification wouldn't pick up the environment specified in a
+    command line flag otherwise, e.g. when doing `modal run --env=foo`
+    """
+    ...
 
 ENVIRONMENT_CACHE: dict[str, _Environment]

modal/exception.py

@@ -2,11 +2,15 @@
 import random
 import signal
 
+import synchronicity.exceptions
+
+UserCodeException = synchronicity.exceptions.UserCodeException  # Deprecated type used for return_exception wrapping
+
 
 class Error(Exception):
     """
-    Base class for all Modal errors. See [`modal.exception`](/docs/reference/modal.exception) for the specialized
-    error classes.
+    Base class for all Modal errors. See [`modal.exception`](https://modal.com/docs/reference/modal.exception)
+    for the specialized error classes.
 
     **Usage**
 
@@ -22,6 +26,10 @@ class Error(Exception):
     """
 
 
+class AlreadyExistsError(Error):
+    """Raised when a resource creation conflicts with an existing resource."""
+
+
 class RemoteError(Error):
     """Raised when an error occurs on the Modal server."""
 
@@ -34,6 +42,10 @@ class SandboxTimeoutError(TimeoutError):
     """Raised when a Sandbox exceeds its execution duration limit and times out."""
 
 
+class ExecTimeoutError(TimeoutError):
+    """Raised when a container process exceeds its execution duration limit and times out."""
+
+
 class SandboxTerminatedError(Error):
     """Raised when a Sandbox is terminated for an internal reason."""
 

modal/experimental/__init__.py

@@ -1,5 +1,6 @@
 # Copyright Modal Labs 2025
 import os
+import shlex
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal, Optional, Union
@@ -12,13 +13,13 @@ from .._object import _get_environment_name
 from .._partial_function import _clustered
 from .._runtime.container_io_manager import _ContainerIOManager
 from .._utils.async_utils import synchronize_api, synchronizer
-from .._utils.deprecation import deprecation_warning
-from .._utils.grpc_utils import retry_transient_errors
+from ..app import _App
 from ..client import _Client
-from ..cls import _Obj
+from ..cls import _Cls
 from ..exception import InvalidError
 from ..image import DockerfileSpec, ImageBuilderVersion, _Image, _ImageRegistryConfig
 from ..secret import _Secret
+from .flash import flash_forward, flash_get_containers, flash_prometheus_autoscaler  # noqa: F401
 
 
 def stop_fetching_inputs():
@@ -84,6 +85,51 @@ async def list_deployed_apps(environment_name: str = "", client: Optional[_Clien
     return app_infos
 
 
+@synchronizer.create_blocking
+async def get_app_objects(
+    app_name: str, *, environment_name: Optional[str] = None, client: Optional[_Client] = None
+) -> dict[str, Union[_Function, _Cls]]:
+    """Experimental interface for retrieving a dictionary of the Functions / Clses in an App.
+
+    The return value is a dictionary mapping names to unhydrated Function or Cls objects.
+
+    We plan to support this functionality through a stable API in the future. It's likely that
+    the stable API will look different (it will probably be a method on the App object itself).
+
+    """
+    # This is implemented through a somewhat odd mixture of internal RPCs and public APIs.
+    # While AppGetLayout provides the object ID and metadata for each object in the App, it's
+    # currently somewhere between very awkward and impossible to hydrate a modal.Cls with just
+    # that information, since the "class service function" needs to be loaded first
+    # (and it's not always possible to do that without knowledge of the parameterization).
+    # So instead we just use AppGetLayout to retrieve the names of the Functions / Clsices on
+    # the App and then use the public .from_name constructors to return unhydrated handles.
+
+    # Additionally, since we need to know the environment name to use `.from_name`, and the App's
+    # environment name isn't stored anywhere on the App (and cannot be retrieved via an RPC), the
+    # experimental function is parameterized by an App name while the stable API would instead
+    # be a method on the App itself.
+
+    if client is None:
+        client = await _Client.from_env()
+
+    app = await _App.lookup(app_name, environment_name=environment_name, client=client)
+    req = api_pb2.AppGetLayoutRequest(app_id=app.app_id)
+    app_layout_resp = await client.stub.AppGetLayout(req)
+
+    app_objects: dict[str, Union[_Function, _Cls]] = {}
+
+    for cls_name in app_layout_resp.app_layout.class_ids:
+        app_objects[cls_name] = _Cls.from_name(app_name, cls_name, environment_name=environment_name)
+
+    for func_name in app_layout_resp.app_layout.function_ids:
+        if func_name.endswith(".*"):
+            continue  # TODO explain
+        app_objects[func_name] = _Function.from_name(app_name, func_name, environment_name=environment_name)
+
+    return app_objects
+
+
 @synchronizer.create_blocking
 async def raw_dockerfile_image(
     path: Union[str, Path],
@@ -94,8 +140,9 @@ async def raw_dockerfile_image(
 
     Unlike for `modal.Image.from_dockerfile`, the provided recipe will not be embellished with
     steps to install dependencies for the Modal client package. As a consequence, the resulting
-    Image cannot be used with a modal Function unless those dependencies are added in a subsequent
-    layer. It _can_ be directly used with a modal Sandbox, which does not need the Modal client.
+    Image cannot be used with a modal Function unless those dependencies are already included
+    as part of the base Dockerfile recipe or are added in a subsequent layer. The Image _can_ be
+    directly used with a modal Sandbox, which does not need the Modal client.
 
     We expect to support this experimental function until the `2025.04` Modal Image Builder is
     stable, at which point Modal Image recipes will no longer install the client dependencies
@@ -127,8 +174,9 @@ async def raw_registry_image(
 
     Unlike for `modal.Image.from_registry`, the provided recipe will not be embellished with
     steps to install dependencies for the Modal client package. As a consequence, the resulting
-    Image cannot be used with a modal Function unless those dependencies are added in a subsequent
-    layer. It _can_ be directly used with a modal Sandbox, which does not need the Modal client.
+    Image cannot be used with a modal Function unless those dependencies are already included
+    as part of the registry Image or are added in a subsequent layer. The Image _can_ be
+    directly used with a modal Sandbox, which does not need the Modal client.
 
     We expect to support this experimental function until the `2025.04` Modal Image Builder is
     stable, at which point Modal Image recipes will no longer install the client dependencies
@@ -163,47 +211,153 @@ async def raw_registry_image(
     )
 
 
+def _install_cuda_command() -> str:
+    """Command to install CUDA Toolkit (nvcc) inside a container."""
+    arch = "x86_64"  # instruction set architecture for the CPU, all Modal machines are x86_64
+    distro = "debian12"  # the distribution and version number of our OS (GNU/Linux)
+    filename = "cuda-keyring_1.1-1_all.deb"  # NVIDIA signing key file
+    cuda_keyring_url = f"https://developer.download.nvidia.com/compute/cuda/repos/{distro}/{arch}/{filename}"
+
+    major, minor = 12, 8
+    max_cuda_version = f"{major}-{minor}"
+
+    return (
+        f"wget {cuda_keyring_url} && "
+        + f"dpkg -i {filename} && "
+        + f"rm -f {filename} && "
+        + f"apt-get update && apt-get install -y cuda-nvcc-{max_cuda_version}"
+    )
+
+
 @synchronizer.create_blocking
-async def update_autoscaler(
-    obj: Union[_Function, _Obj],
+async def notebook_base_image(*, python_version: Optional[str] = None, force_build: bool = False) -> _Image:
+    """Default image used for Modal notebook kernels, with common libraries.
+
+    This can be used to bootstrap development workflows quickly. We don't
+    recommend using this image for production Modal Functions though, as it may
+    change at any time in the future.
+    """
+    # Include several common packages, as well as kernelshim dependencies (except 'modal').
+    # These packages aren't pinned, so they may change over time with builds.
+    #
+    # We plan to use `--exclude-newer` in the future, with date-specific image builds.
+    base_image = _Image.debian_slim(python_version=python_version)
+
+    environment_packages: list[str] = [
+        "accelerate",
+        "aiohttp",
+        "altair",
+        "anthropic",
+        "asyncpg",
+        "beautifulsoup4",
+        "bokeh",
+        "boto3[crt]",
+        "click",
+        "diffusers[torch,flax]",
+        "dm-sonnet",
+        "flax",
+        "ftfy",
+        "h5py",
+        "urllib3",
+        "httpx",
+        "huggingface-hub",
+        "ipywidgets",
+        "jax[cuda12]",
+        "keras",
+        "matplotlib",
+        "nbformat",
+        "numba",
+        "numpy",
+        "openai",
+        "optax",
+        "pandas",
+        "plotly[express]",
+        "polars",
+        "psycopg2",
+        "requests",
+        "safetensors",
+        "scikit-image",
+        "scikit-learn",
+        "scipy",
+        "seaborn",
+        "sentencepiece",
+        "sqlalchemy",
+        "statsmodels",
+        "sympy",
+        "tabulate",
+        "tensorboard",
+        "toml",
+        "transformers",
+        "triton",
+        "typer",
+        "vega-datasets",
+        "watchfiles",
+        "websockets",
+    ]
+
+    # Kernelshim dependencies. (see NOTEBOOK_KERNELSHIM_DEPENDENCIES)
+    kernelshim_packages: list[str] = [
+        "authlib>=1.3",
+        "basedpyright>=1.28",
+        "fastapi>=0.100",
+        "ipykernel>=6",
+        "pydantic>=2",
+        "pyzmq>=26",
+        "ruff>=0.11",
+        "uvicorn>=0.32",
+    ]
+
+    commands: list[str] = [
+        "apt-get update",
+        "apt-get install -y "
+        + "libpq-dev pkg-config cmake git curl wget unzip zip libsqlite3-dev openssh-server vim ffmpeg",
+        _install_cuda_command(),
+        # Install uv since it's faster than pip for installing packages.
+        "pip install uv",
+        # https://github.com/astral-sh/uv/issues/11480
+        "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu129",
+        f"uv pip install --system {shlex.join(sorted(environment_packages))}",
+        f"uv pip install --system {shlex.join(sorted(kernelshim_packages))}",
+    ]
+
+    def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
+        return DockerfileSpec(
+            commands=[
+                "FROM base",
+                *(f"RUN {cmd}" for cmd in commands),
+                "ENV PATH=/usr/local/cuda/bin:$PATH",
+            ],
+            context_files={},
+        )
+
+    return _Image._from_args(
+        base_images={"base": base_image},
+        dockerfile_function=build_dockerfile,
+        force_build=force_build,
+        _namespace=api_pb2.DEPLOYMENT_NAMESPACE_GLOBAL,
+    )
+
+
+@synchronizer.create_blocking
+async def image_delete(
+    image_id: str,
     *,
-    min_containers: Optional[int] = None,
-    max_containers: Optional[int] = None,
-    buffer_containers: Optional[int] = None,
-    scaledown_window: Optional[int] = None,
     client: Optional[_Client] = None,
 ) -> None:
-    """Update the autoscaler settings for a Function or Obj (instance of a Cls).
+    """Delete an Image by its ID.
+
+    Deletion is irreversible and will prevent Apps from using the Image.
 
     This is an experimental interface for a feature that we will be adding to
-    replace the existing `.keep_warm()` method. The stable form of this interface
-    may look different (i.e., it may be a standalone function or a method).
+    the main Image class. The stable form of this interface may look different.
 
+    Note: When building an Image, each chained method call will create an
+    intermediate Image layer, each with its own ID. Deleting an Image will not
+    delete any of its intermediate layers, only the image identified by the
+    provided ID.
     """
-    deprecation_warning(
-        (2025, 5, 5),
-        "The modal.experimental.update_autoscaler(...) function is now deprecated in favor of"
-        " a stable `.update_autoscaler(...) method on the corresponding object.",
-        show_source=True,
-    )
-
-    settings = api_pb2.AutoscalerSettings(
-        min_containers=min_containers,
-        max_containers=max_containers,
-        buffer_containers=buffer_containers,
-        scaledown_window=scaledown_window,
-    )
-
     if client is None:
         client = await _Client.from_env()
 
-    if isinstance(obj, _Function):
-        f = obj
-    else:
-        assert obj._cls._class_service_function is not None
-        await obj._cls._class_service_function.hydrate(client=client)
-        f = obj._cached_service_function()
-    await f.hydrate(client=client)
-
-    request = api_pb2.FunctionUpdateSchedulingParamsRequest(function_id=f.object_id, settings=settings)
-    await retry_transient_errors(client.stub.FunctionUpdateSchedulingParams, request)
+    req = api_pb2.ImageDeleteRequest(image_id=image_id)
+    await client.stub.ImageDelete(req)