encore-dev 2.0.0a7__py3-none-any.whl

encore/storage/redis/hash.py

@@ -0,0 +1,504 @@
+"""Redis hash 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 Any, Optional
+
+from ...tracing._context import active_ctx_bytes
+from ._base import CommandInterface, TypedCommand
+from ._values import T, Value, encode, decode, decode_optional, U
+from . import _responses
+
+
+class _HgetCommand(TypedCommand[T]):
+    """A callable HGET command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _HgetCommand[U]:
+        """Select the value type for this command.
+
+        Use hget[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 _HgetCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, field: str) -> Optional[T]:
+        """Return a hash field's value.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            field: The hash field name.
+
+        Returns:
+            The decoded value, or None if the key or field 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().hash_hget(
+            key, field, source=active_ctx_bytes()
+        )
+        return decode_optional(result, self._value_type)
+
+
+class _HgetallCommand(TypedCommand[T]):
+    """A callable HGETALL command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _HgetallCommand[U]:
+        """Select the value type for this command.
+
+        Use hgetall[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 _HgetallCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str) -> dict[bytes, T]:
+        """Return all fields and values in a hash.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            A dictionary of byte field names to decoded values; 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().hash_hgetall(key, source=active_ctx_bytes())
+        return {
+            field: decode(value, self._value_type) for field, value in result.items()
+        }
+
+
+class _HmgetCommand(TypedCommand[T]):
+    """A callable HMGET command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _HmgetCommand[U]:
+        """Select the value type for this command.
+
+        Use hmget[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 _HmgetCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, field: str, *fields: str) -> list[Optional[T]]:
+        """Return hash values in the requested field order.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            field: The first hash field name.
+            *fields: Additional hash field names, in order.
+
+        Returns:
+            One value per field, with None for missing fields or a missing key.
+
+        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.
+        """
+        fields = (field, *fields)
+        result = await self._get_handle().hash_hmget(
+            key, fields, source=active_ctx_bytes()
+        )
+        return [decode_optional(value, self._value_type) for value in result]
+
+
+class _HrandfieldCommand(TypedCommand[T]):
+    """A callable HRANDFIELD command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _HrandfieldCommand[U]:
+        """Select the value type for this command.
+
+        Use hrandfield[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 _HrandfieldCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, *, count: int | None = None, withvalues: bool = False
+    ) -> Any:
+        """Choose random fields from a hash.
+
+        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.
+            withvalues: Whether to include field values; requires count.
+
+        Returns:
+            Without count, a byte field name or None if the key is missing. With
+            count, a list of byte field names. With withvalues=True, alternating
+            field names and decoded values in RESP2, or nested field/value pairs
+            in RESP3. Only values are decoded.
+
+        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().hash_hrandfield(
+            key, count=count, withvalues=withvalues, source=active_ctx_bytes()
+        )
+        return _responses.fields(result, self._value_type) if withvalues else result
+
+
+class _HscanCommand(TypedCommand[T]):
+    """A callable HSCAN command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _HscanCommand[U]:
+        """Select the value type for this command.
+
+        Use hscan[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 _HscanCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        key: str,
+        cursor: int,
+        *,
+        pattern: str | None = None,
+        count: int | None = None,
+    ) -> tuple[int, dict[bytes, T]]:
+        """Read a batch of hash fields and values 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, fields), where cursor is the next scan cursor and
+            fields is a dictionary from byte field names to decoded values. 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().hash_hscan(
+            key, cursor, pattern=pattern, count=count, source=active_ctx_bytes()
+        )
+        return (
+            result[0],
+            {
+                field: decode(value, self._value_type)
+                for field, value in result[1].items()
+            },
+        )
+
+
+class _HvalsCommand(TypedCommand[T]):
+    """A callable HVALS command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _HvalsCommand[U]:
+        """Select the value type for this command.
+
+        Use hvals[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 _HvalsCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str) -> list[T]:
+        """Return all values in a hash.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            Decoded values, 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().hash_hvals(key, source=active_ctx_bytes())
+        return [decode(value, self._value_type) for value in result]
+
+
+class ReadOnlyInterface(CommandInterface):
+    """Commands available through a read-only database handle."""
+
+    async def hexists(self, key: str, field: str) -> bool:
+        """Check whether a hash contains a field.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            field: The hash field name.
+
+        Returns:
+            True if the field exists, otherwise False.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().hash_hexists(
+            key, field, source=active_ctx_bytes()
+        )
+
+    @property
+    def hget(self) -> _HgetCommand[bytes]:
+        """The callable HGET command.
+
+        Use hget[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _HgetCommand(self._get_handle, bytes)
+
+    @property
+    def hgetall(self) -> _HgetallCommand[bytes]:
+        """The callable HGETALL command.
+
+        Use hgetall[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _HgetallCommand(self._get_handle, bytes)
+
+    async def hkeys(self, key: str) -> list[bytes]:
+        """Return all field names in a hash.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            Field names as bytes, in unspecified order; empty if the key is
+            missing.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().hash_hkeys(key, source=active_ctx_bytes())
+
+    async def hlen(self, key: str) -> int:
+        """Return the number of fields in a hash.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The number of fields, or zero if the key is missing.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().hash_hlen(key, source=active_ctx_bytes())
+
+    @property
+    def hmget(self) -> _HmgetCommand[bytes]:
+        """The callable HMGET command.
+
+        Use hmget[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _HmgetCommand(self._get_handle, bytes)
+
+    @property
+    def hrandfield(self) -> _HrandfieldCommand[bytes]:
+        """The callable HRANDFIELD command.
+
+        Use hrandfield[T](...) to select the decoded value type. Plain calls
+        keep stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _HrandfieldCommand(self._get_handle, bytes)
+
+    @property
+    def hscan(self) -> _HscanCommand[bytes]:
+        """The callable HSCAN command.
+
+        Use hscan[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _HscanCommand(self._get_handle, bytes)
+
+    @property
+    def hvals(self) -> _HvalsCommand[bytes]:
+        """The callable HVALS command.
+
+        Use hvals[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _HvalsCommand(self._get_handle, bytes)
+
+
+class Interface(ReadOnlyInterface):
+    """Read and write commands."""
+
+    async def hdel(self, key: str, field: str, *fields: str) -> int:
+        """Delete fields from a hash.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            field: The first hash field name.
+            *fields: Additional hash field names, in order.
+
+        Returns:
+            The number of fields removed; missing fields are ignored.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        fields = (field, *fields)
+        return await self._get_handle().hash_hdel(
+            key, fields, source=active_ctx_bytes()
+        )
+
+    async def hincrby(self, key: str, field: str, amount: int) -> int:
+        """Add an integer to a hash field, starting from zero if missing.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            field: The hash field name.
+            amount: The amount to add; negative values subtract.
+
+        Returns:
+            The integer value after the increment.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().hash_hincrby(
+            key, field, amount, source=active_ctx_bytes()
+        )
+
+    async def hincrbyfloat(self, key: str, field: str, amount: float) -> float:
+        """Add a number to a hash field, starting from zero if missing.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            field: The hash field name.
+            amount: The amount to add; negative values subtract.
+
+        Returns:
+            The numeric value after the increment.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().hash_hincrbyfloat(
+            key, field, amount, source=active_ctx_bytes()
+        )
+
+    async def hset(
+        self, key: str, item: tuple[str, Value], *items: tuple[str, Value]
+    ) -> int:
+        """Set hash fields, replacing existing values.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            item: The first (field name, value) pair.
+            *items: Additional tuples of the same shape, in order.
+
+        Returns:
+            The number of newly added fields, excluding updated fields.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        items = (item, *items)
+        return await self._get_handle().hash_hset(
+            key,
+            [(field, encode(value)) for field, value in items],
+            source=active_ctx_bytes(),
+        )
+
+    async def hsetnx(self, key: str, field: str, value: Value) -> bool:
+        """Set a hash field only if it does not already exist.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            field: The hash field name.
+            value: The value to encode and store.
+
+        Returns:
+            True if the field was added, otherwise False.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().hash_hsetnx(
+            key, field, encode(value), source=active_ctx_bytes()
+        )