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

modal/object.py

@@ -1,24 +1,27 @@
 # Copyright Modal Labs 2022
 import uuid
+from collections.abc import Awaitable, Hashable, Sequence
 from functools import wraps
-from typing import Awaitable, Callable, ClassVar, Dict, Hashable, List, Optional, Type, TypeVar
+from typing import Callable, ClassVar, Optional, TypeVar
 
 from google.protobuf.message import Message
 
+from modal._utils.async_utils import aclosing
+
 from ._resolver import Resolver
 from ._utils.async_utils import synchronize_api
 from .client import _Client
-from .config import config
+from .config import config, logger
 from .exception import ExecutionError, InvalidError
 
 O = TypeVar("O", bound="_Object")
 
 _BLOCKING_O = synchronize_api(O)
 
-EPHEMERAL_OBJECT_HEARTBEAT_SLEEP = 300
+EPHEMERAL_OBJECT_HEARTBEAT_SLEEP: int = 300
 
 
-def _get_environment_name(environment_name: Optional[str], resolver: Optional[Resolver] = None) -> Optional[str]:
+def _get_environment_name(environment_name: Optional[str] = None, resolver: Optional[Resolver] = None) -> Optional[str]:
     if environment_name:
         return environment_name
     elif resolver and resolver.environment_name:
@@ -29,7 +32,7 @@ def _get_environment_name(environment_name: Optional[str], resolver: Optional[Re
 
 class _Object:
     _type_prefix: ClassVar[Optional[str]] = None
-    _prefix_to_type: ClassVar[Dict[str, type]] = {}
+    _prefix_to_type: ClassVar[dict[str, type]] = {}
 
     # For constructors
     _load: Optional[Callable[[O, Resolver, Optional[str]], Awaitable[None]]]
@@ -37,13 +40,14 @@ class _Object:
     _rep: str
     _is_another_app: bool
     _hydrate_lazily: bool
-    _deps: Optional[Callable[..., List["_Object"]]]
+    _deps: Optional[Callable[..., list["_Object"]]]
     _deduplication_key: Optional[Callable[[], Awaitable[Hashable]]] = None
 
     # For hydrated objects
     _object_id: str
     _client: _Client
     _is_hydrated: bool
+    _is_rehydrated: bool
 
     @classmethod
     def __init_subclass__(cls, type_prefix: Optional[str] = None):
@@ -62,7 +66,7 @@ class _Object:
         is_another_app: bool = False,
         preload: Optional[Callable[[O, Resolver, Optional[str]], Awaitable[None]]] = None,
         hydrate_lazily: bool = False,
-        deps: Optional[Callable[..., List["_Object"]]] = None,
+        deps: Optional[Callable[..., list["_Object"]]] = None,
         deduplication_key: Optional[Callable[[], Awaitable[Hashable]]] = None,
     ):
         self._local_uuid = str(uuid.uuid4())
@@ -77,6 +81,7 @@ class _Object:
         self._object_id = None
         self._client = None
         self._is_hydrated = False
+        self._is_rehydrated = False
 
         self._initialize_from_empty()
 
@@ -91,7 +96,9 @@ class _Object:
 
     def _initialize_from_other(self, other):
         # default implementation, can be overriden in subclasses
-        pass
+        self._object_id = other._object_id
+        self._is_hydrated = other._is_hydrated
+        self._client = other._client
 
     def _hydrate(self, object_id: str, client: _Client, metadata: Optional[Message]):
         assert isinstance(object_id, str)
@@ -116,17 +123,25 @@ class _Object:
         # the object_id is already provided by other means
         return
 
-    def _init_from_other(self, other: O):
-        # Transient use case, see Dict, Queue, and SharedVolume
-        self._init(other._rep, other._load, other._is_another_app, other._preload)
+    def _validate_is_hydrated(self: O):
+        if not self._is_hydrated:
+            object_type = self.__class__.__name__.strip("_")
+            if hasattr(self, "_app") and getattr(self._app, "_running_app", "") is None:
+                # The most common cause of this error: e.g., user called a Function without using App.run()
+                reason = ", because the App it is defined on is not running"
+            else:
+                # Technically possible, but with an ambiguous cause.
+                reason = ""
+            raise ExecutionError(
+                f"{object_type} has not been hydrated with the metadata it needs to run on Modal{reason}."
+            )
 
     def clone(self: O) -> O:
         """mdmd:hidden Clone a given hydrated object."""
 
         # Object to clone must already be hydrated, otherwise from_loader is more suitable.
-        assert self._is_hydrated
-
-        obj = _Object.__new__(type(self))
+        self._validate_is_hydrated()
+        obj = type(self).__new__(type(self))
         obj._initialize_from_other(self)
         return obj
 
@@ -138,7 +153,7 @@ class _Object:
         is_another_app: bool = False,
         preload: Optional[Callable[[O, Resolver, Optional[str]], Awaitable[None]]] = None,
         hydrate_lazily: bool = False,
-        deps: Optional[Callable[..., List["_Object"]]] = None,
+        deps: Optional[Callable[..., Sequence["_Object"]]] = None,
         deduplication_key: Optional[Callable[[], Awaitable[Hashable]]] = None,
     ):
         # TODO(erikbern): flip the order of the two first arguments
@@ -146,26 +161,34 @@ class _Object:
         obj._init(rep, load, is_another_app, preload, hydrate_lazily, deps, deduplication_key)
         return obj
 
+    @classmethod
+    def _get_type_from_id(cls: type[O], object_id: str) -> type[O]:
+        parts = object_id.split("-")
+        if len(parts) != 2:
+            raise InvalidError(f"Object id {object_id} has no dash in it")
+        prefix = parts[0]
+        if prefix not in cls._prefix_to_type:
+            raise InvalidError(f"Object prefix {prefix} does not correspond to a type")
+        return cls._prefix_to_type[prefix]
+
+    @classmethod
+    def _is_id_type(cls: type[O], object_id) -> bool:
+        return cls._get_type_from_id(object_id) == cls
+
     @classmethod
     def _new_hydrated(
-        cls: Type[O], object_id: str, client: _Client, handle_metadata: Optional[Message], is_another_app: bool = False
+        cls: type[O], object_id: str, client: _Client, handle_metadata: Optional[Message], is_another_app: bool = False
     ) -> O:
         if cls._type_prefix is not None:
             # This is called directly on a subclass, e.g. Secret.from_id
             if not object_id.startswith(cls._type_prefix + "-"):
                 raise InvalidError(f"Object {object_id} does not start with {cls._type_prefix}")
-            prefix = cls._type_prefix
+            obj_cls = cls
         else:
             # This is called on the base class, e.g. Handle.from_id
-            parts = object_id.split("-")
-            if len(parts) != 2:
-                raise InvalidError(f"Object id {object_id} has no dash in it")
-            prefix = parts[0]
-            if prefix not in cls._prefix_to_type:
-                raise InvalidError(f"Object prefix {prefix} does not correspond to a type")
+            obj_cls = cls._get_type_from_id(object_id)
 
         # Instantiate provider
-        obj_cls = cls._prefix_to_type[prefix]
         obj = _Object.__new__(obj_cls)
         rep = f"Object({object_id})"  # TODO(erikbern): dumb
         obj._init(rep, is_another_app=is_another_app)
@@ -185,7 +208,7 @@ class _Object:
         return self._local_uuid
 
     @property
-    def object_id(self):
+    def object_id(self) -> str:
         """mdmd:hidden"""
         return self._object_id
 
@@ -195,24 +218,30 @@ class _Object:
         return self._is_hydrated
 
     @property
-    def deps(self) -> Callable[..., List["_Object"]]:
+    def deps(self) -> Callable[..., list["_Object"]]:
         """mdmd:hidden"""
         return self._deps if self._deps is not None else lambda: []
 
-    async def resolve(self):
+    async def resolve(self, client: Optional[_Client] = None):
         """mdmd:hidden"""
         if self._is_hydrated:
+            # memory snapshots capture references which must be rehydrated
+            # on restore to handle staleness.
+            if self._client._snapshotted and not self._is_rehydrated:
+                logger.debug(f"rehydrating {self} after snapshot")
+                self._is_hydrated = False  # un-hydrate and re-resolve
+                c = client if client is not None else await _Client.from_env()
+                resolver = Resolver(c)
+                await resolver.load(self)
+                self._is_rehydrated = True
+                logger.debug(f"rehydrated {self} with client {id(c)}")
             return
         elif not self._hydrate_lazily:
-            raise ExecutionError(
-                "Object has not been hydrated and doesn't support lazy hydration."
-                " This might happen if an object is defined on a different stub,"
-                " or if it's on the same stub but it didn't get created because it"
-                " wasn't defined in global scope."
-            )
+            self._validate_is_hydrated()
         else:
             # TODO: this client and/or resolver can't be changed by a caller to X.from_name()
-            resolver = Resolver(await _Client.from_env())
+            c = client if client is not None else await _Client.from_env()
+            resolver = Resolver(c)
             await resolver.load(self)
 
 
@@ -232,7 +261,8 @@ def live_method_gen(method):
     @wraps(method)
     async def wrapped(self, *args, **kwargs):
         await self.resolve()
-        async for item in method(self, *args, **kwargs):
-            yield item
+        async with aclosing(method(self, *args, **kwargs)) as stream:
+            async for item in stream:
+                yield item
 
     return wrapped

modal/object.pyi

@@ -1,3 +1,4 @@
+import collections.abc
 import google.protobuf.message
 import modal._resolver
 import modal.client
@@ -8,189 +9,211 @@ O = typing.TypeVar("O", bound="_Object")
 
 _BLOCKING_O = typing.TypeVar("_BLOCKING_O", bound="Object")
 
-def _get_environment_name(environment_name: typing.Union[str, None], resolver: typing.Union[modal._resolver.Resolver, None] = None) -> typing.Union[str, None]:
-    ...
-
+def _get_environment_name(
+    environment_name: typing.Optional[str] = None, resolver: typing.Optional[modal._resolver.Resolver] = None
+) -> typing.Optional[str]: ...
 
 class _Object:
-    _type_prefix: typing.ClassVar[typing.Union[str, None]]
-    _prefix_to_type: typing.ClassVar[typing.Dict[str, type]]
-    _load: typing.Union[typing.Callable[[O, modal._resolver.Resolver, typing.Union[str, None]], typing.Awaitable[None]], None]
-    _preload: typing.Union[typing.Callable[[O, modal._resolver.Resolver, typing.Union[str, None]], typing.Awaitable[None]], None]
+    _type_prefix: typing.ClassVar[typing.Optional[str]]
+    _prefix_to_type: typing.ClassVar[dict[str, type]]
+    _load: typing.Optional[
+        typing.Callable[[O, modal._resolver.Resolver, typing.Optional[str]], collections.abc.Awaitable[None]]
+    ]
+    _preload: typing.Optional[
+        typing.Callable[[O, modal._resolver.Resolver, typing.Optional[str]], collections.abc.Awaitable[None]]
+    ]
     _rep: str
     _is_another_app: bool
     _hydrate_lazily: bool
-    _deps: typing.Union[typing.Callable[..., typing.List[_Object]], None]
-    _deduplication_key: typing.Union[typing.Callable[[], typing.Awaitable[typing.Hashable]], None]
+    _deps: typing.Optional[typing.Callable[..., list[_Object]]]
+    _deduplication_key: typing.Optional[typing.Callable[[], collections.abc.Awaitable[collections.abc.Hashable]]]
     _object_id: str
     _client: modal.client._Client
     _is_hydrated: bool
+    _is_rehydrated: bool
 
     @classmethod
-    def __init_subclass__(cls, type_prefix: typing.Union[str, None] = None):
-        ...
-
-    def __init__(self, *args, **kwargs):
-        ...
-
-    def _init(self, rep: str, load: typing.Union[typing.Callable[[O, modal._resolver.Resolver, typing.Union[str, None]], typing.Awaitable[None]], None] = None, is_another_app: bool = False, preload: typing.Union[typing.Callable[[O, modal._resolver.Resolver, typing.Union[str, None]], typing.Awaitable[None]], None] = None, hydrate_lazily: bool = False, deps: typing.Union[typing.Callable[..., typing.List[_Object]], None] = None, deduplication_key: typing.Union[typing.Callable[[], typing.Awaitable[typing.Hashable]], None] = None):
-        ...
-
-    def _unhydrate(self):
-        ...
-
-    def _initialize_from_empty(self):
-        ...
-
-    def _initialize_from_other(self, other):
-        ...
-
-    def _hydrate(self, object_id: str, client: modal.client._Client, metadata: typing.Union[google.protobuf.message.Message, None]):
-        ...
-
-    def _hydrate_metadata(self, metadata: typing.Union[google.protobuf.message.Message, None]):
-        ...
-
-    def _get_metadata(self) -> typing.Union[google.protobuf.message.Message, None]:
-        ...
-
-    def _init_from_other(self, other: O):
-        ...
-
-    def clone(self: O) -> O:
-        ...
-
+    def __init_subclass__(cls, type_prefix: typing.Optional[str] = None): ...
+    def __init__(self, *args, **kwargs): ...
+    def _init(
+        self,
+        rep: str,
+        load: typing.Optional[
+            typing.Callable[[O, modal._resolver.Resolver, typing.Optional[str]], collections.abc.Awaitable[None]]
+        ] = None,
+        is_another_app: bool = False,
+        preload: typing.Optional[
+            typing.Callable[[O, modal._resolver.Resolver, typing.Optional[str]], collections.abc.Awaitable[None]]
+        ] = None,
+        hydrate_lazily: bool = False,
+        deps: typing.Optional[typing.Callable[..., list[_Object]]] = None,
+        deduplication_key: typing.Optional[
+            typing.Callable[[], collections.abc.Awaitable[collections.abc.Hashable]]
+        ] = None,
+    ): ...
+    def _unhydrate(self): ...
+    def _initialize_from_empty(self): ...
+    def _initialize_from_other(self, other): ...
+    def _hydrate(
+        self, object_id: str, client: modal.client._Client, metadata: typing.Optional[google.protobuf.message.Message]
+    ): ...
+    def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
+    def _get_metadata(self) -> typing.Optional[google.protobuf.message.Message]: ...
+    def _validate_is_hydrated(self: O): ...
+    def clone(self: O) -> O: ...
     @classmethod
-    def _from_loader(cls, load: typing.Callable[[O, modal._resolver.Resolver, typing.Union[str, None]], typing.Awaitable[None]], rep: str, is_another_app: bool = False, preload: typing.Union[typing.Callable[[O, modal._resolver.Resolver, typing.Union[str, None]], typing.Awaitable[None]], None] = None, hydrate_lazily: bool = False, deps: typing.Union[typing.Callable[..., typing.List[_Object]], None] = None, deduplication_key: typing.Union[typing.Callable[[], typing.Awaitable[typing.Hashable]], None] = None):
-        ...
-
+    def _from_loader(
+        cls,
+        load: typing.Callable[[O, modal._resolver.Resolver, typing.Optional[str]], collections.abc.Awaitable[None]],
+        rep: str,
+        is_another_app: bool = False,
+        preload: typing.Optional[
+            typing.Callable[[O, modal._resolver.Resolver, typing.Optional[str]], collections.abc.Awaitable[None]]
+        ] = None,
+        hydrate_lazily: bool = False,
+        deps: typing.Optional[typing.Callable[..., collections.abc.Sequence[_Object]]] = None,
+        deduplication_key: typing.Optional[
+            typing.Callable[[], collections.abc.Awaitable[collections.abc.Hashable]]
+        ] = None,
+    ): ...
     @classmethod
-    def _new_hydrated(cls: typing.Type[O], object_id: str, client: modal.client._Client, handle_metadata: typing.Union[google.protobuf.message.Message, None], is_another_app: bool = False) -> O:
-        ...
-
-    def _hydrate_from_other(self, other: O):
-        ...
-
-    def __repr__(self):
-        ...
-
+    def _get_type_from_id(cls: type[O], object_id: str) -> type[O]: ...
+    @classmethod
+    def _is_id_type(cls: type[O], object_id) -> bool: ...
+    @classmethod
+    def _new_hydrated(
+        cls: type[O],
+        object_id: str,
+        client: modal.client._Client,
+        handle_metadata: typing.Optional[google.protobuf.message.Message],
+        is_another_app: bool = False,
+    ) -> O: ...
+    def _hydrate_from_other(self, other: O): ...
+    def __repr__(self): ...
     @property
-    def local_uuid(self):
-        ...
-
+    def local_uuid(self): ...
     @property
-    def object_id(self):
-        ...
-
+    def object_id(self) -> str: ...
     @property
-    def is_hydrated(self) -> bool:
-        ...
-
+    def is_hydrated(self) -> bool: ...
     @property
-    def deps(self) -> typing.Callable[..., typing.List[_Object]]:
-        ...
-
-    async def resolve(self):
-        ...
-
+    def deps(self) -> typing.Callable[..., list[_Object]]: ...
+    async def resolve(self, client: typing.Optional[modal.client._Client] = None): ...
 
 class Object:
-    _type_prefix: typing.ClassVar[typing.Union[str, None]]
-    _prefix_to_type: typing.ClassVar[typing.Dict[str, type]]
-    _load: typing.Union[typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Union[str, None]], None], None]
-    _preload: typing.Union[typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Union[str, None]], None], None]
+    _type_prefix: typing.ClassVar[typing.Optional[str]]
+    _prefix_to_type: typing.ClassVar[dict[str, type]]
+    _load: typing.Optional[
+        typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Optional[str]], collections.abc.Awaitable[None]]
+    ]
+    _preload: typing.Optional[
+        typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Optional[str]], collections.abc.Awaitable[None]]
+    ]
     _rep: str
     _is_another_app: bool
     _hydrate_lazily: bool
-    _deps: typing.Union[typing.Callable[..., typing.List[Object]], None]
-    _deduplication_key: typing.Union[typing.Callable[[], typing.Hashable], None]
+    _deps: typing.Optional[typing.Callable[..., list[Object]]]
+    _deduplication_key: typing.Optional[typing.Callable[[], collections.abc.Awaitable[collections.abc.Hashable]]]
     _object_id: str
     _client: modal.client.Client
     _is_hydrated: bool
+    _is_rehydrated: bool
 
-    def __init__(self, *args, **kwargs):
-        ...
-
+    def __init__(self, *args, **kwargs): ...
     @classmethod
-    def __init_subclass__(cls, type_prefix: typing.Union[str, None] = None):
-        ...
+    def __init_subclass__(cls, type_prefix: typing.Optional[str] = None): ...
 
     class ___init_spec(typing_extensions.Protocol):
-        def __call__(self, rep: str, load: typing.Union[typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Union[str, None]], None], None] = None, is_another_app: bool = False, preload: typing.Union[typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Union[str, None]], None], None] = None, hydrate_lazily: bool = False, deps: typing.Union[typing.Callable[..., typing.List[Object]], None] = None, deduplication_key: typing.Union[typing.Callable[[], typing.Hashable], None] = None):
-            ...
-
-        def aio(self, rep: str, load: typing.Union[typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Union[str, None]], typing.Awaitable[None]], None] = None, is_another_app: bool = False, preload: typing.Union[typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Union[str, None]], typing.Awaitable[None]], None] = None, hydrate_lazily: bool = False, deps: typing.Union[typing.Callable[..., typing.List[Object]], None] = None, deduplication_key: typing.Union[typing.Callable[[], typing.Awaitable[typing.Hashable]], None] = None):
-            ...
+        def __call__(
+            self,
+            rep: str,
+            load: typing.Optional[
+                typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Optional[str]], None]
+            ] = None,
+            is_another_app: bool = False,
+            preload: typing.Optional[
+                typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Optional[str]], None]
+            ] = None,
+            hydrate_lazily: bool = False,
+            deps: typing.Optional[typing.Callable[..., list[Object]]] = None,
+            deduplication_key: typing.Optional[typing.Callable[[], collections.abc.Hashable]] = None,
+        ): ...
+        def aio(
+            self,
+            rep: str,
+            load: typing.Optional[
+                typing.Callable[
+                    [_BLOCKING_O, modal._resolver.Resolver, typing.Optional[str]], collections.abc.Awaitable[None]
+                ]
+            ] = None,
+            is_another_app: bool = False,
+            preload: typing.Optional[
+                typing.Callable[
+                    [_BLOCKING_O, modal._resolver.Resolver, typing.Optional[str]], collections.abc.Awaitable[None]
+                ]
+            ] = None,
+            hydrate_lazily: bool = False,
+            deps: typing.Optional[typing.Callable[..., list[Object]]] = None,
+            deduplication_key: typing.Optional[
+                typing.Callable[[], collections.abc.Awaitable[collections.abc.Hashable]]
+            ] = None,
+        ): ...
 
     _init: ___init_spec
 
-    def _unhydrate(self):
-        ...
-
-    def _initialize_from_empty(self):
-        ...
-
-    def _initialize_from_other(self, other):
-        ...
-
-    def _hydrate(self, object_id: str, client: modal.client.Client, metadata: typing.Union[google.protobuf.message.Message, None]):
-        ...
-
-    def _hydrate_metadata(self, metadata: typing.Union[google.protobuf.message.Message, None]):
-        ...
-
-    def _get_metadata(self) -> typing.Union[google.protobuf.message.Message, None]:
-        ...
-
-    def _init_from_other(self, other: _BLOCKING_O):
-        ...
-
-    def clone(self: _BLOCKING_O) -> _BLOCKING_O:
-        ...
-
+    def _unhydrate(self): ...
+    def _initialize_from_empty(self): ...
+    def _initialize_from_other(self, other): ...
+    def _hydrate(
+        self, object_id: str, client: modal.client.Client, metadata: typing.Optional[google.protobuf.message.Message]
+    ): ...
+    def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
+    def _get_metadata(self) -> typing.Optional[google.protobuf.message.Message]: ...
+    def _validate_is_hydrated(self: _BLOCKING_O): ...
+    def clone(self: _BLOCKING_O) -> _BLOCKING_O: ...
     @classmethod
-    def _from_loader(cls, load: typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Union[str, None]], None], rep: str, is_another_app: bool = False, preload: typing.Union[typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Union[str, None]], None], None] = None, hydrate_lazily: bool = False, deps: typing.Union[typing.Callable[..., typing.List[Object]], None] = None, deduplication_key: typing.Union[typing.Callable[[], typing.Hashable], None] = None):
-        ...
-
+    def _from_loader(
+        cls,
+        load: typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Optional[str]], None],
+        rep: str,
+        is_another_app: bool = False,
+        preload: typing.Optional[
+            typing.Callable[[_BLOCKING_O, modal._resolver.Resolver, typing.Optional[str]], None]
+        ] = None,
+        hydrate_lazily: bool = False,
+        deps: typing.Optional[typing.Callable[..., collections.abc.Sequence[Object]]] = None,
+        deduplication_key: typing.Optional[typing.Callable[[], collections.abc.Hashable]] = None,
+    ): ...
     @classmethod
-    def _new_hydrated(cls: typing.Type[_BLOCKING_O], object_id: str, client: modal.client.Client, handle_metadata: typing.Union[google.protobuf.message.Message, None], is_another_app: bool = False) -> _BLOCKING_O:
-        ...
-
-    def _hydrate_from_other(self, other: _BLOCKING_O):
-        ...
-
-    def __repr__(self):
-        ...
-
+    def _get_type_from_id(cls: type[_BLOCKING_O], object_id: str) -> type[_BLOCKING_O]: ...
+    @classmethod
+    def _is_id_type(cls: type[_BLOCKING_O], object_id) -> bool: ...
+    @classmethod
+    def _new_hydrated(
+        cls: type[_BLOCKING_O],
+        object_id: str,
+        client: modal.client.Client,
+        handle_metadata: typing.Optional[google.protobuf.message.Message],
+        is_another_app: bool = False,
+    ) -> _BLOCKING_O: ...
+    def _hydrate_from_other(self, other: _BLOCKING_O): ...
+    def __repr__(self): ...
     @property
-    def local_uuid(self):
-        ...
-
+    def local_uuid(self): ...
     @property
-    def object_id(self):
-        ...
-
+    def object_id(self) -> str: ...
     @property
-    def is_hydrated(self) -> bool:
-        ...
-
+    def is_hydrated(self) -> bool: ...
     @property
-    def deps(self) -> typing.Callable[..., typing.List[Object]]:
-        ...
+    def deps(self) -> typing.Callable[..., list[Object]]: ...
 
     class __resolve_spec(typing_extensions.Protocol):
-        def __call__(self):
-            ...
-
-        async def aio(self, *args, **kwargs):
-            ...
+        def __call__(self, client: typing.Optional[modal.client.Client] = None): ...
+        async def aio(self, client: typing.Optional[modal.client.Client] = None): ...
 
     resolve: __resolve_spec
 
+def live_method(method): ...
+def live_method_gen(method): ...
 
-def live_method(method):
-    ...
-
-
-def live_method_gen(method):
-    ...
+EPHEMERAL_OBJECT_HEARTBEAT_SLEEP: int

modal/output.py

@@ -0,0 +1,63 @@
+# Copyright Modal Labs 2024
+"""Interface to Modal's OutputManager functionality.
+
+These functions live here so that Modal library code can import them without
+transitively importing Rich, as we do in global scope in _output.py. This allows
+us to avoid importing Rich for client code that runs in the container environment.
+
+"""
+import contextlib
+from collections.abc import Generator
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ._output import OutputManager
+
+
+OUTPUT_ENABLED = False
+
+
+@contextlib.contextmanager
+def enable_output(show_progress: bool = True) -> Generator[None, None, None]:
+    """Context manager that enable output when using the Python SDK.
+
+    This will print to stdout and stderr things such as
+    1. Logs from running functions
+    2. Status of creating objects
+    3. Map progress
+
+    Example:
+    ```python
+    app = modal.App()
+    with modal.enable_output():
+        with app.run():
+            ...
+    ```
+    """
+    from ._output import OutputManager
+
+    # Toggle the output flag from within this function so that we can
+    # call _get_output_manager from within the library and only import
+    # the _output module if output is explicitly enabled. That prevents
+    # us from trying to import rich inside a container environment where
+    # it might not be installed. This is sort of hacky and I would prefer
+    # a more thorough refactor where the OutputManager is fully useable
+    # without rich installed, but that's a larger project.
+    global OUTPUT_ENABLED
+
+    try:
+        with OutputManager.enable_output(show_progress):
+            OUTPUT_ENABLED = True
+            yield
+    finally:
+        OUTPUT_ENABLED = False
+
+
+def _get_output_manager() -> Optional["OutputManager"]:
+    """Interface to the OutputManager that returns None when output is not enabled."""
+    if OUTPUT_ENABLED:
+        from ._output import OutputManager
+
+        return OutputManager.get()
+    else:
+        return None