modal 1.1.2.dev10__py3-none-any.whl → 1.1.2.dev12__py3-none-any.whl

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]): ...

modal/secret.py

@@ -6,6 +6,7 @@ from typing import Optional, Union
 
 from google.protobuf.message import Message
 from grpclib import GRPCError, Status
+from synchronicity import classproperty
 
 from modal_proto import api_pb2
 
@@ -16,7 +17,7 @@ from ._utils.async_utils import 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 .exception import InvalidError, NotFoundError
 
@@ -35,6 +36,68 @@ class SecretInfo:
     created_by: Optional[str]
 
 
+class _SecretManager:
+    """Namespace with methods for managing named Secret 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["_Secret"]:
+        """Return a list of hydrated Secret objects.
+
+        **Examples:**
+
+        ```python
+        secrets = modal.Secret.objects.list()
+        print([s.name for s in secrets])
+        ```
+
+        Secrets will be retreived from the active environment, or another one can be specified:
+
+        ```python notest
+        dev_secrets = modal.Secret.objects.list(environment_name="dev")
+        ```
+
+        By default, all named Secrets are returned, newest to oldest. It's also possible to limit the
+        number of results and to filter by creation date:
+
+        ```python
+        secrets = modal.Secret.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.SecretListItem] = []
+
+        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.SecretListRequest(environment_name=environment_name, pagination=pagination)
+            resp = await retry_transient_errors(client.stub.SecretList, req)
+            items.extend(resp.items)
+            finished = (len(resp.items) < 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)
+
+        secrets = [_Secret._new_hydrated(item.secret_id, client, item.metadata, is_another_app=True) for item in items]
+        return secrets[:max_objects] if max_objects is not None else secrets
+
+
+SecretManager = synchronize_api(_SecretManager)
+
+
 class _Secret(_Object, type_prefix="st"):
     """Secrets provide a dictionary of environment variables for images.
 
@@ -47,6 +110,10 @@ class _Secret(_Object, type_prefix="st"):
 
     _metadata: Optional[api_pb2.SecretMetadata] = None
 
+    @classproperty
+    def objects(cls) -> _SecretManager:
+        return _SecretManager
+
     @property
     def name(self) -> Optional[str]:
         return self._name

modal/secret.pyi

@@ -4,6 +4,7 @@ import modal._object
 import modal.client
 import modal.object
 import modal_proto.api_pb2
+import synchronicity
 import typing
 import typing_extensions
 
@@ -28,6 +29,115 @@ class SecretInfo:
         """Return self==value."""
         ...
 
+class _SecretManager:
+    """Namespace with methods for managing named Secret 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[_Secret]:
+        """Return a list of hydrated Secret objects.
+
+        **Examples:**
+
+        ```python
+        secrets = modal.Secret.objects.list()
+        print([s.name for s in secrets])
+        ```
+
+        Secrets will be retreived from the active environment, or another one can be specified:
+
+        ```python notest
+        dev_secrets = modal.Secret.objects.list(environment_name="dev")
+        ```
+
+        By default, all named Secrets are returned, newest to oldest. It's also possible to limit the
+        number of results and to filter by creation date:
+
+        ```python
+        secrets = modal.Secret.objects.list(max_objects=10, created_before="2025-01-01")
+        ```
+        """
+        ...
+
+class SecretManager:
+    """Namespace with methods for managing named Secret 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[Secret]:
+            """Return a list of hydrated Secret objects.
+
+            **Examples:**
+
+            ```python
+            secrets = modal.Secret.objects.list()
+            print([s.name for s in secrets])
+            ```
+
+            Secrets will be retreived from the active environment, or another one can be specified:
+
+            ```python notest
+            dev_secrets = modal.Secret.objects.list(environment_name="dev")
+            ```
+
+            By default, all named Secrets are returned, newest to oldest. It's also possible to limit the
+            number of results and to filter by creation date:
+
+            ```python
+            secrets = modal.Secret.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[Secret]:
+            """Return a list of hydrated Secret objects.
+
+            **Examples:**
+
+            ```python
+            secrets = modal.Secret.objects.list()
+            print([s.name for s in secrets])
+            ```
+
+            Secrets will be retreived from the active environment, or another one can be specified:
+
+            ```python notest
+            dev_secrets = modal.Secret.objects.list(environment_name="dev")
+            ```
+
+            By default, all named Secrets are returned, newest to oldest. It's also possible to limit the
+            number of results and to filter by creation date:
+
+            ```python
+            secrets = modal.Secret.objects.list(max_objects=10, created_before="2025-01-01")
+            ```
+            """
+            ...
+
+    list: __list_spec
+
 class _Secret(modal._object._Object):
     """Secrets provide a dictionary of environment variables for images.
 
@@ -40,6 +150,8 @@ class _Secret(modal._object._Object):
 
     _metadata: typing.Optional[modal_proto.api_pb2.SecretMetadata]
 
+    @synchronicity.classproperty
+    def objects(cls) -> _SecretManager: ...
     @property
     def name(self) -> typing.Optional[str]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
@@ -157,6 +269,8 @@ class Secret(modal.object.Object):
         """mdmd:hidden"""
         ...
 
+    @synchronicity.classproperty
+    def objects(cls) -> SecretManager: ...
     @property
     def name(self) -> typing.Optional[str]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...

modal/volume.py

@@ -25,6 +25,7 @@ from typing import (
 
 from google.protobuf.message import Message
 from grpclib import GRPCError, Status
+from synchronicity import classproperty
 from synchronicity.async_wrap import asynccontextmanager
 
 import modal.exception
@@ -32,7 +33,13 @@ import modal_proto.api_pb2
 from modal.exception import InvalidError, VolumeUploadTimeoutError
 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 ._utils.async_utils import (
     TaskContext,
@@ -55,7 +62,7 @@ from ._utils.deprecation import deprecation_warning, warn_if_passing_namespace
 from ._utils.grpc_utils import retry_transient_errors
 from ._utils.http_utils import ClientSessionRegistry
 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
 
@@ -106,6 +113,68 @@ class VolumeInfo:
     created_by: Optional[str]
 
 
+class _VolumeManager:
+    """Namespace with methods for managing named Volume 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["_Volume"]:
+        """Return a list of hydrated Volume objects.
+
+        **Examples:**
+
+        ```python
+        volumes = modal.Volume.objects.list()
+        print([v.name for v in volumes])
+        ```
+
+        Volumes will be retreived from the active environment, or another one can be specified:
+
+        ```python notest
+        dev_volumes = modal.Volume.objects.list(environment_name="dev")
+        ```
+
+        By default, all named Volumes are returned, newest to oldest. It's also possible to limit the
+        number of results and to filter by creation date:
+
+        ```python
+        volumes = modal.Volume.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.VolumeListItem] = []
+
+        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.VolumeListRequest(environment_name=environment_name, pagination=pagination)
+            resp = await retry_transient_errors(client.stub.VolumeList, req)
+            items.extend(resp.items)
+            finished = (len(resp.items) < 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)
+
+        volumes = [_Volume._new_hydrated(item.volume_id, client, item.metadata, is_another_app=True) for item in items]
+        return volumes[:max_objects] if max_objects is not None else volumes
+
+
+VolumeManager = synchronize_api(_VolumeManager)
+
+
 class _Volume(_Object, type_prefix="vo"):
     """A writeable volume that can be used to share files between one or more Modal functions.
 
@@ -152,6 +221,14 @@ class _Volume(_Object, type_prefix="vo"):
     _metadata: "typing.Optional[api_pb2.VolumeMetadata]"
     _read_only: bool = False
 
+    @classproperty
+    def objects(cls) -> _VolumeManager:
+        return _VolumeManager
+
+    @property
+    def name(self) -> Optional[str]:
+        return self._name
+
     def read_only(self) -> "_Volume":
         """Configure Volume to mount as read-only.
 
@@ -181,10 +258,6 @@ class _Volume(_Object, type_prefix="vo"):
         obj = _Volume._from_loader(_load, "Volume()", hydrate_lazily=True, deps=lambda: [self])
         return obj
 
-    @property
-    def name(self) -> Optional[str]:
-        return self._name
-
     def _hydrate_metadata(self, metadata: Optional[Message]):
         if metadata:
             assert isinstance(metadata, api_pb2.VolumeMetadata)