encore-dev 2.0.0a7__py3-none-any.whl

encore/storage/redis/set.py

@@ -0,0 +1,570 @@
+"""Redis 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 ...tracing._context import active_ctx_bytes
+from ._base import CommandInterface, TypedCommand
+from ._values import T, Value, encode, decode, decode_pop, U
+
+
+class _SdiffCommand(TypedCommand[T]):
+    """A callable SDIFF command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _SdiffCommand[U]:
+        """Select the value type for this command.
+
+        Use sdiff[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 _SdiffCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, *keys: str) -> list[T]:
+        """Return members of the first set absent from all subsequent sets.
+
+        Args:
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+
+        Returns:
+            The differing decoded members, in unspecified 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.
+        """
+        keys = (key, *keys)
+        result = await self._get_handle().set_sdiff(keys, source=active_ctx_bytes())
+        return [decode(value, self._value_type) for value in result]
+
+
+class _SinterCommand(TypedCommand[T]):
+    """A callable SINTER command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _SinterCommand[U]:
+        """Select the value type for this command.
+
+        Use sinter[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 _SinterCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, *keys: str) -> list[T]:
+        """Return members present in every supplied set.
+
+        Args:
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+
+        Returns:
+            The common decoded members, in unspecified 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.
+        """
+        keys = (key, *keys)
+        result = await self._get_handle().set_sinter(keys, source=active_ctx_bytes())
+        return [decode(value, self._value_type) for value in result]
+
+
+class _SmembersCommand(TypedCommand[T]):
+    """A callable SMEMBERS command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _SmembersCommand[U]:
+        """Select the value type for this command.
+
+        Use smembers[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 _SmembersCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str) -> list[T]:
+        """Return all members of a set.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            Decoded members, in unspecified 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().set_smembers(key, source=active_ctx_bytes())
+        return [decode(value, self._value_type) for value in result]
+
+
+class _SrandmemberCommand(TypedCommand[T]):
+    """A callable SRANDMEMBER command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _SrandmemberCommand[U]:
+        """Select the value type for this command.
+
+        Use srandmember[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 _SrandmemberCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, *, count: int | None = None
+    ) -> T | list[T] | None:
+        """Choose random members without removing them.
+
+        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.
+
+        Returns:
+            Without count, a decoded member or None if the set is missing. With
+            count, a list, empty if the set 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().set_srandmember(
+            key, count=count, source=active_ctx_bytes()
+        )
+        return decode_pop(result, self._value_type)
+
+
+class _SscanCommand(TypedCommand[T]):
+    """A callable SSCAN command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _SscanCommand[U]:
+        """Select the value type for this command.
+
+        Use sscan[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 _SscanCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        key: str,
+        cursor: int,
+        *,
+        pattern: str | None = None,
+        count: int | None = None,
+    ) -> tuple[int, list[T]]:
+        """Read a batch of 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 members. A zero cursor ends the
+            iteration; an empty batch does not.
+
+        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().set_sscan(
+            key, cursor, pattern=pattern, count=count, source=active_ctx_bytes()
+        )
+        return (result[0], [decode(value, self._value_type) for value in result[1]])
+
+
+class _SunionCommand(TypedCommand[T]):
+    """A callable SUNION command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _SunionCommand[U]:
+        """Select the value type for this command.
+
+        Use sunion[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 _SunionCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, *keys: str) -> list[T]:
+        """Return members present in any supplied set.
+
+        Args:
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+
+        Returns:
+            The combined decoded members, in unspecified 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.
+        """
+        keys = (key, *keys)
+        result = await self._get_handle().set_sunion(keys, source=active_ctx_bytes())
+        return [decode(value, self._value_type) for value in result]
+
+
+class _SpopCommand(TypedCommand[T]):
+    """A callable SPOP command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _SpopCommand[U]:
+        """Select the value type for this command.
+
+        Use spop[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 _SpopCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, *, count: int | None = None
+    ) -> T | list[T] | None:
+        """Remove randomly chosen members from a set.
+
+        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 distinct members to remove.
+                None removes one member and returns it instead of a list.
+
+        Returns:
+            Without count, a decoded member or None if the set is missing. With
+            count, a list of up to count distinct members, empty if 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().set_spop(
+            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."""
+
+    async def scard(self, key: str) -> int:
+        """Return the number of members in a 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().set_scard(key, source=active_ctx_bytes())
+
+    @property
+    def sdiff(self) -> _SdiffCommand[bytes]:
+        """The callable SDIFF command.
+
+        Use sdiff[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _SdiffCommand(self._get_handle, bytes)
+
+    @property
+    def sinter(self) -> _SinterCommand[bytes]:
+        """The callable SINTER command.
+
+        Use sinter[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _SinterCommand(self._get_handle, bytes)
+
+    async def sismember(self, key: str, member: Value) -> bool:
+        """Check whether a set contains a member.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            member: The member to encode.
+
+        Returns:
+            True if the member exists, otherwise False.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().set_sismember(
+            key, encode(member), source=active_ctx_bytes()
+        )
+
+    @property
+    def smembers(self) -> _SmembersCommand[bytes]:
+        """The callable SMEMBERS command.
+
+        Use smembers[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _SmembersCommand(self._get_handle, bytes)
+
+    async def smismember(self, key: str, member: Value, *members: Value) -> list[bool]:
+        """Check membership for several values in input order.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            member: The first member to encode.
+            *members: Additional members to encode, in order.
+
+        Returns:
+            One boolean per supplied member.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        members = (member, *members)
+        return await self._get_handle().set_smismember(
+            key, [encode(value) for value in members], source=active_ctx_bytes()
+        )
+
+    @property
+    def srandmember(self) -> _SrandmemberCommand[bytes]:
+        """The callable SRANDMEMBER command.
+
+        Use srandmember[T](...) to select the decoded value type. Plain calls
+        keep stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _SrandmemberCommand(self._get_handle, bytes)
+
+    @property
+    def sscan(self) -> _SscanCommand[bytes]:
+        """The callable SSCAN command.
+
+        Use sscan[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _SscanCommand(self._get_handle, bytes)
+
+    @property
+    def sunion(self) -> _SunionCommand[bytes]:
+        """The callable SUNION command.
+
+        Use sunion[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _SunionCommand(self._get_handle, bytes)
+
+
+class Interface(ReadOnlyInterface):
+    """Read and write commands."""
+
+    async def sadd(self, key: str, member: Value, *members: Value) -> int:
+        """Add members to a set, creating it if needed.
+
+        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 newly added members, excluding existing members.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        members = (member, *members)
+        return await self._get_handle().set_sadd(
+            key, [encode(value) for value in members], source=active_ctx_bytes()
+        )
+
+    async def sdiffstore(self, destination: str, key: str, *keys: str) -> int:
+        """Store the difference between the first set and subsequent 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.
+
+        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().set_sdiffstore(
+            destination, keys, source=active_ctx_bytes()
+        )
+
+    async def sinterstore(self, destination: str, key: str, *keys: str) -> int:
+        """Store the intersection of the supplied 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.
+
+        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().set_sinterstore(
+            destination, keys, source=active_ctx_bytes()
+        )
+
+    async def smove(self, key: str, destination: str, member: Value) -> bool:
+        """Move a member from one set to another atomically.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            destination: The destination key, without an Encore key prefix.
+            member: The member to encode.
+
+        Returns:
+            True if the member was removed from the source and added to the
+            destination; False if it was absent from the source.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().set_smove(
+            key, destination, encode(member), source=active_ctx_bytes()
+        )
+
+    @property
+    def spop(self) -> _SpopCommand[bytes]:
+        """The callable SPOP command.
+
+        Use spop[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _SpopCommand(self._get_handle, bytes)
+
+    async def srem(self, key: str, member: Value, *members: Value) -> int:
+        """Remove members from a 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().set_srem(
+            key, [encode(value) for value in members], source=active_ctx_bytes()
+        )
+
+    async def sunionstore(self, destination: str, key: str, *keys: str) -> int:
+        """Store the union of the supplied 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.
+
+        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().set_sunionstore(
+            destination, keys, source=active_ctx_bytes()
+        )