modal.dict
modal.dict.Dict
class Dict(modal.object.Provider)
A distributed dictionary available to Modal apps.
Keys and values can be essentially any object, so long as it can be
serialized by cloudpickle
, including Modal objects.
Lifetime of dictionary and its items
A Dict
’s lifetime matches the lifetime of the app it’s attached to, but invididual keys expire after 30 days.
Because of this, Dict
s are best used as a cache and not relied on for persistent storage.
On app completion or after stopping an app any associated Dict
objects are cleaned up.
Usage
This is the constructor object, used only to attach a DictHandle
to an app.
To interact with Dict
contents, use DictHandle
objects that are attached
to the live app once an app is running.
import modal
stub = modal.Stub()
stub.some_dict = modal.Dict()
# stub.some_dict["message"] = "hello world" # TypeError!
if __name__ == "__main__":
with stub.run() as app:
handle = app.some_dict
handle["message"] = "hello world" # OK ✔️
def __init__(self, data={}):
Create a new dictionary, optionally filled with initial data.
persist
@typechecked
def persist(self, label: str, namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE):
Deploy a Modal app containing this object. This object can then be imported from other apps using
the returned reference, or by calling modal.SharedVolume.from_name(label)
(or the equivalent method
on respective class).
Example Usage
import modal
volume = modal.SharedVolume().persist("my-volume")
stub = modal.Stub()
# Volume refers to the same object, even across instances of `stub`.
@stub.function(shared_volumes={"/vol": volume})
def f():
pass
from_name
@classmethod
def from_name(
cls: Type[P],
app_name: str,
tag: Optional[str] = None,
namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
) -> P:
Returns a reference to an Modal object of any type
Useful for referring to already created/deployed objects, e.g., Secrets
import modal
stub = modal.Stub()
@stub.function(secret=modal.Secret.from_name("my-secret-name"))
def some_function():
pass
lookup
@classmethod
def lookup(
cls: Type[P],
app_name: str,
tag: Optional[str] = None,
namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
client: Optional[_Client] = None,
) -> H:
General purpose method to retrieve Modal objects such as functions, shared volumes, and secrets.
import modal
square = modal.Function.lookup("my-shared-app", "square")
assert square(3) == 9
vol = modal.SharedVolume.lookup("my-shared-volume")
for chunk in vol.read_file("my_db_dump.csv"):
...
modal.dict.DictHandle
class DictHandle(modal.object.Handle)
Handle for interacting with the contents of a Dict
stub.some_dict = modal.Dict()
if __name__ == "__main__":
with stub.run() as app:
app.some_dict["message"] = "hello world"
def __init__(self):
is_hydrated
def is_hydrated(self) -> bool:
# A hydrated Handle is fully functional and linked to a live object in an app
# To hydrate Handles, run an app using stub.run() or look up the object from a running app using <HandleClass>.lookup()
from_id
@classmethod
def from_id(cls: Type[H], object_id: str, client: Optional[_Client] = None) -> H:
Get an object of this type from a unique object id (retrieved from obj.object_id
)
object_id
@property
def object_id(self) -> str:
A unique object id for this instance. Can be used to retrieve the object using .from_id()
from_app
@classmethod
def from_app(
cls: Type[H],
app_name: str,
tag: Optional[str] = None,
namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
client: Optional[_Client] = None,
) -> H:
Returns a handle to a tagged object in a deployment on Modal.
get
def get(self, key: Any) -> Any:
Get the value associated with the key.
Raises KeyError
if the key does not exist.
contains
def contains(self, key: Any) -> bool:
Check if the key exists.
len
def len(self) -> int:
Returns the length of the dictionary, including any expired keys.
update
def update(self, **kwargs) -> None:
Update the dictionary with additional items.
put
def put(self, key: Any, value: Any) -> None:
Add a specific key-value pair in the dictionary.
pop
def pop(self, key: Any) -> Any:
Remove a key from the dictionary, returning the value if it exists.