modal 1.0.5.dev2__py3-none-any.whl → 1.0.5.dev4__py3-none-any.whl

modal/queue.pyi

@@ -7,7 +7,81 @@ import typing
 import typing_extensions
 
 class _Queue(modal._object._Object):
-    def __init__(self): ...
+    """Distributed, FIFO queue for data flow in Modal apps.
+
+    The queue can contain any object serializable by `cloudpickle`, including Modal objects.
+
+    By default, the `Queue` object acts as a single FIFO queue which supports puts and gets (blocking and non-blocking).
+
+    **Usage**
+
+    ```python
+    from modal import Queue
+
+    # Create an ephemeral queue which is anonymous and garbage collected
+    with Queue.ephemeral() as my_queue:
+        # Putting values
+        my_queue.put("some value")
+        my_queue.put(123)
+
+        # Getting values
+        assert my_queue.get() == "some value"
+        assert my_queue.get() == 123
+
+        # Using partitions
+        my_queue.put(0)
+        my_queue.put(1, partition="foo")
+        my_queue.put(2, partition="bar")
+
+        # Default and "foo" partition are ignored by the get operation.
+        assert my_queue.get(partition="bar") == 2
+
+        # Set custom 10s expiration time on "foo" partition.
+        my_queue.put(3, partition="foo", partition_ttl=10)
+
+        # (beta feature) Iterate through items in place (read immutably)
+        my_queue.put(1)
+        assert [v for v in my_queue.iterate()] == [0, 1]
+
+    # You can also create persistent queues that can be used across apps
+    queue = Queue.from_name("my-persisted-queue", create_if_missing=True)
+    queue.put(42)
+    assert queue.get() == 42
+    ```
+
+    For more examples, see the [guide](https://modal.com/docs/guide/dicts-and-queues#modal-queues).
+
+    **Queue partitions (beta)**
+
+    Specifying partition keys gives access to other independent FIFO partitions within the same `Queue` object.
+    Across any two partitions, puts and gets are completely independent.
+    For example, a put in one partition does not affect a get in any other partition.
+
+    When no partition key is specified (by default), puts and gets will operate on a default partition.
+    This default partition is also isolated from all other partitions.
+    Please see the Usage section below for an example using partitions.
+
+    **Lifetime of a queue and its partitions**
+
+    By default, each partition is cleared 24 hours after the last `put` operation.
+    A lower TTL can be specified by the `partition_ttl` argument in the `put` or `put_many` methods.
+    Each partition's expiry is handled independently.
+
+    As such, `Queue`s are best used for communication between active functions and not relied on for persistent storage.
+
+    On app completion or after stopping an app any associated `Queue` objects are cleaned up.
+    All its partitions will be cleared.
+
+    **Limits**
+
+    A single `Queue` can contain up to 100,000 partitions, each with up to 5,000 items. Each item can be up to 1 MiB.
+
+    Partition keys must be non-empty and must not exceed 64 bytes.
+    """
+    def __init__(self):
+        """mdmd:hidden"""
+        ...
+
     @staticmethod
     def validate_partition_key(partition: typing.Optional[str]) -> bytes: ...
     @classmethod
@@ -16,11 +90,41 @@ class _Queue(modal._object._Object):
         client: typing.Optional[modal.client._Client] = None,
         environment_name: typing.Optional[str] = None,
         _heartbeat_sleep: float = 300,
-    ) -> typing.AsyncContextManager[_Queue]: ...
+    ) -> typing.AsyncContextManager[_Queue]:
+        """Creates a new ephemeral queue within a context manager:
+
+        Usage:
+        ```python
+        from modal import Queue
+
+        with Queue.ephemeral() as q:
+            q.put(123)
+        ```
+
+        ```python notest
+        async with Queue.ephemeral() as q:
+            await q.put.aio(123)
+        ```
+        """
+        ...
+
     @staticmethod
     def from_name(
         name: str, *, namespace=1, environment_name: typing.Optional[str] = None, create_if_missing: bool = False
-    ) -> _Queue: ...
+    ) -> _Queue:
+        """Reference a named Queue, creating if necessary.
+
+        In contrast to `modal.Queue.lookup`, this is a lazy method
+        the defers hydrating the local object with metadata from
+        Modal servers until the first time it is actually used.
+
+        ```python
+        q = modal.Queue.from_name("my-queue", create_if_missing=True)
+        q.put(123)
+        ```
+        """
+        ...
+
     @staticmethod
     async def lookup(
         name: str,
@@ -28,7 +132,22 @@ class _Queue(modal._object._Object):
         client: typing.Optional[modal.client._Client] = None,
         environment_name: typing.Optional[str] = None,
         create_if_missing: bool = False,
-    ) -> _Queue: ...
+    ) -> _Queue:
+        """mdmd:hidden
+        Lookup a named Queue.
+
+        DEPRECATED: This method is deprecated in favor of `modal.Queue.from_name`.
+
+        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)
+        ```
+        """
+        ...
+
     @staticmethod
     async def delete(
         name: str,
@@ -40,10 +159,24 @@ class _Queue(modal._object._Object):
     async def _get_blocking(
         self, partition: typing.Optional[str], timeout: typing.Optional[float], n_values: int
     ) -> list[typing.Any]: ...
-    async def clear(self, *, partition: typing.Optional[str] = None, all: bool = False) -> None: ...
+    async def clear(self, *, partition: typing.Optional[str] = None, all: bool = False) -> None:
+        """Clear the contents of a single partition or all partitions."""
+        ...
+
     async def get(
         self, block: bool = True, timeout: typing.Optional[float] = None, *, partition: typing.Optional[str] = None
-    ) -> typing.Optional[typing.Any]: ...
+    ) -> typing.Optional[typing.Any]:
+        """Remove and return the next object in the queue.
+
+        If `block` is `True` (the default) and the queue is empty, `get` will wait indefinitely for
+        an object, or until `timeout` if specified. Raises a native `queue.Empty` exception
+        if the `timeout` is reached.
+
+        If `block` is `False`, `get` returns `None` immediately if the queue is empty. The `timeout` is
+        ignored in this case.
+        """
+        ...
+
     async def get_many(
         self,
         n_values: int,
@@ -51,7 +184,20 @@ class _Queue(modal._object._Object):
         timeout: typing.Optional[float] = None,
         *,
         partition: typing.Optional[str] = None,
-    ) -> list[typing.Any]: ...
+    ) -> list[typing.Any]:
+        """Remove and return up to `n_values` objects from the queue.
+
+        If there are fewer than `n_values` items in the queue, return all of them.
+
+        If `block` is `True` (the default) and the queue is empty, `get` will wait indefinitely for
+        at least 1 object to be present, or until `timeout` if specified. Raises the stdlib's `queue.Empty`
+        exception if the `timeout` is reached.
+
+        If `block` is `False`, `get` returns `None` immediately if the queue is empty. The `timeout` is
+        ignored in this case.
+        """
+        ...
+
     async def put(
         self,
         v: typing.Any,
@@ -60,7 +206,18 @@ class _Queue(modal._object._Object):
         *,
         partition: typing.Optional[str] = None,
         partition_ttl: int = 86400,
-    ) -> None: ...
+    ) -> None:
+        """Add an object to the end of the queue.
+
+        If `block` is `True` and the queue is full, this method will retry indefinitely or
+        until `timeout` if specified. Raises the stdlib's `queue.Full` exception if the `timeout` is reached.
+        If blocking it is not recommended to omit the `timeout`, as the operation could wait indefinitely.
+
+        If `block` is `False`, this method raises `queue.Full` immediately if the queue is full. The `timeout` is
+        ignored in this case.
+        """
+        ...
+
     async def put_many(
         self,
         vs: list[typing.Any],
@@ -69,7 +226,18 @@ class _Queue(modal._object._Object):
         *,
         partition: typing.Optional[str] = None,
         partition_ttl: int = 86400,
-    ) -> None: ...
+    ) -> None:
+        """Add several objects to the end of the queue.
+
+        If `block` is `True` and the queue is full, this method will retry indefinitely or
+        until `timeout` if specified. Raises the stdlib's `queue.Full` exception if the `timeout` is reached.
+        If blocking it is not recommended to omit the `timeout`, as the operation could wait indefinitely.
+
+        If `block` is `False`, this method raises `queue.Full` immediately if the queue is full. The `timeout` is
+        ignored in this case.
+        """
+        ...
+
     async def _put_many_blocking(
         self,
         partition: typing.Optional[str],
@@ -80,15 +248,97 @@ class _Queue(modal._object._Object):
     async def _put_many_nonblocking(
         self, partition: typing.Optional[str], partition_ttl: int, vs: list[typing.Any]
     ): ...
-    async def len(self, *, partition: typing.Optional[str] = None, total: bool = False) -> int: ...
+    async def len(self, *, partition: typing.Optional[str] = None, total: bool = False) -> int:
+        """Return the number of objects in the queue partition."""
+        ...
+
     def iterate(
         self, *, partition: typing.Optional[str] = None, item_poll_timeout: float = 0.0
-    ) -> collections.abc.AsyncGenerator[typing.Any, None]: ...
+    ) -> collections.abc.AsyncGenerator[typing.Any, None]:
+        """(Beta feature) Iterate through items in the queue without mutation.
+
+        Specify `item_poll_timeout` to control how long the iterator should wait for the next time before giving up.
+        """
+        ...
 
 SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
 
 class Queue(modal.object.Object):
-    def __init__(self): ...
+    """Distributed, FIFO queue for data flow in Modal apps.
+
+    The queue can contain any object serializable by `cloudpickle`, including Modal objects.
+
+    By default, the `Queue` object acts as a single FIFO queue which supports puts and gets (blocking and non-blocking).
+
+    **Usage**
+
+    ```python
+    from modal import Queue
+
+    # Create an ephemeral queue which is anonymous and garbage collected
+    with Queue.ephemeral() as my_queue:
+        # Putting values
+        my_queue.put("some value")
+        my_queue.put(123)
+
+        # Getting values
+        assert my_queue.get() == "some value"
+        assert my_queue.get() == 123
+
+        # Using partitions
+        my_queue.put(0)
+        my_queue.put(1, partition="foo")
+        my_queue.put(2, partition="bar")
+
+        # Default and "foo" partition are ignored by the get operation.
+        assert my_queue.get(partition="bar") == 2
+
+        # Set custom 10s expiration time on "foo" partition.
+        my_queue.put(3, partition="foo", partition_ttl=10)
+
+        # (beta feature) Iterate through items in place (read immutably)
+        my_queue.put(1)
+        assert [v for v in my_queue.iterate()] == [0, 1]
+
+    # You can also create persistent queues that can be used across apps
+    queue = Queue.from_name("my-persisted-queue", create_if_missing=True)
+    queue.put(42)
+    assert queue.get() == 42
+    ```
+
+    For more examples, see the [guide](https://modal.com/docs/guide/dicts-and-queues#modal-queues).
+
+    **Queue partitions (beta)**
+
+    Specifying partition keys gives access to other independent FIFO partitions within the same `Queue` object.
+    Across any two partitions, puts and gets are completely independent.
+    For example, a put in one partition does not affect a get in any other partition.
+
+    When no partition key is specified (by default), puts and gets will operate on a default partition.
+    This default partition is also isolated from all other partitions.
+    Please see the Usage section below for an example using partitions.
+
+    **Lifetime of a queue and its partitions**
+
+    By default, each partition is cleared 24 hours after the last `put` operation.
+    A lower TTL can be specified by the `partition_ttl` argument in the `put` or `put_many` methods.
+    Each partition's expiry is handled independently.
+
+    As such, `Queue`s are best used for communication between active functions and not relied on for persistent storage.
+
+    On app completion or after stopping an app any associated `Queue` objects are cleaned up.
+    All its partitions will be cleared.
+
+    **Limits**
+
+    A single `Queue` can contain up to 100,000 partitions, each with up to 5,000 items. Each item can be up to 1 MiB.
+
+    Partition keys must be non-empty and must not exceed 64 bytes.
+    """
+    def __init__(self):
+        """mdmd:hidden"""
+        ...
+
     @staticmethod
     def validate_partition_key(partition: typing.Optional[str]) -> bytes: ...
     @classmethod
@@ -97,11 +347,40 @@ class Queue(modal.object.Object):
         client: typing.Optional[modal.client.Client] = None,
         environment_name: typing.Optional[str] = None,
         _heartbeat_sleep: float = 300,
-    ) -> synchronicity.combined_types.AsyncAndBlockingContextManager[Queue]: ...
+    ) -> synchronicity.combined_types.AsyncAndBlockingContextManager[Queue]:
+        """Creates a new ephemeral queue within a context manager:
+
+        Usage:
+        ```python
+        from modal import Queue
+
+        with Queue.ephemeral() as q:
+            q.put(123)
+        ```
+
+        ```python notest
+        async with Queue.ephemeral() as q:
+            await q.put.aio(123)
+        ```
+        """
+        ...
+
     @staticmethod
     def from_name(
         name: str, *, namespace=1, environment_name: typing.Optional[str] = None, create_if_missing: bool = False
-    ) -> Queue: ...
+    ) -> Queue:
+        """Reference a named Queue, creating if necessary.
+
+        In contrast to `modal.Queue.lookup`, this is a lazy method
+        the defers hydrating the local object with metadata from
+        Modal servers until the first time it is actually used.
+
+        ```python
+        q = modal.Queue.from_name("my-queue", create_if_missing=True)
+        q.put(123)
+        ```
+        """
+        ...
 
     class __lookup_spec(typing_extensions.Protocol):
         def __call__(
@@ -112,7 +391,22 @@ class Queue(modal.object.Object):
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
             create_if_missing: bool = False,
-        ) -> Queue: ...
+        ) -> Queue:
+            """mdmd:hidden
+            Lookup a named Queue.
+
+            DEPRECATED: This method is deprecated in favor of `modal.Queue.from_name`.
+
+            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)
+            ```
+            """
+            ...
+
         async def aio(
             self,
             /,
@@ -121,7 +415,21 @@ class Queue(modal.object.Object):
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
             create_if_missing: bool = False,
-        ) -> Queue: ...
+        ) -> Queue:
+            """mdmd:hidden
+            Lookup a named Queue.
+
+            DEPRECATED: This method is deprecated in favor of `modal.Queue.from_name`.
+
+            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)
+            ```
+            """
+            ...
 
     lookup: __lookup_spec
 
@@ -162,8 +470,13 @@ class Queue(modal.object.Object):
     _get_blocking: ___get_blocking_spec[typing_extensions.Self]
 
     class __clear_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, *, partition: typing.Optional[str] = None, all: bool = False) -> None: ...
-        async def aio(self, /, *, partition: typing.Optional[str] = None, all: bool = False) -> None: ...
+        def __call__(self, /, *, partition: typing.Optional[str] = None, all: bool = False) -> None:
+            """Clear the contents of a single partition or all partitions."""
+            ...
+
+        async def aio(self, /, *, partition: typing.Optional[str] = None, all: bool = False) -> None:
+            """Clear the contents of a single partition or all partitions."""
+            ...
 
     clear: __clear_spec[typing_extensions.Self]
 
@@ -175,7 +488,18 @@ class Queue(modal.object.Object):
             timeout: typing.Optional[float] = None,
             *,
             partition: typing.Optional[str] = None,
-        ) -> typing.Optional[typing.Any]: ...
+        ) -> typing.Optional[typing.Any]:
+            """Remove and return the next object in the queue.
+
+            If `block` is `True` (the default) and the queue is empty, `get` will wait indefinitely for
+            an object, or until `timeout` if specified. Raises a native `queue.Empty` exception
+            if the `timeout` is reached.
+
+            If `block` is `False`, `get` returns `None` immediately if the queue is empty. The `timeout` is
+            ignored in this case.
+            """
+            ...
+
         async def aio(
             self,
             /,
@@ -183,7 +507,17 @@ class Queue(modal.object.Object):
             timeout: typing.Optional[float] = None,
             *,
             partition: typing.Optional[str] = None,
-        ) -> typing.Optional[typing.Any]: ...
+        ) -> typing.Optional[typing.Any]:
+            """Remove and return the next object in the queue.
+
+            If `block` is `True` (the default) and the queue is empty, `get` will wait indefinitely for
+            an object, or until `timeout` if specified. Raises a native `queue.Empty` exception
+            if the `timeout` is reached.
+
+            If `block` is `False`, `get` returns `None` immediately if the queue is empty. The `timeout` is
+            ignored in this case.
+            """
+            ...
 
     get: __get_spec[typing_extensions.Self]
 
@@ -196,7 +530,20 @@ class Queue(modal.object.Object):
             timeout: typing.Optional[float] = None,
             *,
             partition: typing.Optional[str] = None,
-        ) -> list[typing.Any]: ...
+        ) -> list[typing.Any]:
+            """Remove and return up to `n_values` objects from the queue.
+
+            If there are fewer than `n_values` items in the queue, return all of them.
+
+            If `block` is `True` (the default) and the queue is empty, `get` will wait indefinitely for
+            at least 1 object to be present, or until `timeout` if specified. Raises the stdlib's `queue.Empty`
+            exception if the `timeout` is reached.
+
+            If `block` is `False`, `get` returns `None` immediately if the queue is empty. The `timeout` is
+            ignored in this case.
+            """
+            ...
+
         async def aio(
             self,
             /,
@@ -205,7 +552,19 @@ class Queue(modal.object.Object):
             timeout: typing.Optional[float] = None,
             *,
             partition: typing.Optional[str] = None,
-        ) -> list[typing.Any]: ...
+        ) -> list[typing.Any]:
+            """Remove and return up to `n_values` objects from the queue.
+
+            If there are fewer than `n_values` items in the queue, return all of them.
+
+            If `block` is `True` (the default) and the queue is empty, `get` will wait indefinitely for
+            at least 1 object to be present, or until `timeout` if specified. Raises the stdlib's `queue.Empty`
+            exception if the `timeout` is reached.
+
+            If `block` is `False`, `get` returns `None` immediately if the queue is empty. The `timeout` is
+            ignored in this case.
+            """
+            ...
 
     get_many: __get_many_spec[typing_extensions.Self]
 
@@ -219,7 +578,18 @@ class Queue(modal.object.Object):
             *,
             partition: typing.Optional[str] = None,
             partition_ttl: int = 86400,
-        ) -> None: ...
+        ) -> None:
+            """Add an object to the end of the queue.
+
+            If `block` is `True` and the queue is full, this method will retry indefinitely or
+            until `timeout` if specified. Raises the stdlib's `queue.Full` exception if the `timeout` is reached.
+            If blocking it is not recommended to omit the `timeout`, as the operation could wait indefinitely.
+
+            If `block` is `False`, this method raises `queue.Full` immediately if the queue is full. The `timeout` is
+            ignored in this case.
+            """
+            ...
+
         async def aio(
             self,
             /,
@@ -229,7 +599,17 @@ class Queue(modal.object.Object):
             *,
             partition: typing.Optional[str] = None,
             partition_ttl: int = 86400,
-        ) -> None: ...
+        ) -> None:
+            """Add an object to the end of the queue.
+
+            If `block` is `True` and the queue is full, this method will retry indefinitely or
+            until `timeout` if specified. Raises the stdlib's `queue.Full` exception if the `timeout` is reached.
+            If blocking it is not recommended to omit the `timeout`, as the operation could wait indefinitely.
+
+            If `block` is `False`, this method raises `queue.Full` immediately if the queue is full. The `timeout` is
+            ignored in this case.
+            """
+            ...
 
     put: __put_spec[typing_extensions.Self]
 
@@ -243,7 +623,18 @@ class Queue(modal.object.Object):
             *,
             partition: typing.Optional[str] = None,
             partition_ttl: int = 86400,
-        ) -> None: ...
+        ) -> None:
+            """Add several objects to the end of the queue.
+
+            If `block` is `True` and the queue is full, this method will retry indefinitely or
+            until `timeout` if specified. Raises the stdlib's `queue.Full` exception if the `timeout` is reached.
+            If blocking it is not recommended to omit the `timeout`, as the operation could wait indefinitely.
+
+            If `block` is `False`, this method raises `queue.Full` immediately if the queue is full. The `timeout` is
+            ignored in this case.
+            """
+            ...
+
         async def aio(
             self,
             /,
@@ -253,7 +644,17 @@ class Queue(modal.object.Object):
             *,
             partition: typing.Optional[str] = None,
             partition_ttl: int = 86400,
-        ) -> None: ...
+        ) -> None:
+            """Add several objects to the end of the queue.
+
+            If `block` is `True` and the queue is full, this method will retry indefinitely or
+            until `timeout` if specified. Raises the stdlib's `queue.Full` exception if the `timeout` is reached.
+            If blocking it is not recommended to omit the `timeout`, as the operation could wait indefinitely.
+
+            If `block` is `False`, this method raises `queue.Full` immediately if the queue is full. The `timeout` is
+            ignored in this case.
+            """
+            ...
 
     put_many: __put_many_spec[typing_extensions.Self]
 
@@ -284,17 +685,33 @@ class Queue(modal.object.Object):
     _put_many_nonblocking: ___put_many_nonblocking_spec[typing_extensions.Self]
 
     class __len_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, *, partition: typing.Optional[str] = None, total: bool = False) -> int: ...
-        async def aio(self, /, *, partition: typing.Optional[str] = None, total: bool = False) -> int: ...
+        def __call__(self, /, *, partition: typing.Optional[str] = None, total: bool = False) -> int:
+            """Return the number of objects in the queue partition."""
+            ...
+
+        async def aio(self, /, *, partition: typing.Optional[str] = None, total: bool = False) -> int:
+            """Return the number of objects in the queue partition."""
+            ...
 
     len: __len_spec[typing_extensions.Self]
 
     class __iterate_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(
             self, /, *, partition: typing.Optional[str] = None, item_poll_timeout: float = 0.0
-        ) -> typing.Generator[typing.Any, None, None]: ...
+        ) -> typing.Generator[typing.Any, None, None]:
+            """(Beta feature) Iterate through items in the queue without mutation.
+
+            Specify `item_poll_timeout` to control how long the iterator should wait for the next time before giving up.
+            """
+            ...
+
         def aio(
             self, /, *, partition: typing.Optional[str] = None, item_poll_timeout: float = 0.0
-        ) -> collections.abc.AsyncGenerator[typing.Any, None]: ...
+        ) -> collections.abc.AsyncGenerator[typing.Any, None]:
+            """(Beta feature) Iterate through items in the queue without mutation.
+
+            Specify `item_poll_timeout` to control how long the iterator should wait for the next time before giving up.
+            """
+            ...
 
     iterate: __iterate_spec[typing_extensions.Self]