Polish: add docstring, return self

modal/object.py

@@ -5,6 +5,7 @@
 from typing import Callable, ClassVar, Optional, TypeVar
 
 from google.protobuf.message import Message
+from typing_extensions import Self
 
 from modal._utils.async_utils import aclosing
 
@@ -234,11 +235,16 @@ async def resolve(self, client: Optional[_Client] = None):
             " will lazily hydrate when needed.",
             show_source=False,  # synchronicity interferes with attributing source correctly
         )
-        return await self.hydrate(client)
+        await self.hydrate(client)
 
-    async def hydrate(self, client: Optional[_Client] = None):
-        # TODO Add docstring
-        # TODO should this return self so that you can chain it for very eager hydration?
+    async def hydrate(self, client: Optional[_Client] = None) -> Self:
+        """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.
+
+        """
         if self._is_hydrated:
             # memory snapshots capture references which must be rehydrated
             # on restore to handle staleness.
@@ -250,15 +256,15 @@ async def hydrate(self, client: Optional[_Client] = None):
                 await resolver.load(self)
                 self._is_rehydrated = True
                 logger.debug(f"rehydrated {self} with client {id(c)}")
-            return
         elif not self._hydrate_lazily:
-            # TODO can remove _hydrate lazily? I think all objects support it now?
+            # TODO(michael) can remove _hydrate lazily? I think all objects support it now?
             self._validate_is_hydrated()
         else:
             # TODO: this client and/or resolver can't be changed by a caller to X.from_name()
             c = client if client is not None else await _Client.from_env()
             resolver = Resolver(c)
             await resolver.load(self)
+        return self
 
 
 Object = synchronize_api(_Object, target_module=__name__)

test/object_test.py

@@ -23,8 +23,7 @@ def test_new_hydrated(client):
 
 
 def test_on_demand_hydration(client):
-    obj = Dict.from_name("test-dict", create_if_missing=True)
-    obj.hydrate(client)
+    obj = Dict.from_name("test-dict", create_if_missing=True).hydrate(client)
     assert obj.object_id is not None