modal 1.1.2.dev11__py3-none-any.whl → 1.1.2.dev13__py3-none-any.whl

modal/dict.py

@@ -2,25 +2,32 @@
 from collections.abc import AsyncIterator, Mapping
 from dataclasses import dataclass
 from datetime import datetime
-from typing import Any, Optional
+from typing import Any, Optional, Union
 
 from google.protobuf.message import Message
 from grpclib import GRPCError
+from synchronicity import classproperty
 from synchronicity.async_wrap import asynccontextmanager
 
 from modal_proto import api_pb2
 
-from ._object import EPHEMERAL_OBJECT_HEARTBEAT_SLEEP, _get_environment_name, _Object, live_method, live_method_gen
+from ._object import (
+    EPHEMERAL_OBJECT_HEARTBEAT_SLEEP,
+    _get_environment_name,
+    _Object,
+    live_method,
+    live_method_gen,
+)
 from ._resolver import Resolver
 from ._serialization import deserialize, serialize
 from ._utils.async_utils import TaskContext, synchronize_api
 from ._utils.deprecation import deprecation_warning, warn_if_passing_namespace
 from ._utils.grpc_utils import retry_transient_errors
 from ._utils.name_utils import check_object_name
-from ._utils.time_utils import timestamp_to_localized_dt
+from ._utils.time_utils import as_timestamp, timestamp_to_localized_dt
 from .client import _Client
 from .config import logger
-from .exception import RequestSizeError
+from .exception import InvalidError, RequestSizeError
 
 
 def _serialize_dict(data):
@@ -29,7 +36,7 @@ def _serialize_dict(data):
 
 @dataclass
 class DictInfo:
-    """Information about the Dict object."""
+    """Information about a Dict object."""
 
     # This dataclass should be limited to information that is unchanging over the lifetime of the Dict,
     # since it is transmitted from the server when the object is hydrated and could be stale when accessed.
@@ -39,6 +46,68 @@ class DictInfo:
     created_by: Optional[str]
 
 
+class _DictManager:
+    """Namespace with methods for managing named Dict objects."""
+
+    @staticmethod
+    async def list(
+        *,
+        max_objects: Optional[int] = None,  # Limit results to this size
+        created_before: Optional[Union[datetime, str]] = None,  # Limit based on creation date
+        environment_name: str = "",  # Uses active environment if not specified
+        client: Optional[_Client] = None,  # Optional client with Modal credentials
+    ) -> list["_Dict"]:
+        """Return a list of hydrated Dict objects.
+
+        **Examples:**
+
+        ```python
+        dicts = modal.Dict.objects.list()
+        print([d.name for d in dicts])
+        ```
+
+        Dicts will be retreived from the active environment, or another one can be specified:
+
+        ```python notest
+        dev_dicts = modal.Dict.objects.list(environment_name="dev")
+        ```
+
+        By default, all named Dict are returned, newest to oldest. It's also possible to limit the
+        number of results and to filter by creation date:
+
+        ```python
+        dicts = modal.Dict.objects.list(max_objects=10, created_before="2025-01-01")
+        ```
+
+        """
+        client = await _Client.from_env() if client is None else client
+        if max_objects is not None and max_objects < 0:
+            raise InvalidError("max_objects cannot be negative")
+
+        items: list[api_pb2.DictListResponse.DictInfo] = []
+
+        async def retrieve_page(created_before: float) -> bool:
+            max_page_size = 100 if max_objects is None else min(100, max_objects - len(items))
+            pagination = api_pb2.ListPagination(max_objects=max_page_size, created_before=created_before)
+            req = api_pb2.DictListRequest(environment_name=environment_name, pagination=pagination)
+            resp = await retry_transient_errors(client.stub.DictList, req)
+            items.extend(resp.dicts)
+            finished = (len(resp.dicts) < max_page_size) or (max_objects is not None and len(items) >= max_objects)
+            return finished
+
+        finished = await retrieve_page(as_timestamp(created_before))
+        while True:
+            if finished:
+                break
+            finished = await retrieve_page(items[-1].metadata.creation_info.created_at)
+
+        dicts = [_Dict._new_hydrated(item.dict_id, client, item.metadata, is_another_app=True) for item in items]
+        return dicts[:max_objects] if max_objects is not None else dicts
+
+
+DictManager = synchronize_api(_DictManager)
+
+
 class _Dict(_Object, type_prefix="di"):
     """Distributed dictionary for storage in Modal apps.
 
@@ -90,6 +159,10 @@ class _Dict(_Object, type_prefix="di"):
             "`Dict(...)` constructor is not allowed. Please use `Dict.from_name` or `Dict.ephemeral` instead"
         )
 
+    @classproperty
+    def objects(cls) -> _DictManager:
+        return _DictManager
+
     @property
     def name(self) -> Optional[str]:
         return self._name

modal/dict.pyi

@@ -5,6 +5,7 @@ import modal._object
 import modal.client
 import modal.object
 import modal_proto.api_pb2
+import synchronicity
 import synchronicity.combined_types
 import typing
 import typing_extensions
@@ -12,7 +13,7 @@ import typing_extensions
 def _serialize_dict(data): ...
 
 class DictInfo:
-    """Information about the Dict object."""
+    """Information about a Dict object."""
 
     name: typing.Optional[str]
     created_at: datetime.datetime
@@ -32,6 +33,115 @@ class DictInfo:
         """Return self==value."""
         ...
 
+class _DictManager:
+    """Namespace with methods for managing named Dict objects."""
+    @staticmethod
+    async def list(
+        *,
+        max_objects: typing.Optional[int] = None,
+        created_before: typing.Union[datetime.datetime, str, None] = None,
+        environment_name: str = "",
+        client: typing.Optional[modal.client._Client] = None,
+    ) -> list[_Dict]:
+        """Return a list of hydrated Dict objects.
+
+        **Examples:**
+
+        ```python
+        dicts = modal.Dict.objects.list()
+        print([d.name for d in dicts])
+        ```
+
+        Dicts will be retreived from the active environment, or another one can be specified:
+
+        ```python notest
+        dev_dicts = modal.Dict.objects.list(environment_name="dev")
+        ```
+
+        By default, all named Dict are returned, newest to oldest. It's also possible to limit the
+        number of results and to filter by creation date:
+
+        ```python
+        dicts = modal.Dict.objects.list(max_objects=10, created_before="2025-01-01")
+        ```
+        """
+        ...
+
+class DictManager:
+    """Namespace with methods for managing named Dict objects."""
+    def __init__(self, /, *args, **kwargs):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    class __list_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            *,
+            max_objects: typing.Optional[int] = None,
+            created_before: typing.Union[datetime.datetime, str, None] = None,
+            environment_name: str = "",
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> list[Dict]:
+            """Return a list of hydrated Dict objects.
+
+            **Examples:**
+
+            ```python
+            dicts = modal.Dict.objects.list()
+            print([d.name for d in dicts])
+            ```
+
+            Dicts will be retreived from the active environment, or another one can be specified:
+
+            ```python notest
+            dev_dicts = modal.Dict.objects.list(environment_name="dev")
+            ```
+
+            By default, all named Dict are returned, newest to oldest. It's also possible to limit the
+            number of results and to filter by creation date:
+
+            ```python
+            dicts = modal.Dict.objects.list(max_objects=10, created_before="2025-01-01")
+            ```
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            *,
+            max_objects: typing.Optional[int] = None,
+            created_before: typing.Union[datetime.datetime, str, None] = None,
+            environment_name: str = "",
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> list[Dict]:
+            """Return a list of hydrated Dict objects.
+
+            **Examples:**
+
+            ```python
+            dicts = modal.Dict.objects.list()
+            print([d.name for d in dicts])
+            ```
+
+            Dicts will be retreived from the active environment, or another one can be specified:
+
+            ```python notest
+            dev_dicts = modal.Dict.objects.list(environment_name="dev")
+            ```
+
+            By default, all named Dict are returned, newest to oldest. It's also possible to limit the
+            number of results and to filter by creation date:
+
+            ```python
+            dicts = modal.Dict.objects.list(max_objects=10, created_before="2025-01-01")
+            ```
+            """
+            ...
+
+    list: __list_spec
+
 class _Dict(modal._object._Object):
     """Distributed dictionary for storage in Modal apps.
 
@@ -81,6 +191,8 @@ class _Dict(modal._object._Object):
         """mdmd:hidden"""
         ...
 
+    @synchronicity.classproperty
+    def objects(cls) -> _DictManager: ...
     @property
     def name(self) -> typing.Optional[str]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
@@ -308,6 +420,8 @@ class Dict(modal.object.Object):
         """mdmd:hidden"""
         ...
 
+    @synchronicity.classproperty
+    def objects(cls) -> DictManager: ...
     @property
     def name(self) -> typing.Optional[str]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...

modal/experimental/__init__.py

@@ -1,5 +1,6 @@
 # Copyright Modal Labs 2025
 import os
+import shlex
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal, Optional, Union
@@ -212,6 +213,109 @@ async def raw_registry_image(
     )
 
 
+@synchronizer.create_blocking
+async def notebook_base_image(*, python_version: Optional[str] = None, force_build: bool = False) -> _Image:
+    """Default image used for Modal notebook kernels, with common libraries.
+
+    This can be used to bootstrap development workflows quickly. We don't
+    recommend using this image for production Modal Functions though, as it may
+    change at any time in the future.
+    """
+    # Include several common packages, as well as kernelshim dependencies (except 'modal').
+    # These packages aren't pinned, so they may change over time with builds.
+    #
+    # We plan to use `--exclude-newer` in the future, with date-specific image builds.
+    base_image = _Image.debian_slim(python_version=python_version)
+
+    environment_packages: list[str] = [
+        "accelerate",
+        "aiohttp",
+        "altair",
+        "anthropic",
+        "asyncpg",
+        "beautifulsoup4",
+        "bokeh",
+        "boto3[crt]",
+        "click",
+        "diffusers[torch,flax]",
+        "dm-sonnet",
+        "flax",
+        "ftfy",
+        "h5py",
+        "urllib3",
+        "httpx",
+        "huggingface-hub",
+        "ipywidgets",
+        "jax[cuda12]",
+        "keras",
+        "matplotlib",
+        "nbformat",
+        "numba",
+        "numpy",
+        "openai",
+        "optax",
+        "pandas",
+        "plotly[express]",
+        "polars",
+        "psycopg2",
+        "requests",
+        "safetensors",
+        "scikit-image",
+        "scikit-learn",
+        "scipy",
+        "seaborn",
+        "sentencepiece",
+        "sqlalchemy",
+        "statsmodels",
+        "sympy",
+        "tabulate",
+        "tensorboard",
+        "toml",
+        "transformers",
+        "triton",
+        "typer",
+        "vega-datasets",
+        "watchfiles",
+        "websockets",
+    ]
+
+    # Kernelshim dependencies. (see NOTEBOOK_KERNELSHIM_DEPENDENCIES)
+    kernelshim_packages: list[str] = [
+        "authlib>=1.3",
+        "basedpyright>=1.28",
+        "fastapi>=0.100",
+        "ipykernel>=6",
+        "pydantic>=2",
+        "pyzmq>=26",
+        "ruff>=0.11",
+        "uvicorn>=0.32",
+    ]
+
+    commands: list[str] = [
+        "apt-get update",
+        "apt-get install -y libpq-dev pkg-config cmake git curl wget unzip zip libsqlite3-dev openssh-server",
+        # Install uv since it's faster than pip for installing packages.
+        "pip install uv",
+        # https://github.com/astral-sh/uv/issues/11480
+        "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126",
+        f"uv pip install --system {shlex.join(sorted(environment_packages))}",
+        f"uv pip install --system {shlex.join(sorted(kernelshim_packages))}",
+    ]
+
+    # TODO: Also install the CUDA Toolkit, so `nvcc` is available.
+    # https://github.com/charlesfrye/cuda-modal/blob/7fef8db12402986cf42d9c8cca8c63d1da6d7700/cuda/use_cuda.py#L158-L188
+
+    def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
+        return DockerfileSpec(commands=["FROM base", *(f"RUN {cmd}" for cmd in commands)], context_files={})
+
+    return _Image._from_args(
+        base_images={"base": base_image},
+        dockerfile_function=build_dockerfile,
+        force_build=force_build,
+        _namespace=api_pb2.DEPLOYMENT_NAMESPACE_GLOBAL,
+    )
+
+
 @synchronizer.create_blocking
 async def update_autoscaler(
     obj: Union[_Function, _Obj],

modal/functions.pyi

@@ -433,7 +433,7 @@ class Function(
 
     _call_generator: ___call_generator_spec[typing_extensions.Self]
 
-    class __remote_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER, SUPERSELF]):
+    class __remote_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER, SUPERSELF]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> ReturnType_INNER:
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
@@ -442,7 +442,7 @@ class Function(
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
 
-    remote: __remote_spec[modal._functions.P, modal._functions.ReturnType, typing_extensions.Self]
+    remote: __remote_spec[modal._functions.ReturnType, modal._functions.P, typing_extensions.Self]
 
     class __remote_gen_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /, *args, **kwargs) -> typing.Generator[typing.Any, None, None]:
@@ -469,7 +469,7 @@ class Function(
         """
         ...
 
-    class ___experimental_spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER, SUPERSELF]):
+    class ___experimental_spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER, SUPERSELF]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """[Experimental] Calls the function with the given arguments, without waiting for the results.
 
@@ -493,7 +493,7 @@ class Function(
             ...
 
     _experimental_spawn: ___experimental_spawn_spec[
-        modal._functions.P, modal._functions.ReturnType, typing_extensions.Self
+        modal._functions.ReturnType, modal._functions.P, typing_extensions.Self
     ]
 
     class ___spawn_map_inner_spec(typing_extensions.Protocol[P_INNER, SUPERSELF]):
@@ -502,7 +502,7 @@ class Function(
 
     _spawn_map_inner: ___spawn_map_inner_spec[modal._functions.P, typing_extensions.Self]
 
-    class __spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER, SUPERSELF]):
+    class __spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER, SUPERSELF]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """Calls the function with the given arguments, without waiting for the results.
 
@@ -523,7 +523,7 @@ class Function(
             """
             ...
 
-    spawn: __spawn_spec[modal._functions.P, modal._functions.ReturnType, typing_extensions.Self]
+    spawn: __spawn_spec[modal._functions.ReturnType, modal._functions.P, typing_extensions.Self]
 
     def get_raw_f(self) -> collections.abc.Callable[..., typing.Any]:
         """Return the inner Python object wrapped by this Modal Function."""

modal/queue.py

@@ -5,22 +5,29 @@ import warnings
 from collections.abc import AsyncGenerator, AsyncIterator
 from dataclasses import dataclass
 from datetime import datetime
-from typing import Any, Optional
+from typing import Any, Optional, Union
 
 from google.protobuf.message import Message
 from grpclib import GRPCError, Status
+from synchronicity import classproperty
 from synchronicity.async_wrap import asynccontextmanager
 
 from modal_proto import api_pb2
 
-from ._object import EPHEMERAL_OBJECT_HEARTBEAT_SLEEP, _get_environment_name, _Object, live_method, live_method_gen
+from ._object import (
+    EPHEMERAL_OBJECT_HEARTBEAT_SLEEP,
+    _get_environment_name,
+    _Object,
+    live_method,
+    live_method_gen,
+)
 from ._resolver import Resolver
 from ._serialization import deserialize, serialize
 from ._utils.async_utils import TaskContext, synchronize_api, warn_if_generator_is_not_consumed
 from ._utils.deprecation import deprecation_warning, warn_if_passing_namespace
 from ._utils.grpc_utils import retry_transient_errors
 from ._utils.name_utils import check_object_name
-from ._utils.time_utils import timestamp_to_localized_dt
+from ._utils.time_utils import as_timestamp, timestamp_to_localized_dt
 from .client import _Client
 from .exception import InvalidError, RequestSizeError
 
@@ -37,6 +44,68 @@ class QueueInfo:
     created_by: Optional[str]
 
 
+class _QueueManager:
+    """Namespace with methods for managing named Queue objects."""
+
+    @staticmethod
+    async def list(
+        *,
+        max_objects: Optional[int] = None,  # Limit requests to this size
+        created_before: Optional[Union[datetime, str]] = None,  # Limit based on creation date
+        environment_name: str = "",  # Uses active environment if not specified
+        client: Optional[_Client] = None,  # Optional client with Modal credentials
+    ) -> list["_Queue"]:
+        """Return a list of hydrated Queue objects.
+
+        **Examples:**
+
+        ```python
+        queues = modal.Queue.objects.list()
+        print([q.name for q in queues])
+        ```
+
+        Queues will be retreived from the active environment, or another one can be specified:
+
+        ```python notest
+        dev_queues = modal.Queue.objects.list(environment_name="dev")
+        ```
+
+        By default, all named Queues are returned, newest to oldest. It's also possible to limit the
+        number of results and to filter by creation date:
+
+        ```python
+        queues = modal.Queue.objects.list(max_objects=10, created_before="2025-01-01")
+        ```
+
+        """
+        client = await _Client.from_env() if client is None else client
+        if max_objects is not None and max_objects < 0:
+            raise InvalidError("max_objects cannot be negative")
+
+        items: list[api_pb2.QueueListResponse.QueueInfo] = []
+
+        async def retrieve_page(created_before: float) -> bool:
+            max_page_size = 100 if max_objects is None else min(100, max_objects - len(items))
+            pagination = api_pb2.ListPagination(max_objects=max_page_size, created_before=created_before)
+            req = api_pb2.QueueListRequest(environment_name=environment_name, pagination=pagination)
+            resp = await retry_transient_errors(client.stub.QueueList, req)
+            items.extend(resp.queues)
+            finished = (len(resp.queues) < max_page_size) or (max_objects is not None and len(items) >= max_objects)
+            return finished
+
+        finished = await retrieve_page(as_timestamp(created_before))
+        while True:
+            if finished:
+                break
+            finished = await retrieve_page(items[-1].metadata.creation_info.created_at)
+
+        queues = [_Queue._new_hydrated(item.queue_id, client, item.metadata, is_another_app=True) for item in items]
+        return queues[:max_objects] if max_objects is not None else queues
+
+
+QueueManager = synchronize_api(_QueueManager)
+
+
 class _Queue(_Object, type_prefix="qu"):
     """Distributed, FIFO queue for data flow in Modal apps.
 
@@ -116,6 +185,10 @@ class _Queue(_Object, type_prefix="qu"):
         """mdmd:hidden"""
         raise RuntimeError("Queue() is not allowed. Please use `Queue.from_name(...)` or `Queue.ephemeral()` instead.")
 
+    @classproperty
+    def objects(cls) -> _QueueManager:
+        return _QueueManager
+
     @property
     def name(self) -> Optional[str]:
         return self._name

modal/queue.pyi

@@ -5,6 +5,7 @@ import modal._object
 import modal.client
 import modal.object
 import modal_proto.api_pb2
+import synchronicity
 import synchronicity.combined_types
 import typing
 import typing_extensions
@@ -30,6 +31,115 @@ class QueueInfo:
         """Return self==value."""
         ...
 
+class _QueueManager:
+    """Namespace with methods for managing named Queue objects."""
+    @staticmethod
+    async def list(
+        *,
+        max_objects: typing.Optional[int] = None,
+        created_before: typing.Union[datetime.datetime, str, None] = None,
+        environment_name: str = "",
+        client: typing.Optional[modal.client._Client] = None,
+    ) -> list[_Queue]:
+        """Return a list of hydrated Queue objects.
+
+        **Examples:**
+
+        ```python
+        queues = modal.Queue.objects.list()
+        print([q.name for q in queues])
+        ```
+
+        Queues will be retreived from the active environment, or another one can be specified:
+
+        ```python notest
+        dev_queues = modal.Queue.objects.list(environment_name="dev")
+        ```
+
+        By default, all named Queues are returned, newest to oldest. It's also possible to limit the
+        number of results and to filter by creation date:
+
+        ```python
+        queues = modal.Queue.objects.list(max_objects=10, created_before="2025-01-01")
+        ```
+        """
+        ...
+
+class QueueManager:
+    """Namespace with methods for managing named Queue objects."""
+    def __init__(self, /, *args, **kwargs):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    class __list_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            *,
+            max_objects: typing.Optional[int] = None,
+            created_before: typing.Union[datetime.datetime, str, None] = None,
+            environment_name: str = "",
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> list[Queue]:
+            """Return a list of hydrated Queue objects.
+
+            **Examples:**
+
+            ```python
+            queues = modal.Queue.objects.list()
+            print([q.name for q in queues])
+            ```
+
+            Queues will be retreived from the active environment, or another one can be specified:
+
+            ```python notest
+            dev_queues = modal.Queue.objects.list(environment_name="dev")
+            ```
+
+            By default, all named Queues are returned, newest to oldest. It's also possible to limit the
+            number of results and to filter by creation date:
+
+            ```python
+            queues = modal.Queue.objects.list(max_objects=10, created_before="2025-01-01")
+            ```
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            *,
+            max_objects: typing.Optional[int] = None,
+            created_before: typing.Union[datetime.datetime, str, None] = None,
+            environment_name: str = "",
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> list[Queue]:
+            """Return a list of hydrated Queue objects.
+
+            **Examples:**
+
+            ```python
+            queues = modal.Queue.objects.list()
+            print([q.name for q in queues])
+            ```
+
+            Queues will be retreived from the active environment, or another one can be specified:
+
+            ```python notest
+            dev_queues = modal.Queue.objects.list(environment_name="dev")
+            ```
+
+            By default, all named Queues are returned, newest to oldest. It's also possible to limit the
+            number of results and to filter by creation date:
+
+            ```python
+            queues = modal.Queue.objects.list(max_objects=10, created_before="2025-01-01")
+            ```
+            """
+            ...
+
+    list: __list_spec
+
 class _Queue(modal._object._Object):
     """Distributed, FIFO queue for data flow in Modal apps.
 
@@ -109,6 +219,8 @@ class _Queue(modal._object._Object):
         """mdmd:hidden"""
         ...
 
+    @synchronicity.classproperty
+    def objects(cls) -> _QueueManager: ...
     @property
     def name(self) -> typing.Optional[str]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
@@ -377,6 +489,8 @@ class Queue(modal.object.Object):
         """mdmd:hidden"""
         ...
 
+    @synchronicity.classproperty
+    def objects(cls) -> QueueManager: ...
     @property
     def name(self) -> typing.Optional[str]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...