modal 0.62.115__py3-none-any.whl → 0.72.13__py3-none-any.whl

modal/environments.py

@@ -1,14 +1,115 @@
 # Copyright Modal Labs 2023
-from typing import List, Optional
+from dataclasses import dataclass
+from typing import Optional
 
 from google.protobuf.empty_pb2 import Empty
+from google.protobuf.message import Message
 from google.protobuf.wrappers_pb2 import StringValue
 
-from modal.client import _Client
-from modal.config import config
 from modal_proto import api_pb2
 
-from ._utils.async_utils import synchronizer
+from ._resolver import Resolver
+from ._utils.async_utils import synchronize_api, synchronizer
+from ._utils.deprecation import renamed_parameter
+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
+from .object import _Object
+
+
+@dataclass(frozen=True)
+class EnvironmentSettings:
+    image_builder_version: str  # Ideally would be typed with ImageBuilderVersion literal
+    webhook_suffix: str
+
+
+class _Environment(_Object, type_prefix="en"):
+    _settings: EnvironmentSettings
+
+    def __init__(self):
+        """mdmd:hidden"""
+        raise RuntimeError(
+            "`Environment(...)` constructor is not allowed."
+            " Please use `Environment.from_name` or `Environment.lookup` instead."
+        )
+
+    # TODO(michael) Keeping this private for now until we decide what else should be in it
+    # And what the rules should be about updates / mutability
+    # @property
+    # def settings(self) -> EnvironmentSettings:
+    #     return self._settings
+
+    def _hydrate_metadata(self, metadata: Message):
+        # Overridden concrete implementation of base class method
+        assert metadata and isinstance(metadata, api_pb2.EnvironmentMetadata)
+        # TODO(michael) should probably expose the `name` from the metadata
+        # as the way to discover the name of the "default" environment
+
+        # Is there a simpler way to go Message -> Dataclass?
+        self._settings = EnvironmentSettings(
+            image_builder_version=metadata.settings.image_builder_version,
+            webhook_suffix=metadata.settings.webhook_suffix,
+        )
+
+    @staticmethod
+    @renamed_parameter((2024, 12, 18), "label", "name")
+    async def from_name(
+        name: str,
+        create_if_missing: bool = False,
+    ):
+        if name:
+            # Allow null names for the case where we want to look up the "default" environment,
+            # which is defined by the server. It feels messy to have "from_name" without a name, though?
+            # We're adding this mostly for internal use right now. We could consider an environment-only
+            # alternate constructor, like `Environment.get_default`, rather than exposing "unnamed"
+            # 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]):
+            request = api_pb2.EnvironmentGetOrCreateRequest(
+                deployment_name=name,
+                object_creation_type=(
+                    api_pb2.OBJECT_CREATION_TYPE_CREATE_IF_MISSING
+                    if create_if_missing
+                    else api_pb2.OBJECT_CREATION_TYPE_UNSPECIFIED
+                ),
+            )
+            response = await retry_transient_errors(resolver.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
+    @renamed_parameter((2024, 12, 18), "label", "name")
+    async def lookup(
+        name: str,
+        client: Optional[_Client] = None,
+        create_if_missing: bool = False,
+    ):
+        obj = await _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)
+
+
+# Needs to be after definition; synchronicity interferes with forward references?
+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.lookup(name, client)
+    ENVIRONMENT_CACHE[name] = environment
+    return environment
 
 
 @synchronizer.create_blocking
@@ -53,7 +154,7 @@ async def create_environment(name: str, client: Optional[_Client] = None):
 
 
 @synchronizer.create_blocking
-async def list_environments(client: Optional[_Client] = None) -> List[api_pb2.EnvironmentListItem]:
+async def list_environments(client: Optional[_Client] = None) -> list[api_pb2.EnvironmentListItem]:
     if client is None:
         client = await _Client.from_env()
     resp = await client.stub.EnvironmentList(Empty())

modal/environments.pyi

@@ -1,47 +1,99 @@
+import google.protobuf.message
 import modal.client
+import modal.object
 import modal_proto.api_pb2
 import typing
 import typing_extensions
 
-class __delete_environment_spec(typing_extensions.Protocol):
-    def __call__(self, name: str, client: typing.Union[modal.client.Client, None] = None):
-        ...
+class EnvironmentSettings:
+    image_builder_version: str
+    webhook_suffix: str
 
-    async def aio(self, *args, **kwargs):
-        ...
+    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): ...
 
-delete_environment: __delete_environment_spec
+class _Environment(modal.object._Object):
+    _settings: EnvironmentSettings
 
+    def __init__(self): ...
+    def _hydrate_metadata(self, metadata: google.protobuf.message.Message): ...
+    @staticmethod
+    async 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
+    ): ...
 
-class __update_environment_spec(typing_extensions.Protocol):
-    def __call__(self, current_name: str, *, new_name: typing.Union[str, None] = None, new_web_suffix: typing.Union[str, None] = None, client: typing.Union[modal.client.Client, None] = None):
-        ...
+class Environment(modal.object.Object):
+    _settings: EnvironmentSettings
 
-    async def aio(self, *args, **kwargs):
-        ...
+    def __init__(self): ...
+    def _hydrate_metadata(self, metadata: google.protobuf.message.Message): ...
 
-update_environment: __update_environment_spec
+    class __from_name_spec(typing_extensions.Protocol):
+        def __call__(self, name: str, create_if_missing: bool = False): ...
+        async def aio(self, name: str, create_if_missing: bool = False): ...
 
+    from_name: __from_name_spec
 
-class __create_environment_spec(typing_extensions.Protocol):
-    def __call__(self, name: str, client: typing.Union[modal.client.Client, None] = None):
-        ...
+    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
+        ): ...
 
-    async def aio(self, *args, **kwargs):
-        ...
+    lookup: __lookup_spec
 
-create_environment: __create_environment_spec
+async def _get_environment_cached(name: str, client: modal.client._Client) -> _Environment: ...
 
+class __delete_environment_spec(typing_extensions.Protocol):
+    def __call__(self, name: str, client: typing.Optional[modal.client.Client] = None): ...
+    async def aio(self, name: str, client: typing.Optional[modal.client.Client] = None): ...
 
-class __list_environments_spec(typing_extensions.Protocol):
-    def __call__(self, client: typing.Union[modal.client.Client, None] = None) -> typing.List[modal_proto.api_pb2.EnvironmentListItem]:
-        ...
+delete_environment: __delete_environment_spec
 
-    async def aio(self, *args, **kwargs) -> typing.List[modal_proto.api_pb2.EnvironmentListItem]:
-        ...
+class __update_environment_spec(typing_extensions.Protocol):
+    def __call__(
+        self,
+        current_name: str,
+        *,
+        new_name: typing.Optional[str] = None,
+        new_web_suffix: typing.Optional[str] = None,
+        client: typing.Optional[modal.client.Client] = None,
+    ): ...
+    async def aio(
+        self,
+        current_name: str,
+        *,
+        new_name: typing.Optional[str] = None,
+        new_web_suffix: typing.Optional[str] = None,
+        client: typing.Optional[modal.client.Client] = None,
+    ): ...
+
+update_environment: __update_environment_spec
+
+class __create_environment_spec(typing_extensions.Protocol):
+    def __call__(self, name: str, client: typing.Optional[modal.client.Client] = None): ...
+    async def aio(self, name: str, client: typing.Optional[modal.client.Client] = None): ...
+
+create_environment: __create_environment_spec
+
+class __list_environments_spec(typing_extensions.Protocol):
+    def __call__(
+        self, client: typing.Optional[modal.client.Client] = None
+    ) -> list[modal_proto.api_pb2.EnvironmentListItem]: ...
+    async def aio(
+        self, client: typing.Optional[modal.client.Client] = None
+    ) -> list[modal_proto.api_pb2.EnvironmentListItem]: ...
 
 list_environments: __list_environments_spec
 
+def ensure_env(environment_name: typing.Optional[str] = None) -> str: ...
 
-def ensure_env(environment_name: typing.Union[str, None] = None) -> str:
-    ...
+ENVIRONMENT_CACHE: dict[str, _Environment]

modal/exception.py

@@ -1,10 +1,6 @@
 # Copyright Modal Labs 2022
 import random
 import signal
-import sys
-import warnings
-from datetime import date
-from typing import Tuple
 
 
 class Error(Exception):
@@ -58,6 +54,10 @@ class InteractiveTimeoutError(TimeoutError):
     """Raised when interactive frontends time out while trying to connect to a container."""
 
 
+class OutputExpiredError(TimeoutError):
+    """Raised when the Output exceeds expiration and times out."""
+
+
 class AuthError(Error):
     """Raised when a client has missing or invalid authentication."""
 
@@ -86,6 +86,14 @@ class DeserializationError(Error):
     """Raised to provide more context when an error is encountered during deserialization."""
 
 
+class SerializationError(Error):
+    """Raised to provide more context when an error is encountered during serialization."""
+
+
+class RequestSizeError(Error):
+    """Raised when an operation produces a gRPC request that is rejected by the server for being too large."""
+
+
 class DeprecationError(UserWarning):
     """UserWarning category emitted when a deprecated Modal feature or API is used."""
 
@@ -96,6 +104,16 @@ class PendingDeprecationError(UserWarning):
     """Soon to be deprecated feature. Only used intermittently because of multi-repo concerns."""
 
 
+class ServerWarning(UserWarning):
+    """Warning originating from the Modal server and re-issued in client code."""
+
+
+class InternalFailure(Error):
+    """
+    Retriable internal error.
+    """
+
+
 class _CliUserExecutionError(Exception):
     """mdmd:hidden
     Private wrapper for exceptions during when importing or running stubs from the CLI.
@@ -111,45 +129,6 @@ class _CliUserExecutionError(Exception):
         self.user_source = user_source
 
 
-# TODO(erikbern): we have something similready in function_utils.py
-_INTERNAL_MODULES = ["modal", "synchronicity"]
-
-
-def _is_internal_frame(frame):
-    module = frame.f_globals["__name__"].split(".")[0]
-    return module in _INTERNAL_MODULES
-
-
-def deprecation_error(deprecated_on: Tuple[int, int, int], msg: str):
-    raise DeprecationError(f"Deprecated on {date(*deprecated_on)}: {msg}")
-
-
-def deprecation_warning(
-    deprecated_on: Tuple[int, int, int], msg: str, *, pending: bool = False, show_source: bool = True
-) -> None:
-    """Utility for getting the proper stack entry.
-
-    See the implementation of the built-in [warnings.warn](https://docs.python.org/3/library/warnings.html#available-functions).
-    """
-    filename, lineno = "<unknown>", 0
-    if show_source:
-        # Find the last non-Modal line that triggered the warning
-        try:
-            frame = sys._getframe()
-            while frame is not None and _is_internal_frame(frame):
-                frame = frame.f_back
-            filename = frame.f_code.co_filename
-            lineno = frame.f_lineno
-        except ValueError:
-            # Use the defaults from above
-            pass
-
-    warning_cls: type = PendingDeprecationError if pending else DeprecationError
-
-    # This is a lower-level function that warnings.warn uses
-    warnings.warn_explicit(f"{date(*deprecated_on)}: {msg}", warning_cls, filename, lineno)
-
-
 def _simulate_preemption_interrupt(signum, frame):
     signal.alarm(30)  # simulate a SIGKILL after 30s
     raise KeyboardInterrupt("Simulated preemption interrupt from modal-client!")
@@ -198,3 +177,11 @@ class InputCancellation(BaseException):
 
 class ModuleNotMountable(Exception):
     pass
+
+
+class ClientClosed(Error):
+    pass
+
+
+class FilesystemExecutionError(Error):
+    """Raised when an unknown error is thrown during a container filesystem operation."""

modal/experimental.py

@@ -1,9 +1,69 @@
 # Copyright Modal Labs 2022
-from ._container_io_manager import _ContainerIOManager
+from typing import (
+    Any,
+    Callable,
+)
+
+import modal._clustered_functions
+from modal.functions import _Function
+
+from ._runtime.container_io_manager import _ContainerIOManager
+from .exception import (
+    InvalidError,
+)
+from .partial_function import _PartialFunction, _PartialFunctionFlags
 
 
 def stop_fetching_inputs():
     """Don't fetch any more inputs from the server, after the current one.
     The container will exit gracefully after the current input is processed."""
-
     _ContainerIOManager.stop_fetching_inputs()
+
+
+def get_local_input_concurrency():
+    """Get the container's local input concurrency.
+    If recently reduced to particular value, it can return a larger number than
+    set due to in-progress inputs."""
+    return _ContainerIOManager.get_input_concurrency()
+
+
+def set_local_input_concurrency(concurrency: int):
+    """Set the container's local input concurrency. Dynamic concurrency will be disabled.
+    When setting to a smaller value, this method will not interrupt in-progress inputs.
+    """
+    _ContainerIOManager.set_input_concurrency(concurrency)
+
+
+def clustered(size: int, broadcast: bool = True):
+    """Provision clusters of colocated and networked containers for the Function.
+
+    Parameters:
+    size: int
+        Number of containers spun up to handle each input.
+    broadcast: bool = True
+        If True, inputs will be sent simultaneously to each container. Otherwise,
+        inputs will be sent only to the rank-0 container, which is responsible for
+        delegating to the workers.
+    """
+
+    assert broadcast, "broadcast=False has not been implemented yet!"
+
+    if size <= 0:
+        raise ValueError("cluster size must be greater than 0")
+
+    def wrapper(raw_f: Callable[..., Any]) -> _PartialFunction:
+        if isinstance(raw_f, _Function):
+            raw_f = raw_f.get_raw_f()
+            raise InvalidError(
+                f"Applying decorators for {raw_f} in the wrong order!\nUsage:\n\n"
+                "@app.function()\n@modal.clustered()\ndef clustered_function():\n    ..."
+            )
+        return _PartialFunction(
+            raw_f, _PartialFunctionFlags.FUNCTION | _PartialFunctionFlags.CLUSTERED, cluster_size=size
+        )
+
+    return wrapper
+
+
+def get_cluster_info() -> modal._clustered_functions.ClusterInfo:
+    return modal._clustered_functions.get_cluster_info()