modal 1.0.6.dev58__py3-none-any.whl → 1.2.3.dev7__py3-none-any.whl

modal/queue.pyi

@@ -1,11 +1,356 @@
 import collections.abc
+import datetime
+import google.protobuf.message
 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
 
+class QueueInfo:
+    """Information about the Queue object."""
+
+    name: typing.Optional[str]
+    created_at: datetime.datetime
+    created_by: typing.Optional[str]
+
+    def __init__(
+        self, name: typing.Optional[str], created_at: datetime.datetime, created_by: typing.Optional[str]
+    ) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
+
+class _QueueManager:
+    """Namespace with methods for managing named Queue objects."""
+    @staticmethod
+    async def create(
+        name: str,
+        *,
+        allow_existing: bool = False,
+        environment_name: typing.Optional[str] = None,
+        client: typing.Optional[modal.client._Client] = None,
+    ) -> None:
+        """Create a new Queue object.
+
+        **Examples:**
+
+        ```python notest
+        modal.Queue.objects.create("my-queue")
+        ```
+
+        Queues will be created in the active environment, or another one can be specified:
+
+        ```python notest
+        modal.Queue.objects.create("my-queue", environment_name="dev")
+        ```
+
+        By default, an error will be raised if the Queue already exists, but passing
+        `allow_existing=True` will make the creation attempt a no-op in this case.
+
+        ```python notest
+        modal.Queue.objects.create("my-queue", allow_existing=True)
+        ```
+
+        Note that this method does not return a local instance of the Queue. You can use
+        `modal.Queue.from_name` to perform a lookup after creation.
+
+        Added in v1.1.2.
+        """
+        ...
+
+    @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")
+        ```
+
+        Added in v1.1.2.
+        """
+        ...
+
+    @staticmethod
+    async def delete(
+        name: str,
+        *,
+        allow_missing: bool = False,
+        environment_name: typing.Optional[str] = None,
+        client: typing.Optional[modal.client._Client] = None,
+    ):
+        """Delete a named Queue.
+
+        Warning: This deletes an *entire Queue*, not just a specific entry or partition.
+        Deletion is irreversible and will affect any Apps currently using the Queue.
+
+        **Examples:**
+
+        ```python notest
+        await modal.Queue.objects.delete("my-queue")
+        ```
+
+        Queues will be deleted from the active environment, or another one can be specified:
+
+        ```python notest
+        await modal.Queue.objects.delete("my-queue", environment_name="dev")
+        ```
+
+        Added in v1.1.2.
+        """
+        ...
+
+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 __create_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            name: str,
+            *,
+            allow_existing: bool = False,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> None:
+            """Create a new Queue object.
+
+            **Examples:**
+
+            ```python notest
+            modal.Queue.objects.create("my-queue")
+            ```
+
+            Queues will be created in the active environment, or another one can be specified:
+
+            ```python notest
+            modal.Queue.objects.create("my-queue", environment_name="dev")
+            ```
+
+            By default, an error will be raised if the Queue already exists, but passing
+            `allow_existing=True` will make the creation attempt a no-op in this case.
+
+            ```python notest
+            modal.Queue.objects.create("my-queue", allow_existing=True)
+            ```
+
+            Note that this method does not return a local instance of the Queue. You can use
+            `modal.Queue.from_name` to perform a lookup after creation.
+
+            Added in v1.1.2.
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            name: str,
+            *,
+            allow_existing: bool = False,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> None:
+            """Create a new Queue object.
+
+            **Examples:**
+
+            ```python notest
+            modal.Queue.objects.create("my-queue")
+            ```
+
+            Queues will be created in the active environment, or another one can be specified:
+
+            ```python notest
+            modal.Queue.objects.create("my-queue", environment_name="dev")
+            ```
+
+            By default, an error will be raised if the Queue already exists, but passing
+            `allow_existing=True` will make the creation attempt a no-op in this case.
+
+            ```python notest
+            modal.Queue.objects.create("my-queue", allow_existing=True)
+            ```
+
+            Note that this method does not return a local instance of the Queue. You can use
+            `modal.Queue.from_name` to perform a lookup after creation.
+
+            Added in v1.1.2.
+            """
+            ...
+
+    create: __create_spec
+
+    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")
+            ```
+
+            Added in v1.1.2.
+            """
+            ...
+
+        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")
+            ```
+
+            Added in v1.1.2.
+            """
+            ...
+
+    list: __list_spec
+
+    class __delete_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            name: str,
+            *,
+            allow_missing: bool = False,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ):
+            """Delete a named Queue.
+
+            Warning: This deletes an *entire Queue*, not just a specific entry or partition.
+            Deletion is irreversible and will affect any Apps currently using the Queue.
+
+            **Examples:**
+
+            ```python notest
+            await modal.Queue.objects.delete("my-queue")
+            ```
+
+            Queues will be deleted from the active environment, or another one can be specified:
+
+            ```python notest
+            await modal.Queue.objects.delete("my-queue", environment_name="dev")
+            ```
+
+            Added in v1.1.2.
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            name: str,
+            *,
+            allow_missing: bool = False,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ):
+            """Delete a named Queue.
+
+            Warning: This deletes an *entire Queue*, not just a specific entry or partition.
+            Deletion is irreversible and will affect any Apps currently using the Queue.
+
+            **Examples:**
+
+            ```python notest
+            await modal.Queue.objects.delete("my-queue")
+            ```
+
+            Queues will be deleted from the active environment, or another one can be specified:
+
+            ```python notest
+            await modal.Queue.objects.delete("my-queue", environment_name="dev")
+            ```
+
+            Added in v1.1.2.
+            """
+            ...
+
+    delete: __delete_spec
+
 class _Queue(modal._object._Object):
     """Distributed, FIFO queue for data flow in Modal apps.
 
@@ -78,10 +423,19 @@ class _Queue(modal._object._Object):
 
     Partition keys must be non-empty and must not exceed 64 bytes.
     """
+
+    _metadata: typing.Optional[modal_proto.api_pb2.QueueMetadata]
+
     def __init__(self):
         """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]): ...
+    def _get_metadata(self) -> modal_proto.api_pb2.QueueMetadata: ...
     @staticmethod
     def validate_partition_key(partition: typing.Optional[str]) -> bytes: ...
     @classmethod
@@ -110,7 +464,12 @@ class _Queue(modal._object._Object):
 
     @staticmethod
     def from_name(
-        name: str, *, namespace=None, environment_name: typing.Optional[str] = None, create_if_missing: bool = False
+        name: str,
+        *,
+        namespace=None,
+        environment_name: typing.Optional[str] = None,
+        create_if_missing: bool = False,
+        client: typing.Optional[modal.client._Client] = None,
     ) -> _Queue:
         """Reference a named Queue, creating if necessary.
 
@@ -126,35 +485,26 @@ class _Queue(modal._object._Object):
         ...
 
     @staticmethod
-    async def lookup(
+    async def delete(
         name: str,
-        namespace=None,
+        *,
         client: typing.Optional[modal.client._Client] = None,
         environment_name: typing.Optional[str] = None,
-        create_if_missing: bool = False,
-    ) -> _Queue:
+    ):
         """mdmd:hidden
-        Lookup a named Queue.
-
-        DEPRECATED: This method is deprecated in favor of `modal.Queue.from_name`.
+        Delete a named Queue.
 
-        In contrast to `modal.Queue.from_name`, this is an eager method
-        that will hydrate the local object with metadata from Modal servers.
+        Warning: This deletes an *entire Queue*, not just a specific entry or partition.
+        Deletion is irreversible and will affect any Apps currently using the Queue.
 
-        ```python notest
-        q = modal.Queue.lookup("my-queue")
-        q.put(123)
-        ```
+        DEPRECATED: This method is deprecated; we recommend using `modal.Queue.objects.delete` instead.
         """
         ...
 
-    @staticmethod
-    async def delete(
-        name: str,
-        *,
-        client: typing.Optional[modal.client._Client] = None,
-        environment_name: typing.Optional[str] = None,
-    ): ...
+    async def info(self) -> QueueInfo:
+        """Return information about the Queue object."""
+        ...
+
     async def _get_nonblocking(self, partition: typing.Optional[str], n_values: int) -> list[typing.Any]: ...
     async def _get_blocking(
         self, partition: typing.Optional[str], timeout: typing.Optional[float], n_values: int
@@ -335,10 +685,19 @@ class Queue(modal.object.Object):
 
     Partition keys must be non-empty and must not exceed 64 bytes.
     """
+
+    _metadata: typing.Optional[modal_proto.api_pb2.QueueMetadata]
+
     def __init__(self):
         """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]): ...
+    def _get_metadata(self) -> modal_proto.api_pb2.QueueMetadata: ...
     @staticmethod
     def validate_partition_key(partition: typing.Optional[str]) -> bytes: ...
     @classmethod
@@ -367,7 +726,12 @@ class Queue(modal.object.Object):
 
     @staticmethod
     def from_name(
-        name: str, *, namespace=None, environment_name: typing.Optional[str] = None, create_if_missing: bool = False
+        name: str,
+        *,
+        namespace=None,
+        environment_name: typing.Optional[str] = None,
+        create_if_missing: bool = False,
+        client: typing.Optional[modal.client.Client] = None,
     ) -> Queue:
         """Reference a named Queue, creating if necessary.
 
@@ -382,28 +746,22 @@ class Queue(modal.object.Object):
         """
         ...
 
-    class __lookup_spec(typing_extensions.Protocol):
+    class __delete_spec(typing_extensions.Protocol):
         def __call__(
             self,
             /,
             name: str,
-            namespace=None,
+            *,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
-            create_if_missing: bool = False,
-        ) -> Queue:
+        ):
             """mdmd:hidden
-            Lookup a named Queue.
+            Delete a named Queue.
 
-            DEPRECATED: This method is deprecated in favor of `modal.Queue.from_name`.
+            Warning: This deletes an *entire Queue*, not just a specific entry or partition.
+            Deletion is irreversible and will affect any Apps currently using the Queue.
 
-            In contrast to `modal.Queue.from_name`, this is an eager method
-            that will hydrate the local object with metadata from Modal servers.
-
-            ```python notest
-            q = modal.Queue.lookup("my-queue")
-            q.put(123)
-            ```
+            DEPRECATED: This method is deprecated; we recommend using `modal.Queue.objects.delete` instead.
             """
             ...
 
@@ -411,47 +769,32 @@ class Queue(modal.object.Object):
             self,
             /,
             name: str,
-            namespace=None,
+            *,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
-            create_if_missing: bool = False,
-        ) -> Queue:
+        ):
             """mdmd:hidden
-            Lookup a named Queue.
-
-            DEPRECATED: This method is deprecated in favor of `modal.Queue.from_name`.
+            Delete a named Queue.
 
-            In contrast to `modal.Queue.from_name`, this is an eager method
-            that will hydrate the local object with metadata from Modal servers.
+            Warning: This deletes an *entire Queue*, not just a specific entry or partition.
+            Deletion is irreversible and will affect any Apps currently using the Queue.
 
-            ```python notest
-            q = modal.Queue.lookup("my-queue")
-            q.put(123)
-            ```
+            DEPRECATED: This method is deprecated; we recommend using `modal.Queue.objects.delete` instead.
             """
             ...
 
-    lookup: __lookup_spec
+    delete: __delete_spec
 
-    class __delete_spec(typing_extensions.Protocol):
-        def __call__(
-            self,
-            /,
-            name: str,
-            *,
-            client: typing.Optional[modal.client.Client] = None,
-            environment_name: typing.Optional[str] = None,
-        ): ...
-        async def aio(
-            self,
-            /,
-            name: str,
-            *,
-            client: typing.Optional[modal.client.Client] = None,
-            environment_name: typing.Optional[str] = None,
-        ): ...
+    class __info_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(self, /) -> QueueInfo:
+            """Return information about the Queue object."""
+            ...
 
-    delete: __delete_spec
+        async def aio(self, /) -> QueueInfo:
+            """Return information about the Queue object."""
+            ...
+
+    info: __info_spec[typing_extensions.Self]
 
     class ___get_nonblocking_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /, partition: typing.Optional[str], n_values: int) -> list[typing.Any]: ...