encore-dev 2.0.0a7__py3-none-any.whl

encore/storage/redis/sorted_set.py

@@ -0,0 +1,753 @@
+"""Redis sorted set 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 collections.abc import Sequence
+from typing import Optional
+
+from ...tracing._context import active_ctx_bytes
+from ._base import CommandInterface, TypedCommand
+from ._values import T, Value, encode, decode, decode_sorted, U
+
+
+class _ZrandmemberCommand(TypedCommand[T]):
+    """A callable ZRANDMEMBER command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _ZrandmemberCommand[U]:
+        """Select the value type for this command.
+
+        Use zrandmember[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 _ZrandmemberCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, *, count: int | None = None, withscores: bool = False
+    ) -> T | list[T] | list[tuple[T, float]] | None:
+        """Choose random members from a sorted set.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            count: Without count, return one random item. A positive count
+                selects distinct items; a negative count allows repeats and
+                requests abs(count) items.
+            withscores: Whether to include scores; requires count.
+
+        Returns:
+            Without count, a decoded member or None if missing. With count, a
+            list of members, or (member, float score) tuples when
+            withscores=True.
+
+        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().sorted_set_zrandmember(
+            key, count=count, withscores=withscores, source=active_ctx_bytes()
+        )
+        return decode_sorted(result, self._value_type)
+
+
+class _ZrangeCommand(TypedCommand[T]):
+    """A callable ZRANGE command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _ZrangeCommand[U]:
+        """Select the value type for this command.
+
+        Use zrange[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 _ZrangeCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, start: int, stop: int, *, withscores: bool = False
+    ) -> list[T] | list[tuple[T, float]]:
+        """Return members by rank in ascending score order.
+
+        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.
+            withscores: Whether to include each member's score in the result.
+
+        Returns:
+            Decoded members, or (member, float score) tuples when
+            withscores=True. Equal scores are ordered lexicographically by
+            member bytes.
+
+        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().sorted_set_zrange(
+            key, start, stop, withscores=withscores, source=active_ctx_bytes()
+        )
+        return (
+            [(decode(member, self._value_type), score) for member, score in result]
+            if withscores
+            else [decode(member, self._value_type) for member in result]
+        )
+
+
+class _ZrangebyscoreCommand(TypedCommand[T]):
+    """A callable ZRANGEBYSCORE command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _ZrangebyscoreCommand[U]:
+        """Select the value type for this command.
+
+        Use zrangebyscore[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 _ZrangebyscoreCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        key: str,
+        minimum: str,
+        maximum: str,
+        *,
+        withscores: bool = False,
+        offset: int | None = None,
+        count: int | None = None,
+    ) -> list[T] | list[tuple[T, float]]:
+        """Return members within a score range in ascending order.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            minimum: The lower score bound as a string; prefix with "(" to
+                exclude it. Use "-inf" for no lower bound.
+            maximum: The upper score bound as a string; prefix with "(" to
+                exclude it. Use "+inf" for no upper bound.
+            withscores: Whether to include each member's score in the result.
+            offset: The nonnegative number of matching members to skip; supply
+                together with count.
+            count: The nonnegative maximum number of members to return; supply
+                together with offset.
+
+        Returns:
+            Decoded members, or (member, float score) tuples when
+            withscores=True. Equal scores are ordered lexicographically by
+            member bytes.
+
+        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().sorted_set_zrangebyscore(
+            key,
+            minimum,
+            maximum,
+            withscores=withscores,
+            offset=offset,
+            count=count,
+            source=active_ctx_bytes(),
+        )
+        return (
+            [(decode(member, self._value_type), score) for member, score in result]
+            if withscores
+            else [decode(member, self._value_type) for member in result]
+        )
+
+
+class _ZrevrangeCommand(TypedCommand[T]):
+    """A callable ZREVRANGE command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _ZrevrangeCommand[U]:
+        """Select the value type for this command.
+
+        Use zrevrange[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 _ZrevrangeCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, start: int, stop: int, *, withscores: bool = False
+    ) -> list[T] | list[tuple[T, float]]:
+        """Return members by rank in descending score order.
+
+        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.
+            withscores: Whether to include each member's score in the result.
+
+        Returns:
+            Decoded members, or (member, float score) tuples when
+            withscores=True. Equal scores use reverse lexicographic member
+            order.
+
+        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().sorted_set_zrevrange(
+            key, start, stop, withscores=withscores, source=active_ctx_bytes()
+        )
+        return (
+            [(decode(member, self._value_type), score) for member, score in result]
+            if withscores
+            else [decode(member, self._value_type) for member in result]
+        )
+
+
+class _ZscanCommand(TypedCommand[T]):
+    """A callable ZSCAN command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _ZscanCommand[U]:
+        """Select the value type for this command.
+
+        Use zscan[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 _ZscanCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        key: str,
+        cursor: int,
+        *,
+        pattern: str | None = None,
+        count: int | None = None,
+    ) -> tuple[int, list[tuple[T, float]]]:
+        """Read a batch of sorted-set members using a scan cursor.
+
+        Continue with the returned cursor until it is zero. Scans may return
+        duplicates and do not provide a snapshot while data changes.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            cursor: Zero to start an iteration, or the cursor from the previous
+                call.
+            pattern: A Redis glob pattern to filter results, or None for no
+                filter.
+            count: A hint for work per call, not a result limit; None uses the
+                server default.
+
+        Returns:
+            A tuple (cursor, members), where cursor is the next scan cursor and
+            members is a list of (decoded member, float score) tuples. A zero
+            cursor ends the iteration; an empty batch does not. Members are not
+            sorted.
+
+        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().sorted_set_zscan(
+            key, cursor, pattern=pattern, count=count, source=active_ctx_bytes()
+        )
+        return (
+            result[0],
+            [(decode(member, self._value_type), score) for member, score in result[1]],
+        )
+
+
+class _ZpopmaxCommand(TypedCommand[T]):
+    """A callable ZPOPMAX command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _ZpopmaxCommand[U]:
+        """Select the value type for this command.
+
+        Use zpopmax[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 _ZpopmaxCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, *, count: int = 1) -> list[tuple[T, float]]:
+        """Remove the members with the highest scores.
+
+        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 members to remove; defaults
+                to one.
+
+        Returns:
+            Removed (decoded member, float score) tuples in descending score
+            order; empty 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().sorted_set_zpopmax(
+            key, count=count, source=active_ctx_bytes()
+        )
+        return [(decode(member, self._value_type), score) for member, score in result]
+
+
+class _ZpopminCommand(TypedCommand[T]):
+    """A callable ZPOPMIN command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _ZpopminCommand[U]:
+        """Select the value type for this command.
+
+        Use zpopmin[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 _ZpopminCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, *, count: int = 1) -> list[tuple[T, float]]:
+        """Remove the members with the lowest scores.
+
+        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 members to remove; defaults
+                to one.
+
+        Returns:
+            Removed (decoded member, float score) tuples in ascending score
+            order; empty 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().sorted_set_zpopmin(
+            key, count=count, source=active_ctx_bytes()
+        )
+        return [(decode(member, self._value_type), score) for member, score in result]
+
+
+class ReadOnlyInterface(CommandInterface):
+    """Commands available through a read-only database handle."""
+
+    async def zcard(self, key: str) -> int:
+        """Return the number of members in a sorted set.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The set size, or zero if the key does not exist.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().sorted_set_zcard(key, source=active_ctx_bytes())
+
+    async def zcount(self, key: str, minimum: str, maximum: str) -> int:
+        """Count members within a score range.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            minimum: The lower score bound as a string; prefix with "(" to
+                exclude it. Use "-inf" for no lower bound.
+            maximum: The upper score bound as a string; prefix with "(" to
+                exclude it. Use "+inf" for no upper bound.
+
+        Returns:
+            The number of members whose scores fall within the bounds.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().sorted_set_zcount(
+            key, minimum, maximum, source=active_ctx_bytes()
+        )
+
+    @property
+    def zrandmember(self) -> _ZrandmemberCommand[bytes]:
+        """The callable ZRANDMEMBER command.
+
+        Use zrandmember[T](...) to select the decoded value type. Plain calls
+        keep stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _ZrandmemberCommand(self._get_handle, bytes)
+
+    @property
+    def zrange(self) -> _ZrangeCommand[bytes]:
+        """The callable ZRANGE command.
+
+        Use zrange[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _ZrangeCommand(self._get_handle, bytes)
+
+    @property
+    def zrangebyscore(self) -> _ZrangebyscoreCommand[bytes]:
+        """The callable ZRANGEBYSCORE command.
+
+        Use zrangebyscore[T](...) to select the decoded value type. Plain calls
+        keep stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _ZrangebyscoreCommand(self._get_handle, bytes)
+
+    async def zrank(self, key: str, member: Value) -> Optional[int]:
+        """Return a member's rank in ascending score order.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            member: The member to encode.
+
+        Returns:
+            The zero-based rank, or None if the key or member is missing.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().sorted_set_zrank(
+            key, encode(member), source=active_ctx_bytes()
+        )
+
+    @property
+    def zrevrange(self) -> _ZrevrangeCommand[bytes]:
+        """The callable ZREVRANGE command.
+
+        Use zrevrange[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _ZrevrangeCommand(self._get_handle, bytes)
+
+    async def zrevrank(self, key: str, member: Value) -> Optional[int]:
+        """Return a member's rank in descending score order.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            member: The member to encode.
+
+        Returns:
+            The zero-based rank, or None if the key or member is missing.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().sorted_set_zrevrank(
+            key, encode(member), source=active_ctx_bytes()
+        )
+
+    @property
+    def zscan(self) -> _ZscanCommand[bytes]:
+        """The callable ZSCAN command.
+
+        Use zscan[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _ZscanCommand(self._get_handle, bytes)
+
+    async def zscore(self, key: str, member: Value) -> Optional[float]:
+        """Return a sorted-set member's score.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            member: The member to encode.
+
+        Returns:
+            The score as a float, or None if the key or member is missing.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().sorted_set_zscore(
+            key, encode(member), source=active_ctx_bytes()
+        )
+
+
+class Interface(ReadOnlyInterface):
+    """Read and write commands."""
+
+    async def zadd(
+        self,
+        key: str,
+        item: tuple[float, Value],
+        *items: tuple[float, Value],
+        nx: bool = False,
+        xx: bool = False,
+        gt: bool = False,
+        lt: bool = False,
+        ch: bool = False,
+    ) -> int:
+        """Add members or update their scores in a sorted set.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            item: The first (score, member) pair.
+            *items: Additional tuples of the same shape, in order.
+            nx: Only add new entries; mutually exclusive with xx.
+            xx: Only update existing entries; mutually exclusive with nx.
+            gt: Only update existing scores when the new score is greater;
+                incompatible with lt and nx. New members are still added unless
+                xx=True.
+            lt: Only update existing scores when the new score is smaller;
+                incompatible with gt and nx. New members are still added unless
+                xx=True.
+            ch: Whether to count changed existing members as well as new
+                members.
+
+        Returns:
+            The number of new members, or the number of added and changed
+            members when ch=True.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        items = (item, *items)
+        return await self._get_handle().sorted_set_zadd(
+            key,
+            [(score, encode(member)) for score, member in items],
+            nx=nx,
+            xx=xx,
+            gt=gt,
+            lt=lt,
+            ch=ch,
+            source=active_ctx_bytes(),
+        )
+
+    async def zincrby(self, key: str, amount: float, member: Value) -> float:
+        """Increment a member's score, starting from zero if missing.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            amount: The amount to add; negative values subtract.
+            member: The member to encode.
+
+        Returns:
+            The resulting score as a float.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().sorted_set_zincrby(
+            key, amount, encode(member), source=active_ctx_bytes()
+        )
+
+    async def zinterstore(
+        self,
+        destination: str,
+        key: str,
+        *keys: str,
+        weights: Sequence[float] | None = None,
+        aggregate: str | None = None,
+    ) -> int:
+        """Store the weighted intersection of sorted sets.
+
+        Args:
+            destination: The destination key, without an Encore key prefix.
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+            weights: One score multiplier per source key, or None to use one for
+                each.
+            aggregate: The case-insensitive score aggregation: SUM, MIN, or MAX.
+                Defaults to SUM.
+
+        Returns:
+            The number of members stored, replacing the destination's previous
+            value.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        keys = (key, *keys)
+        return await self._get_handle().sorted_set_zinterstore(
+            destination,
+            keys,
+            weights=weights,
+            aggregate=aggregate,
+            source=active_ctx_bytes(),
+        )
+
+    @property
+    def zpopmax(self) -> _ZpopmaxCommand[bytes]:
+        """The callable ZPOPMAX command.
+
+        Use zpopmax[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _ZpopmaxCommand(self._get_handle, bytes)
+
+    @property
+    def zpopmin(self) -> _ZpopminCommand[bytes]:
+        """The callable ZPOPMIN command.
+
+        Use zpopmin[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _ZpopminCommand(self._get_handle, bytes)
+
+    async def zrem(self, key: str, member: Value, *members: Value) -> int:
+        """Remove members from a sorted set.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            member: The first member to encode.
+            *members: Additional members to encode, in order.
+
+        Returns:
+            The number of members removed; absent members are ignored.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        members = (member, *members)
+        return await self._get_handle().sorted_set_zrem(
+            key, [encode(value) for value in members], source=active_ctx_bytes()
+        )
+
+    async def zremrangebyrank(self, key: str, start: int, stop: int) -> int:
+        """Remove members within an inclusive rank range.
+
+        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:
+            The number of members removed.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().sorted_set_zremrangebyrank(
+            key, start, stop, source=active_ctx_bytes()
+        )
+
+    async def zremrangebyscore(self, key: str, minimum: str, maximum: str) -> int:
+        """Remove members within a score range.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            minimum: The lower score bound as a string; prefix with "(" to
+                exclude it. Use "-inf" for no lower bound.
+            maximum: The upper score bound as a string; prefix with "(" to
+                exclude it. Use "+inf" for no upper bound.
+
+        Returns:
+            The number of members removed.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().sorted_set_zremrangebyscore(
+            key, minimum, maximum, source=active_ctx_bytes()
+        )
+
+    async def zunionstore(
+        self,
+        destination: str,
+        key: str,
+        *keys: str,
+        weights: Sequence[float] | None = None,
+        aggregate: str | None = None,
+    ) -> int:
+        """Store the weighted union of sorted sets.
+
+        Args:
+            destination: The destination key, without an Encore key prefix.
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+            weights: One score multiplier per source key, or None to use one for
+                each.
+            aggregate: The case-insensitive score aggregation: SUM, MIN, or MAX.
+                Defaults to SUM.
+
+        Returns:
+            The number of members stored, replacing the destination's previous
+            value.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        keys = (key, *keys)
+        return await self._get_handle().sorted_set_zunionstore(
+            destination,
+            keys,
+            weights=weights,
+            aggregate=aggregate,
+            source=active_ctx_bytes(),
+        )