modal 1.1.5.dev66__py3-none-any.whl → 1.3.1.dev8__py3-none-any.whl

modal/exception.py

@@ -1,7 +1,45 @@
 # Copyright Modal Labs 2022
+"""
+Modal-specific exception types.
+
+## Notes on `grpclib.GRPCError` migration
+
+Historically, the Modal SDK could propagate `grpclib.GRPCError` exceptions out
+to user code.  As of v1.3, we are in the process of gracefully migrating to
+always raising a Modal exception type in these cases. To avoid breaking user
+code that relies on catching `grpclib.GRPCError`, a subset of Modal exception
+types temporarily inherit from `grpclib.GRPCError`.
+
+We encourage users to migrate any code that currently catches `grpclib.GRPCError`
+to instead catch the appropriate Modal exception type. The following mapping
+between GRPCError status codes and Modal exception types is currently in use:
+
+```
+CANCELLED -> ServiceError
+UNKNOWN -> ServiceError
+INVALID_ARGUMENT -> InvalidError
+DEADLINE_EXCEEDED -> ServiceError
+NOT_FOUND -> NotFoundError
+ALREADY_EXISTS -> AlreadyExistsError
+PERMISSION_DENIED -> PermissionDeniedError
+RESOURCE_EXHAUSTED -> ResourceExhaustedError
+FAILED_PRECONDITION -> ConflictError
+ABORTED -> ConflictError
+OUT_OF_RANGE -> InvalidError
+UNIMPLEMENTED -> UnimplementedError
+INTERNAL -> InternalError
+UNAVAILABLE -> ServiceError
+DATA_LOSS -> DataLossError
+UNAUTHENTICATED -> AuthError
+```
+
+"""
+
 import random
 import signal
+from typing import Any, Optional
 
+import grpclib
 import synchronicity.exceptions
 
 UserCodeException = synchronicity.exceptions.UserCodeException  # Deprecated type used for return_exception wrapping
@@ -26,10 +64,116 @@ class Error(Exception):
     """
 
 
-class AlreadyExistsError(Error):
+class _GRPCErrorWrapper(grpclib.GRPCError):
+    """This transitional class helps us migrate away from propagating `grpclib.GRPCError` to users.
+
+    It serves two purposes:
+    - It avoids abruptly breaking user code that catches `grpclib.GRPCError`
+    - It actively warns when users access attributes defined by `grpclib.GRPCError`
+
+    This won't catch all cases (users might react indiscriminately to GRPCError without checking the status).
+
+    The mapping between GRPCError status codes and our error types is defined in `modal._grpc_client`.
+
+    """
+
+    # These will be set on the instance in our error handling middleware
+    _grpc_message: str
+    _grpc_status: grpclib.Status
+    _grpc_details: Any
+
+    def __init__(self, message: Optional[str] = None):
+        # Override GRPCError's init and repr to behave more like a regular Exception
+        # (We don't customize these anywhere in our custom error types currently).
+        self._message = message or ""
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._message!r})"
+
+    def _warn_on_grpc_error_attribute_access(self) -> None:
+        from ._utils.deprecation import deprecation_warning  # Avoid circular import
+
+        exc_type = type(self).__name__
+        deprecation_warning(
+            (2025, 12, 9),
+            "Modal will stop propagating the `grpclib.GRPCError` type in the future. "
+            f"Update your code so that it catches `modal.exception.{exc_type}` directly "
+            "to avoid changes to error handling behavior in the future.",
+            pending=True,
+        )
+
+    @property
+    def message(self) -> str:
+        self._warn_on_grpc_error_attribute_access()
+        return self._grpc_message
+
+    @message.setter
+    def message(self, value: str) -> None:
+        self._grpc_message = value
+
+    @property
+    def status(self) -> grpclib.Status:
+        self._warn_on_grpc_error_attribute_access()
+        return self._grpc_status
+
+    @status.setter
+    def status(self, value: grpclib.Status) -> None:
+        self._grpc_status = value
+
+    @property
+    def details(self) -> Any:
+        self._warn_on_grpc_error_attribute_access()
+        return self._grpc_details
+
+    @details.setter
+    def details(self, value: Any) -> None:
+        self._grpc_details = value
+
+
+class AlreadyExistsError(Error, _GRPCErrorWrapper):
     """Raised when a resource creation conflicts with an existing resource."""
 
 
+class AuthError(Error, _GRPCErrorWrapper):
+    """Raised when a client has missing or invalid authentication."""
+
+
+class InternalError(Error, _GRPCErrorWrapper):
+    """Raised when an internal error occurs in the Modal system."""
+
+
+class InvalidError(Error, _GRPCErrorWrapper):
+    """Raised when user does something invalid."""
+
+
+class ConflictError(InvalidError, _GRPCErrorWrapper):
+    """Raised when a resource conflict occurs between the request and current system state."""
+
+
+class DataLossError(Error, _GRPCErrorWrapper):
+    """Raised when data is lost or corrupted."""
+
+
+class NotFoundError(Error, _GRPCErrorWrapper):
+    """Raised when a requested resource was not found."""
+
+
+class PermissionDeniedError(Error, _GRPCErrorWrapper):
+    """Raised when a user does not have permission to perform the requested operation."""
+
+
+class ResourceExhaustedError(Error, _GRPCErrorWrapper):
+    """Raised when a server-side resource has been exhausted, e.g. a quota or rate limit."""
+
+
+class ServiceError(Error, _GRPCErrorWrapper):
+    """Raised when an error occurs in basic client/server communication."""
+
+
+class UnimplementedError(Error, _GRPCErrorWrapper):
+    """Raised when a requested operation is not implemented or not supported."""
+
+
 class RemoteError(Error):
     """Raised when an error occurs on the Modal server."""
 
@@ -42,6 +186,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."""
 
@@ -66,26 +214,14 @@ class OutputExpiredError(TimeoutError):
     """Raised when the Output exceeds expiration and times out."""
 
 
-class AuthError(Error):
-    """Raised when a client has missing or invalid authentication."""
-
-
 class ConnectionError(Error):
     """Raised when an issue occurs while connecting to the Modal servers."""
 
 
-class InvalidError(Error):
-    """Raised when user does something invalid."""
-
-
 class VersionError(Error):
     """Raised when the current client version of Modal is unsupported."""
 
 
-class NotFoundError(Error):
-    """Raised when a requested resource was not found."""
-
-
 class ExecutionError(Error):
     """Raised when something unexpected happened during runtime."""
 
@@ -116,10 +252,12 @@ class ServerWarning(UserWarning):
     """Warning originating from the Modal server and re-issued in client code."""
 
 
+class AsyncUsageWarning(UserWarning):
+    """Warning emitted when a blocking Modal interface is used in an async context."""
+
+
 class InternalFailure(Error):
-    """
-    Retriable internal error.
-    """
+    """Retriable internal error."""
 
 
 class _CliUserExecutionError(Exception):

modal/experimental/__init__.py

@@ -13,15 +13,18 @@ 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 _Cls, _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
+from .flash import (  # noqa: F401
+    flash_forward,
+    flash_get_containers,
+    flash_prometheus_autoscaler,
+    http_server,
+)
 
 
 def stop_fetching_inputs():
@@ -87,6 +90,19 @@ async def list_deployed_apps(environment_name: str = "", client: Optional[_Clien
     return app_infos
 
 
+@synchronizer.create_blocking
+async def stop_app(name: str, *, environment_name: Optional[str] = None, client: Optional[_Client] = None) -> None:
+    """Stop a deployed App.
+
+    This interface is experimental and may change in the future,
+    although the functionality will continue to be supported.
+    """
+    client_ = client or await _Client.from_env()
+    app = await _App.lookup(name, environment_name=environment_name, client=client_)
+    req = api_pb2.AppStopRequest(app_id=app.app_id, source=api_pb2.APP_STOP_SOURCE_PYTHON_CLIENT)
+    await client_.stub.AppStop(req)
+
+
 @synchronizer.create_blocking
 async def get_app_objects(
     app_name: str, *, environment_name: Optional[str] = None, client: Optional[_Client] = None
@@ -117,7 +133,7 @@ async def get_app_objects(
 
     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 retry_transient_errors(client.stub.AppGetLayout, req)
+    app_layout_resp = await client.stub.AppGetLayout(req)
 
     app_objects: dict[str, Union[_Function, _Cls]] = {}
 
@@ -340,52 +356,6 @@ async def notebook_base_image(*, python_version: Optional[str] = None, force_bui
     )
 
 
-@synchronizer.create_blocking
-async def update_autoscaler(
-    obj: Union[_Function, _Obj],
-    *,
-    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).
-
-    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).
-
-    """
-    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)
-
-
 @synchronizer.create_blocking
 async def image_delete(
     image_id: str,
@@ -394,7 +364,8 @@ async def image_delete(
 ) -> None:
     """Delete an Image by its ID.
 
-    Deletion is irreversible and will prevent Apps from using the Image.
+    Deletion is irreversible and will prevent Functions/Sandboxes from using
+    the Image.
 
     This is an experimental interface for a feature that we will be adding to
     the main Image class. The stable form of this interface may look different.
@@ -408,4 +379,4 @@ async def image_delete(
         client = await _Client.from_env()
 
     req = api_pb2.ImageDeleteRequest(image_id=image_id)
-    await retry_transient_errors(client.stub.ImageDelete, req)
+    await client.stub.ImageDelete(req)