encore-dev 2.0.0a7__py3-none-any.whl

encore/storage/redis/list.py

@@ -0,0 +1,511 @@
+"""Redis list commands.
+
+Keys are strings without Encore prefixes. Values accept bytes, str, int, float,
+or
+RedisValue implementations; value reads default to bytes. Use command[T](...) to
+decode values as T. Custom encoding and decoding errors propagate to the caller.
+Repeated arguments are variadic. Individual commands document their reply
+shapes and any option-dependent behavior.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ...tracing._context import active_ctx_bytes
+from ._base import CommandInterface, TypedCommand
+from ._values import T, Value, encode, decode, decode_optional, decode_pop, U
+
+
+class _LindexCommand(TypedCommand[T]):
+    """A callable LINDEX command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _LindexCommand[U]:
+        """Select the value type for this command.
+
+        Use lindex[T](...) to decode stored values as T. Selecting a type does
+        not open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _LindexCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, index: int) -> Optional[T]:
+        """Return the element at a list index.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            index: The zero-based index; negative values count from the end.
+
+        Returns:
+            The decoded element, or None if the key or index does not exist.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        result = await self._get_handle().list_lindex(
+            key, index, source=active_ctx_bytes()
+        )
+        return decode_optional(result, self._value_type)
+
+
+class _LrangeCommand(TypedCommand[T]):
+    """A callable LRANGE command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _LrangeCommand[U]:
+        """Select the value type for this command.
+
+        Use lrange[T](...) to decode stored values as T. Selecting a type does
+        not open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _LrangeCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, start: int, stop: int) -> list[T]:
+        """Return an inclusive range of list elements.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            start: The inclusive starting index; negative values count from the
+                end.
+            stop: The inclusive ending index; negative values count from the
+                end.
+
+        Returns:
+            Elements in list order; empty if the key or range is empty.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        result = await self._get_handle().list_lrange(
+            key, start, stop, source=active_ctx_bytes()
+        )
+        return [decode(value, self._value_type) for value in result]
+
+
+class _LmoveCommand(TypedCommand[T]):
+    """A callable LMOVE command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _LmoveCommand[U]:
+        """Select the value type for this command.
+
+        Use lmove[T](...) to decode stored values as T. Selecting a type does
+        not open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _LmoveCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, destination: str, from_side: str, to_side: str
+    ) -> Optional[T]:
+        """Move one element between list ends atomically.
+
+        Redis executes the command before its result is decoded. A decoding
+        error does not undo the command's effects.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            destination: The destination key, without an Encore key prefix.
+            from_side: The source end: LEFT or RIGHT, case-insensitively.
+            to_side: The destination end: LEFT or RIGHT, case-insensitively.
+
+        Returns:
+            The decoded moved element, or None if the source is empty or
+            missing.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        result = await self._get_handle().list_lmove(
+            key, destination, from_side, to_side, source=active_ctx_bytes()
+        )
+        return decode_optional(result, self._value_type)
+
+
+class _LpopCommand(TypedCommand[T]):
+    """A callable LPOP command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _LpopCommand[U]:
+        """Select the value type for this command.
+
+        Use lpop[T](...) to decode stored values as T. Selecting a type does not
+        open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _LpopCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, *, count: int | None = None
+    ) -> T | list[T] | None:
+        """Remove elements from the head of a list.
+
+        Redis executes the command before its result is decoded. A decoding
+        error does not undo the command's effects.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            count: The nonnegative maximum number of elements to remove. None
+                removes and returns a single decoded element instead of a list.
+
+        Returns:
+            Without count, a single decoded element. With count, a list of up to
+            count elements. Returns None if the key is missing.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        result = await self._get_handle().list_lpop(
+            key, count=count, source=active_ctx_bytes()
+        )
+        return decode_pop(result, self._value_type)
+
+
+class _RpopCommand(TypedCommand[T]):
+    """A callable RPOP command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _RpopCommand[U]:
+        """Select the value type for this command.
+
+        Use rpop[T](...) to decode stored values as T. Selecting a type does not
+        open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _RpopCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, *, count: int | None = None
+    ) -> T | list[T] | None:
+        """Remove elements from the tail of a list.
+
+        Redis executes the command before its result is decoded. A decoding
+        error does not undo the command's effects.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            count: The nonnegative maximum number of elements to remove. None
+                removes and returns a single decoded element instead of a list.
+
+        Returns:
+            Without count, a single decoded element. With count, a list in
+            removal order of up to count elements. Returns None if the key is
+            missing.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        result = await self._get_handle().list_rpop(
+            key, count=count, source=active_ctx_bytes()
+        )
+        return decode_pop(result, self._value_type)
+
+
+class ReadOnlyInterface(CommandInterface):
+    """Commands available through a read-only database handle."""
+
+    @property
+    def lindex(self) -> _LindexCommand[bytes]:
+        """The callable LINDEX command.
+
+        Use lindex[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _LindexCommand(self._get_handle, bytes)
+
+    async def llen(self, key: str) -> int:
+        """Return the number of elements in a list.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The list length, or zero if the key does not exist.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().list_llen(key, source=active_ctx_bytes())
+
+    async def lpos(
+        self,
+        key: str,
+        element: Value,
+        *,
+        rank: int | None = None,
+        count: int | None = None,
+        maxlen: int | None = None,
+    ) -> int | list[int] | None:
+        """Find the positions of matching elements in a list.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            element: The element to encode and find.
+            rank: Which match to start with, starting at one. Negative ranks
+                search from the tail; zero is invalid.
+            count: The maximum number of positions to return; zero returns all
+                matches. None returns a single position.
+            maxlen: The maximum number of elements to inspect; zero means
+                unlimited.
+
+        Returns:
+            Without count, the matching index or None. With count, a list of
+            indices, empty if nothing matches.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().list_lpos(
+            key,
+            encode(element),
+            rank=rank,
+            count=count,
+            maxlen=maxlen,
+            source=active_ctx_bytes(),
+        )
+
+    @property
+    def lrange(self) -> _LrangeCommand[bytes]:
+        """The callable LRANGE command.
+
+        Use lrange[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _LrangeCommand(self._get_handle, bytes)
+
+
+class Interface(ReadOnlyInterface):
+    """Read and write commands."""
+
+    async def linsert(self, key: str, position: str, pivot: Value, value: Value) -> int:
+        """Insert an element before or after the first matching pivot.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            position: BEFORE or AFTER, case-insensitively, relative to the first
+                pivot.
+            pivot: The existing element to encode and insert beside.
+            value: The value to encode and store.
+
+        Returns:
+            The resulting length, zero if the key is missing, or -1 if the pivot
+            is missing.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().list_linsert(
+            key, position, encode(pivot), encode(value), source=active_ctx_bytes()
+        )
+
+    @property
+    def lmove(self) -> _LmoveCommand[bytes]:
+        """The callable LMOVE command.
+
+        Use lmove[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _LmoveCommand(self._get_handle, bytes)
+
+    @property
+    def lpop(self) -> _LpopCommand[bytes]:
+        """The callable LPOP command.
+
+        Use lpop[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _LpopCommand(self._get_handle, bytes)
+
+    async def lpush(self, key: str, value: Value, *values: Value) -> int:
+        """Push values onto the head of a list, creating it if needed.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            value: The first value to encode and push.
+            *values: Additional values to encode, in order.
+
+        Returns:
+            The resulting list length. Values are pushed in input order, so the
+            last supplied value becomes the head.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().list_lpush(
+            key,
+            [encode(value), *(encode(item) for item in values)],
+            source=active_ctx_bytes(),
+        )
+
+    async def lpushx(self, key: str, value: Value, *values: Value) -> int:
+        """Push values onto the head of an existing list.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            value: The first value to encode and push.
+            *values: Additional values to encode, in order.
+
+        Returns:
+            The resulting length, or zero if the key is missing. The last
+            supplied value becomes the head.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        values = (value, *values)
+        return await self._get_handle().list_lpushx(
+            key, [encode(value) for value in values], source=active_ctx_bytes()
+        )
+
+    async def lrem(self, key: str, count: int, value: Value) -> int:
+        """Remove matching values from a list.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            count: Remove up to count matches from the head if positive,
+                abs(count) from the tail if negative, or all matches if zero.
+            value: The value to encode and remove.
+
+        Returns:
+            The number of elements removed.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().list_lrem(
+            key, count, encode(value), source=active_ctx_bytes()
+        )
+
+    async def lset(self, key: str, index: int, value: Value) -> None:
+        """Replace the element at a list index.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            index: The zero-based index; negative values count from the end.
+            value: The value to encode and store.
+
+        Raises:
+            EncoreError: The key is missing, the index is out of range, or Redis
+                rejects the command or the request fails.
+        """
+        return await self._get_handle().list_lset(
+            key, index, encode(value), source=active_ctx_bytes()
+        )
+
+    async def ltrim(self, key: str, start: int, stop: int) -> None:
+        """Keep only an inclusive range of list elements.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            start: The inclusive starting index; negative values count from the
+                end.
+            stop: The inclusive ending index; negative values count from the
+                end.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().list_ltrim(
+            key, start, stop, source=active_ctx_bytes()
+        )
+
+    @property
+    def rpop(self) -> _RpopCommand[bytes]:
+        """The callable RPOP command.
+
+        Use rpop[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _RpopCommand(self._get_handle, bytes)
+
+    async def rpush(self, key: str, value: Value, *values: Value) -> int:
+        """Push values onto the tail of a list, creating it if needed.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            value: The first value to encode and push.
+            *values: Additional values to encode, in order.
+
+        Returns:
+            The resulting list length. Values retain their input order.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().list_rpush(
+            key,
+            [encode(value), *(encode(item) for item in values)],
+            source=active_ctx_bytes(),
+        )
+
+    async def rpushx(self, key: str, value: Value, *values: Value) -> int:
+        """Push values onto the tail of an existing list.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            value: The first value to encode and push.
+            *values: Additional values to encode, in order.
+
+        Returns:
+            The resulting length, or zero if the key is missing. Values retain
+            their input order.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        values = (value, *values)
+        return await self._get_handle().list_rpushx(
+            key, [encode(value) for value in values], source=active_ctx_bytes()
+        )