encore-dev 2.0.0a7__py3-none-any.whl

encore/storage/redis/__init__.py

@@ -0,0 +1,200 @@
+"""Redis databases and explicit read-only/read-write handles.
+
+Declare Database(name) at module scope. Call commands directly on its families,
+or pass read()/write() handles to other functions.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from ...internal.lazy import Lazy
+from ...internal.runtime import _native, runtime
+from . import generic as _generic
+from . import string as _string
+from . import bitmap as _bitmap
+from . import hash as _hash
+from . import json as _json
+from . import list as _list
+from . import set as _set
+from . import sorted_set as _sorted_set
+from . import geo as _geo
+from . import stream as _stream
+from . import pubsub as _pubsub
+
+from ._values import RedisValue, Value
+
+__all__ = ["Database", "DatabaseRef", "ReadOnlyDatabaseRef", "RedisValue", "Value"]
+
+
+class ReadOnlyDatabaseRef:
+    """A handle exposing read-only command interfaces."""
+
+    def __init__(self, get_handle: Callable[[], _native.RedisDatabase]) -> None:
+        """Initialize a handle that resolves its connection on first use.
+
+        Args:
+            get_handle: A factory returning the native database handle. Use
+                Database.read() to obtain a read-only handle in application
+                code.
+        """
+        self._handle = Lazy(get_handle)
+
+    @property
+    def generic(self) -> _generic.ReadOnlyInterface:
+        """Read-only generic key commands for this handle."""
+        return _generic.ReadOnlyInterface(self._handle.get)
+
+    @property
+    def string(self) -> _string.ReadOnlyInterface:
+        """Read-only string commands for this handle."""
+        return _string.ReadOnlyInterface(self._handle.get)
+
+    @property
+    def bitmap(self) -> _bitmap.ReadOnlyInterface:
+        """Read-only bitmap commands for this handle."""
+        return _bitmap.ReadOnlyInterface(self._handle.get)
+
+    @property
+    def hash(self) -> _hash.ReadOnlyInterface:
+        """Read-only hash commands for this handle."""
+        return _hash.ReadOnlyInterface(self._handle.get)
+
+    @property
+    def json(self) -> _json.ReadOnlyInterface:
+        """Read-only RedisJSON commands for this handle."""
+        return _json.ReadOnlyInterface(self._handle.get)
+
+    @property
+    def list(self) -> _list.ReadOnlyInterface:
+        """Read-only list commands for this handle."""
+        return _list.ReadOnlyInterface(self._handle.get)
+
+    @property
+    def set(self) -> _set.ReadOnlyInterface:
+        """Read-only set commands for this handle."""
+        return _set.ReadOnlyInterface(self._handle.get)
+
+    @property
+    def sorted_set(self) -> _sorted_set.ReadOnlyInterface:
+        """Read-only sorted-set commands for this handle."""
+        return _sorted_set.ReadOnlyInterface(self._handle.get)
+
+    @property
+    def geo(self) -> _geo.ReadOnlyInterface:
+        """Read-only geospatial commands for this handle."""
+        return _geo.ReadOnlyInterface(self._handle.get)
+
+    @property
+    def stream(self) -> _stream.ReadOnlyInterface:
+        """Read-only stream commands for this handle."""
+        return _stream.ReadOnlyInterface(self._handle.get)
+
+    @property
+    def pubsub(self) -> _pubsub.ReadOnlyInterface:
+        """Read-only Redis channel commands for this handle."""
+        return _pubsub.ReadOnlyInterface(self._handle.get)
+
+
+class DatabaseRef(ReadOnlyDatabaseRef):
+    """A handle exposing read and write command interfaces."""
+
+    @property
+    def connection_string(self) -> str:
+        """The direct Redis server URL, including connection credentials.
+
+        External clients using this URL do not apply Encore key prefixes.
+
+        Raises:
+            EncoreError: The database connection cannot be initialized.
+        """
+        return self._handle.get().connection_string()
+
+    @property
+    def generic(self) -> _generic.Interface:
+        """Read-write generic key commands for this handle."""
+        return _generic.Interface(self._handle.get)
+
+    @property
+    def string(self) -> _string.Interface:
+        """Read-write string commands for this handle."""
+        return _string.Interface(self._handle.get)
+
+    @property
+    def bitmap(self) -> _bitmap.Interface:
+        """Read-write bitmap commands for this handle."""
+        return _bitmap.Interface(self._handle.get)
+
+    @property
+    def hash(self) -> _hash.Interface:
+        """Read-write hash commands for this handle."""
+        return _hash.Interface(self._handle.get)
+
+    @property
+    def json(self) -> _json.Interface:
+        """Read-write RedisJSON commands for this handle."""
+        return _json.Interface(self._handle.get)
+
+    @property
+    def list(self) -> _list.Interface:
+        """Read-write list commands for this handle."""
+        return _list.Interface(self._handle.get)
+
+    @property
+    def set(self) -> _set.Interface:
+        """Read-write set commands for this handle."""
+        return _set.Interface(self._handle.get)
+
+    @property
+    def sorted_set(self) -> _sorted_set.Interface:
+        """Read-write sorted-set commands for this handle."""
+        return _sorted_set.Interface(self._handle.get)
+
+    @property
+    def geo(self) -> _geo.Interface:
+        """Read-write geospatial commands for this handle."""
+        return _geo.Interface(self._handle.get)
+
+    @property
+    def stream(self) -> _stream.Interface:
+        """Read-write stream commands for this handle."""
+        return _stream.Interface(self._handle.get)
+
+    @property
+    def pubsub(self) -> _pubsub.Interface:
+        """Read-write Redis channel commands for this handle."""
+        return _pubsub.Interface(self._handle.get)
+
+
+class Database(DatabaseRef):
+    """A named Redis database with read and write command interfaces.
+
+    Declare the database at module scope so Encore can discover it. Connections
+    are resolved lazily when a command is executed.
+    """
+
+    def __init__(self, name: str) -> None:
+        """Declare a Redis database resource.
+
+        Args:
+            name: The database's logical name in the Encore application.
+        """
+        self._name = name
+        super().__init__(lambda: runtime().redis_database(name))
+
+    def write(self) -> DatabaseRef:
+        """Return a handle granting read-write access to this database."""
+        return DatabaseRef(lambda: self._handle.get().write())
+
+    def read(self, primary: bool = False) -> ReadOnlyDatabaseRef:
+        """Return a read-only handle.
+
+        Args:
+            primary: Whether to request the primary server even when replicas
+                are available. Currently all reads use the primary, including
+                when this is False.
+
+        Returns:
+            A lazy handle exposing only read-only command interfaces.
+        """
+        return ReadOnlyDatabaseRef(lambda: self._handle.get().read(primary=primary))

encore/storage/redis/_base.py

@@ -0,0 +1,42 @@
+"""Shared lazy native-handle access for Redis command families."""
+
+from collections.abc import Callable
+from typing import Generic
+
+from ._values import T, validate_decoder
+
+from ...internal.runtime import _native
+
+
+class CommandInterface:
+    """A command family backed by a lazily resolved native database handle."""
+
+    def __init__(self, get_handle: Callable[[], _native.RedisDatabase]) -> None:
+        """Initialize a command family without opening a connection.
+
+        Args:
+            get_handle: A factory returning the native database handle.
+        """
+        self._get_handle = get_handle
+
+
+class TypedCommand(CommandInterface, Generic[T]):
+    """A lazy command bound to a value decoder, selected with command[T]."""
+
+    def __init__(
+        self,
+        get_handle: Callable[[], _native.RedisDatabase],
+        value_type: type[T],
+    ) -> None:
+        """Bind a lazy command to a value decoder.
+
+        Args:
+            get_handle: A factory returning the native database handle when
+                called.
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue. The type selects how stored values are decoded;
+                command metadata is unchanged.
+        """
+        validate_decoder(value_type)
+        super().__init__(get_handle)
+        self._value_type = value_type

encore/storage/redis/_responses.py

@@ -0,0 +1,150 @@
+"""Decode values in raw RESP replies without converting command metadata."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._values import T, decode
+
+
+def fields(data: Any, as_type: type[T]) -> Any:
+    """Decode hash or stream values while preserving field names.
+
+    Decoding errors propagate to the caller.
+
+    Args:
+        data: A flat alternating field/value list, nested field/value pairs, a
+            field-to-value dictionary, or None.
+        as_type: A validated value decoder.
+
+    Returns:
+        The corresponding field/value layout with decoded values. None and the
+        default bytes mode are preserved.
+    """
+    if data is None or as_type is bytes:
+        return data
+    if isinstance(data, dict):
+        return {key: decode(value, as_type) for key, value in data.items()}
+    if data and isinstance(data[0], (list, tuple)):
+        return [[key, decode(value, as_type)] for key, value in data]
+    return [
+        decode(value, as_type) if index % 2 else value
+        for index, value in enumerate(data)
+    ]
+
+
+def entries(data: Any, as_type: type[T]) -> Any:
+    """Decode stream entry values while preserving IDs and field names.
+
+    Decoding errors propagate to the caller.
+
+    Args:
+        data: A list of [entry ID, fields] pairs, or None. Fields may be None
+            for deleted pending entries.
+        as_type: A validated value decoder.
+
+    Returns:
+        A list of entries with decoded field values. Entry IDs, field names, and
+        missing fields are preserved.
+    """
+    if data is None or as_type is bytes:
+        return data
+    return [[entry_id, fields(values, as_type)] for entry_id, values in data]
+
+
+def streams(data: Any, as_type: type[T]) -> Any:
+    """Decode stream values while preserving stream keys and reply layout.
+
+    Decoding errors propagate to the caller.
+
+    Args:
+        data: An XREAD or XREADGROUP reply: a stream-key dictionary in RESP3, a
+            list of [stream key, entries] pairs in RESP2, or None.
+        as_type: A validated value decoder.
+
+    Returns:
+        The same protocol layout with decoded field values. Stream keys, entry
+        IDs, field names, and None are preserved.
+    """
+    if data is None or as_type is bytes:
+        return data
+    if isinstance(data, dict):
+        return {key: entries(values, as_type) for key, values in data.items()}
+    return [[key, entries(values, as_type)] for key, values in data]
+
+
+def autoclaim(data: Any, as_type: type[T], justid: bool) -> Any:
+    """Decode claimed stream entries while preserving claim metadata.
+
+    Decoding errors propagate to the caller.
+
+    Args:
+        data: An XAUTOCLAIM reply containing the next scan ID, claimed entries,
+            and optionally deleted entry IDs.
+        as_type: A validated value decoder.
+        justid: Whether the reply contains entry IDs instead of entries.
+
+    Returns:
+        The reply with decoded entry values. Scan IDs and deleted IDs are
+        unchanged; ID-only replies are returned unchanged.
+    """
+    if justid or data is None or as_type is bytes:
+        return data
+    return [data[0], entries(data[1], as_type), *data[2:]]
+
+
+def stream_info(data: Any, as_type: type[T]) -> Any:
+    """Decode values in stream information without changing metadata.
+
+    Decoding errors propagate to the caller.
+
+    Args:
+        data: An XINFO STREAM reply: a metadata dictionary in RESP3 or an
+            alternating key/value list in RESP2.
+        as_type: A validated value decoder.
+
+    Returns:
+        The same layout with values decoded in first-entry, last-entry, and
+        entries. All other metadata is unchanged.
+    """
+    if data is None or as_type is bytes:
+        return data
+
+    def convert(key: bytes, value: Any) -> Any:
+        """Decode only metadata fields containing stored stream entries."""
+        if key in (b"first-entry", b"last-entry"):
+            return None if value is None else entries([value], as_type)[0]
+        if key == b"entries":
+            return entries(value, as_type)
+        return value
+
+    if isinstance(data, dict):
+        return {key: convert(key, value) for key, value in data.items()}
+    return [
+        convert(data[index - 1], value) if index % 2 else value
+        for index, value in enumerate(data)
+    ]
+
+
+def geo_members(data: Any, as_type: type[T]) -> Any:
+    """Decode geospatial members without changing result metadata.
+
+    Decoding errors propagate to the caller.
+
+    Args:
+        data: A list of members or rows starting with a member. Store variants
+            may instead return a count.
+        as_type: A validated value decoder.
+
+    Returns:
+        Decoded members, with any distances, coordinates, and hashes unchanged.
+        Counts and other non-list replies are returned unchanged.
+    """
+    if not isinstance(data, list) or as_type is bytes:
+        return data
+    return [
+        [decode(row[0], as_type), *row[1:]]
+        if isinstance(row, list)
+        else decode(row, as_type)
+        for row in data
+    ]

encore/storage/redis/_values.py

@@ -0,0 +1,189 @@
+"""Encoding and explicit per-command decoding of Redis values."""
+
+from __future__ import annotations
+
+from typing import Protocol, TypeVar, Union, cast
+
+_R = TypeVar("_R", bound="RedisValue")
+
+
+class RedisValue(Protocol):
+    """A value that can serialize itself to Redis and reconstruct itself.
+
+    Implementing these methods is sufficient; inheritance is not required.
+    Encoding must return bytes. Decoding errors propagate to the caller.
+    """
+
+    def encode(self) -> bytes:
+        """Serialize this value for storage in Redis.
+
+        The SDK calls this method when writing a custom value. Encoding errors
+        propagate to the caller before the command is sent.
+
+        Returns:
+            The bytes to store. The class's decode() method must be able to
+            reconstruct the value from these bytes.
+        """
+        ...
+
+    @classmethod
+    def decode(cls: type[_R], data: bytes) -> _R:
+        """Reconstruct a value from its stored representation.
+
+        The SDK calls this method for reads such as db.string.get[MyValue](key).
+        Raise an exception if the bytes cannot be decoded; decoding errors
+        propagate to the caller rather than being treated as missing values.
+
+        Args:
+            data: The stored representation produced by encode().
+
+        Returns:
+            An instance of the class on which decode() was called.
+        """
+        ...
+
+
+# Union (rather than |) keeps this runtime type alias compatible with Python 3.9.
+Value = Union[int, float, str, bytes, RedisValue]
+T = TypeVar("T", bound=Value)
+U = TypeVar("U", bound=Value)
+
+
+def encode(value: Value) -> bytes:
+    """Encode a value for a Redis command.
+
+    Floats use Python's repr() as ASCII text, including nan and infinities.
+    Redis numeric commands may reject non-finite values. Custom encoding errors
+    propagate before the command is sent.
+
+    Args:
+        value: Bytes, UTF-8 text, an integer, a float, or a RedisValue
+            implementation. Booleans are not supported. Custom encoders must
+            return bytes.
+
+    Returns:
+        Bytes unchanged, UTF-8-encoded text, ASCII numeric text, or the
+        custom encoder's result.
+    """
+    if isinstance(value, bytes):
+        return value
+    if isinstance(value, str):
+        return value.encode("utf-8")
+    if isinstance(value, bool):
+        raise TypeError(
+            "Redis values must be bytes, str, int, float, or RedisValue; not bool"
+        )
+    if isinstance(value, int):
+        return str(value).encode("ascii")
+    if isinstance(value, float):
+        return repr(value).encode("ascii")
+    encoder = getattr(value, "encode", None)
+    if not callable(encoder):
+        raise TypeError("Redis values must be bytes, str, int, float, or RedisValue")
+    result = encoder()
+    if not isinstance(result, bytes):
+        raise TypeError("RedisValue.encode() must return bytes")
+    return result
+
+
+def decode(data: bytes, as_type: type[T]) -> T:
+    """Decode one stored value using a validated decoder.
+
+    Custom decoding errors propagate to the caller. This helper does not decode
+    keys, field names, or other command metadata.
+
+    Args:
+        data: The stored value.
+        as_type: bytes, str, int, float, or a class implementing RedisValue.
+
+    Returns:
+        The value decoded as as_type; bytes are returned unchanged.
+
+    Raises:
+        UnicodeDecodeError: The stored value is not UTF-8 when as_type is str.
+        ValueError: The stored value cannot be parsed when as_type is int or
+            float.
+    """
+    if as_type is bytes:
+        return cast(T, data)
+    if as_type is str:
+        return cast(T, data.decode("utf-8"))
+    if as_type is int:
+        return cast(T, int(data))
+    if as_type is float:
+        return cast(T, float(data))
+    return cast(T, cast("type[RedisValue]", as_type).decode(data))
+
+
+def validate_decoder(as_type: type[T]) -> None:
+    """Validate a decoder before a command can affect Redis.
+
+    Args:
+        as_type: The proposed runtime decoder class.
+
+    Raises:
+        TypeError: The decoder is not bytes, str, int, float, or a class with a
+            callable decode() method.
+    """
+    if as_type in (bytes, str, int, float):
+        return
+    if not isinstance(as_type, type) or not callable(getattr(as_type, "decode", None)):
+        raise TypeError(
+            "The type argument must be bytes, str, int, float, or a RedisValue class"
+        )
+
+
+def decode_optional(data: bytes | None, as_type: type[T]) -> T | None:
+    """Decode a stored value, preserving None for a missing value.
+
+    Args:
+        data: A stored value or None.
+        as_type: A validated value decoder.
+
+    Returns:
+        The decoded value, or None without invoking the decoder.
+    """
+    return None if data is None else decode(data, as_type)
+
+
+def decode_pop(
+    data: bytes | list[bytes] | None, as_type: type[T]
+) -> T | list[T] | None:
+    """Decode a single value or collection returned by a pop command.
+
+    Args:
+        data: A single value, a list of values, or None for a missing key.
+        as_type: A validated value decoder.
+
+    Returns:
+        A decoded value, a list of decoded values, or None, matching the input
+        shape. Empty lists stay empty. Decoding errors propagate.
+    """
+    if isinstance(data, list):
+        return [decode(value, as_type) for value in data]
+    return decode_optional(data, as_type)
+
+
+def decode_sorted(
+    data: bytes | list[bytes] | list[tuple[bytes, float]] | None,
+    as_type: type[T],
+) -> T | list[T] | list[tuple[T, float]] | None:
+    """Decode sorted-set members while preserving scores and reply shape.
+
+    Args:
+        data: A member, a list of members, a list of (member, score) tuples, or
+            None for a missing key.
+        as_type: A validated member decoder.
+
+    Returns:
+        The same reply shape with decoded members and unchanged numeric scores.
+        Empty lists and None are preserved. Decoding errors propagate.
+    """
+    if isinstance(data, list):
+        if data and isinstance(data[0], tuple):
+            return [
+                (decode(member, as_type), score)
+                for member, score in cast("list[tuple[bytes, float]]", data)
+            ]
+        return [decode(member, as_type) for member in cast("list[bytes]", data)]
+    return decode_optional(data, as_type)