coredis 5.5.0__cp313-cp313-macosx_11_0_arm64.whl

coredis/response/types.py

@@ -0,0 +1,416 @@
+from __future__ import annotations
+
+import dataclasses
+import datetime
+import re
+import shlex
+from collections.abc import Set
+from re import Pattern
+
+from coredis.typing import (
+    ClassVar,
+    Literal,
+    Mapping,
+    NamedTuple,
+    OrderedDict,
+    RedisValueT,
+    StringT,
+    TypedDict,
+)
+
+#: Response from `CLIENT INFO <https://redis.io/commands/client-info>`__
+#:
+#: - ``id``: a unique 64-bit client ID
+#: - ``addr``: address/port of the client
+#: - ``laddr``: address/port of local address client connected to (bind address)
+#: - ``fd``: file descriptor corresponding to the socket
+#: - ``name``: the name set by the client with CLIENT SETNAME
+#: - ``age``: total duration of the connection in seconds
+#: - ``idle``: idle time of the connection in seconds
+#: - ``flags``: client flags
+#: - ``db``: current database ID
+#: - ``sub``: number of channel subscriptions
+#: - ``psub``: number of pattern matching subscriptions
+#: - ``multi``: number of commands in a MULTI/EXEC context
+#: - ``qbuf``: query buffer length (0 means no query pending)
+#: - ``qbuf-free``: free space of the query buffer (0 means the buffer is full)
+#: - ``argv-mem``: incomplete arguments for the next command (already extracted from query buffer)
+#: - ``multi-mem``: memory is used up by buffered multi commands. Added in Redis 7.0
+#: - ``obl``: output buffer length
+#: - ``oll``: output list length (replies are queued in this list when the buffer is full)
+#: - ``omem``: output buffer memory usage
+#: - ``tot-mem``: total memory consumed by this client in its various buffers
+#: - ``events``: file descriptor events
+#: - ``cmd``: last command played
+#: - ``user``: the authenticated username of the client
+#: - ``redir``: client id of current client tracking redirection
+#: - ``resp``: client RESP protocol version. Added in Redis 7.0
+ClientInfo = TypedDict(
+    "ClientInfo",
+    {
+        "id": int,
+        "addr": str,
+        "laddr": str,
+        "fd": int,
+        "name": str,
+        "age": int,
+        "idle": int,
+        "flags": str,
+        "db": int,
+        "sub": int,
+        "psub": int,
+        "multi": int,
+        "qbuf": int,
+        "qbuf-free": int,
+        "argv-mem": int,
+        "multi-mem": int,
+        "obl": int,
+        "oll": int,
+        "omem": int,
+        "tot-mem": int,
+        "events": str,
+        "cmd": str,
+        "user": str,
+        "redir": int,
+        "resp": str,
+    },
+)
+
+#: Script/Function flags
+#: See: `<https://redis.io/topics/lua-api#a-namescriptflagsa-script-flags>`__
+ScriptFlag = Literal[
+    "no-writes",
+    "allow-oom",
+    "allow-stale",
+    "no-cluster",
+    b"no-writes",
+    b"allow-oom",
+    b"allow-stale",
+    b"no-cluster",
+]
+
+
+class FunctionDefinition(TypedDict):
+    """
+    Function definition as returned by `FUNCTION LIST <https://redis.io/commands/function-list>`__
+    """
+
+    #: the name of the function
+    name: StringT
+    #: the description of the function
+    description: StringT
+    #: function flags
+    flags: set[ScriptFlag]
+
+
+class LibraryDefinition(TypedDict):
+    """
+    Library definition as returned by `FUNCTION LIST <https://redis.io/commands/function-list>`__
+    """
+
+    #: the name of the library
+    name: StringT
+    #: the engine used by the library
+    engine: Literal["LUA"]
+    #: Mapping of function names to functions in the library
+    functions: dict[StringT, FunctionDefinition]
+    #: The library's source code
+    library_code: StringT | None
+
+
+class ScoredMember(NamedTuple):
+    """
+    Member of a sorted set
+    """
+
+    #: The sorted set member name
+    member: StringT
+    #: Score of the member
+    score: float
+
+
+class GeoCoordinates(NamedTuple):
+    """
+    A longitude/latitude pair identifying a location
+    """
+
+    #: Longitude
+    longitude: float
+    #: Latitude
+    latitude: float
+
+
+ScoredMembers = tuple[ScoredMember, ...]
+
+
+class GeoSearchResult(NamedTuple):
+    """
+    Structure of a geo query
+    """
+
+    #: Place name
+    name: StringT
+    #: Distance
+    distance: float | None
+    #: GeoHash
+    geohash: int | None
+    #: Lat/Lon
+    coordinates: GeoCoordinates | None
+
+
+#: Definition of a redis command
+#: See: `<https://redis.io/topics/key-specs>`__
+#:
+#: - ``name``: This is the command's name in lowercase
+#: - ``arity``: Arity is the number of arguments a command expects.
+#: - ``flags``: See `<https://redis.io/commands/command#flags>`__
+#: - ``first-key``: This value identifies the position of the command's first key name argumen
+#: - ``last-key``: This value identifies the position of the command's last key name argument
+#: - ``step``: This value is the step, or increment, between the first key and last key values
+#:   where the keys are.
+#: - ``acl-categories``: This is an array of simple strings that are the ACL categories to which
+#:   the command belongs
+#: - ``tips``: Helpful information about the command
+#: - ``key-specification``: This is an array consisting of the command's key specifications
+#: - ``sub-commands``: This is an array containing all of the command's subcommands, if any
+Command = TypedDict(
+    "Command",
+    {
+        "name": str,
+        "arity": int,
+        "flags": Set[str],
+        "first-key": int,
+        "last-key": int,
+        "step": int,
+        "acl-categories": Set[str] | None,
+        "tips": Set[str] | None,
+        "key-specifications": Set[Mapping[str, int | str | Mapping]] | None,  # type: ignore
+        "sub-commands": tuple[str, ...] | None,
+    },
+)
+
+
+class RoleInfo(NamedTuple):
+    """
+    Redis instance role information
+    """
+
+    #:
+    role: str
+    #:
+    offset: int | None = None
+    #:
+    status: str | None = None
+    #:
+    slaves: tuple[dict[str, str | int], ...] | None = None
+    #:
+    masters: tuple[str, ...] | None = None
+
+
+class StreamEntry(NamedTuple):
+    """
+    Structure representing an entry in a redis stream
+    """
+
+    identifier: StringT
+    field_values: OrderedDict[StringT, StringT]
+
+
+#: Details of a stream
+#: See: `<https://redis.io/commands/xinfo-stream>`__
+StreamInfo = TypedDict(
+    "StreamInfo",
+    {
+        "first-entry": StreamEntry | None,
+        "last-entry": StreamEntry | None,
+        "length": int,
+        "radix-tree-keys": int,
+        "radix-tree-nodes": int,
+        "groups": int | list[dict],  # type: ignore
+        "last-generated-id": str,
+        "max-deleted-entry-id": str,
+        "recorded-first-entry-id": str,
+        "entries-added": int,
+        "entries-read": int,
+        "entries": tuple[StreamEntry, ...] | None,
+    },
+)
+
+
+class StreamPending(NamedTuple):
+    """
+    Summary response from
+    `XPENDING <https://redis.io/commands/xpending#summary-form-of-xpending>`__
+    """
+
+    pending: int
+    minimum_identifier: StringT
+    maximum_identifier: StringT
+    consumers: OrderedDict[StringT, int]
+
+
+class StreamPendingExt(NamedTuple):
+    """
+    Extended form response from
+    `XPENDING <https://redis.io/commands/xpending#extended-form-of-xpending>`__
+    """
+
+    identifier: StringT
+    consumer: StringT
+    idle: int
+    delivered: int
+
+
+#: Response from `SLOWLOG GET <https://redis.io/commands/slowlog-get>`__
+class SlowLogInfo(NamedTuple):
+    #: A unique progressive identifier for every slow log entry.
+    id: int
+    #: The unix timestamp at which the logged command was processed.
+    start_time: int
+    #: The amount of time needed for its execution, in microseconds.
+    duration: int
+    #: The array composing the arguments of the command.
+    command: tuple[StringT, ...]
+    #: Client IP address and port
+    client_addr: tuple[StringT, int]
+    #: Client name
+    client_name: str
+
+
+class LCSMatch(NamedTuple):
+    """
+    An instance of an LCS match
+    """
+
+    #: Start/end offset of the first string
+    first: tuple[int, int]
+    #: Start/end offset of the second string
+    second: tuple[int, int]
+    #: Length of the match
+    length: int | None
+
+
+class LCSResult(NamedTuple):
+    """
+    Results from `LCS <https://redis.io/commands/lcs>`__
+    """
+
+    #: matches
+    matches: tuple[LCSMatch, ...]
+    #: Length of longest match
+    length: int
+
+
+@dataclasses.dataclass
+class MonitorResult:
+    """
+    Details of issued commands received by the client when
+    listening with the `MONITOR <https://redis.io/commands/monitor>`__
+    command
+    """
+
+    #: Time command was received
+    time: datetime.datetime
+    #: db number
+    db: int
+    #: (host, port) or path if the server is listening on a unix domain socket
+    client_addr: tuple[str, int] | str | None
+    #: The type of the client that send the command
+    client_type: Literal["tcp", "unix", "lua"]
+    #: The name of the command
+    command: str
+    #: Arguments passed to the command
+    args: tuple[str, ...] | None
+
+    EXPR: ClassVar[Pattern[str]] = re.compile(r"\[(\d+) (.*?)\] (.*)$")
+
+    @classmethod
+    def parse_response_string(cls, response: str) -> MonitorResult:
+        command_time, command_data = response.split(" ", 1)
+        match = cls.EXPR.match(command_data)
+        assert match
+        db_id, client_info, command = match.groups()
+        command = shlex.split(command)
+        client_addr = None
+        client_type: Literal["tcp", "unix", "lua"]
+        if client_info == "lua":
+            client_type = "lua"
+        elif client_info.startswith("unix"):
+            client_type = "unix"
+            client_addr = client_info[5:]
+        else:
+            host, port = client_info.rsplit(":", 1)
+            client_addr = (host, int(port))
+            client_type = "tcp"
+        return cls(
+            time=datetime.datetime.fromtimestamp(float(command_time)),
+            db=int(db_id),
+            client_addr=client_addr,
+            client_type=client_type,
+            command=command[0],
+            args=tuple(command[1:]),
+        )
+
+
+class ClusterNode(TypedDict):
+    host: str
+    port: int
+    node_id: str | None
+    server_type: Literal["master", "slave"] | None
+
+
+class ClusterNodeDetail(TypedDict):
+    id: str
+    flags: tuple[str, ...]
+    host: str
+    port: int
+    master: str | None
+    ping_sent: int
+    pong_recv: int
+    link_state: str
+    slots: list[int]
+    migrations: list[dict[str, RedisValueT]]
+
+
+class PubSubMessage(TypedDict):
+    #: One of the following:
+    #:
+    #: subscribe
+    #:   Server response when a client subscribes to a channel(s)
+    #: unsubscribe
+    #:   Server response when a client unsubscribes from a channel(s)
+    #: psubscribe
+    #:   Server response when a client subscribes to a pattern(s)
+    #: punsubscribe
+    #:   Server response when a client unsubscribes from a pattern(s)
+    #: ssubscribe
+    #:   Server response when a client subscribes to a shard channel(s)
+    #: sunsubscribe
+    #:   Server response when a client unsubscribes from a shard channel(s)
+    #: message
+    #:   A message received from subscribing to a channel
+    #: pmessage
+    #:   A message received from subscribing to a pattern
+    type: str
+    #: The channel subscribed to or unsubscribed from or the channel a message was published to
+    channel: StringT
+    #: The pattern that was subscribed to or unsubscribed from or to which a received message was
+    #: routed to
+    pattern: StringT | None
+    #: - If ``type`` is one of ``{message, pmessage}`` this is the actual published message
+    #: - If ``type`` is one of
+    #:   ``{subscribe, psubscribe, ssubscribe, unsubscribe, punsubscribe, sunsubscribe}``
+    #:   this will be an :class:`int` corresponding to the  number of channels and patterns that the
+    #:   connection is currently subscribed to.
+    data: int | StringT
+
+
+class VectorData(TypedDict):
+    #: The quantization type as a string (``fp32``, ``bin`` or ``q8``)
+    quantization: str
+    #: Raw bytes representation of the vector
+    blob: bytes
+    #: The L2 norm of the vector before normalization
+    l2_norm: float
+    #: If the vector is quantized as q8, the quantization range
+    quantization_range: float

coredis/retry.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from functools import wraps
+from typing import Any
+
+from coredis.typing import Awaitable, Callable, P, R
+
+logger = logging.getLogger(__name__)
+
+
+class RetryPolicy(ABC):
+    """
+    Abstract retry policy
+    """
+
+    def __init__(self, retries: int, retryable_exceptions: tuple[type[BaseException], ...]) -> None:
+        """
+        :param retries: number of times to retry if a :paramref:`retryable_exception`
+         is encountered.
+        :param retryable_exceptions: The exceptions to trigger a retry for
+        """
+        self.retryable_exceptions = retryable_exceptions
+        self.retries = retries
+
+    @abstractmethod
+    async def delay(self, attempt_number: int) -> None:
+        pass
+
+    async def call_with_retries(
+        self,
+        func: Callable[..., Awaitable[R]],
+        before_hook: Callable[..., Awaitable[Any]] | None = None,
+        failure_hook: Callable[..., Awaitable[Any]]
+        | dict[type[BaseException], Callable[..., Awaitable[None]]]
+        | None = None,
+    ) -> R:
+        """
+        :param func: a function that should return the coroutine that will be
+         awaited when retrying if :paramref:`RetryPolicy.retryable_exceptions` is encountered.
+        :param before_hook: if provided will be called on every attempt.
+        :param failure_hook: if provided and is a callable it will be
+         called everytime a retryable exception is encountered. If it is a mapping
+         of exception types to callables, the first exception type that is a parent
+         of any encountered exception will be called.
+        """
+        last_error: BaseException | None = None
+        for attempt in range(self.retries + 1):
+            try:
+                await self.delay(attempt)
+                if before_hook:
+                    await before_hook()
+                return await func()
+            except self.retryable_exceptions as e:
+                logger.info(f"Retry attempt {attempt + 1} due to error: {e}")
+                if failure_hook:
+                    try:
+                        if isinstance(failure_hook, dict):
+                            for exc_type, hook in failure_hook.items():
+                                if isinstance(e, exc_type):
+                                    await hook(e)
+                                    break
+                        else:
+                            await failure_hook(e)
+                    except:  # noqa
+                        pass
+                last_error = e
+        if last_error:
+            raise last_error
+        assert False
+
+    def will_retry(self, exc: BaseException) -> bool:
+        return isinstance(exc, self.retryable_exceptions)
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}<"
+            f"retries={self.retries}, "
+            f"retryable_exceptions={','.join(e.__name__ for e in self.retryable_exceptions)}"
+            ">"
+        )
+
+
+class NoRetryPolicy(RetryPolicy):
+    def __init__(self) -> None:
+        super().__init__(1, ())
+
+    async def delay(self, attempt_number: int) -> None:
+        pass
+
+
+class ConstantRetryPolicy(RetryPolicy):
+    """
+    Retry policy that pauses :paramref:`ConstantRetryPolicy.delay`
+    seconds between :paramref:`ConstantRetryPolicy.retries`
+    if any of :paramref:`ConstantRetryPolicy.retryable_exceptions` are
+    encountered.
+    """
+
+    def __init__(
+        self,
+        retryable_exceptions: tuple[type[BaseException], ...],
+        retries: int,
+        delay: float,
+    ) -> None:
+        self.__delay = delay
+        super().__init__(retries, retryable_exceptions)
+
+    async def delay(self, attempt_number: int) -> None:
+        if attempt_number > 0:
+            await asyncio.sleep(self.__delay)
+
+
+class ExponentialBackoffRetryPolicy(RetryPolicy):
+    """
+    Retry policy that exponentially backs off before retrying up to
+    :paramref:`ExponentialBackoffRetryPolicy.retries` if any
+    of :paramref:`ExponentialBackoffRetryPolicy.retryable_exceptions` are
+    encountered. :paramref:`ExponentialBckoffRetryPolicy.initial_delay`
+    is used as the initial value for calculating the exponential backoff.
+
+    """
+
+    def __init__(
+        self,
+        retryable_exceptions: tuple[type[BaseException], ...],
+        retries: int,
+        initial_delay: float,
+    ) -> None:
+        self.__initial_delay = initial_delay
+        super().__init__(retries, retryable_exceptions)
+
+    async def delay(self, attempt_number: int) -> None:
+        if attempt_number > 0:
+            await asyncio.sleep(pow(2, attempt_number) * self.__initial_delay)
+
+
+class CompositeRetryPolicy(RetryPolicy):
+    """
+    Convenience class to combine multiple retry policies
+    """
+
+    def __init__(self, *retry_policies: RetryPolicy):
+        self._retry_policies = set(retry_policies)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}<{','.join(str(p) for p in self._retry_policies)}>"
+
+    def add_retry_policy(self, policy: RetryPolicy) -> None:
+        """
+        Add to the retry policies that this instance was created with
+        """
+        self._retry_policies.add(policy)
+
+    async def delay(self, attempt_number: int) -> None:
+        raise NotImplementedError()
+
+    async def call_with_retries(
+        self,
+        func: Callable[..., Awaitable[R]],
+        before_hook: Callable[..., Awaitable[Any]] | None = None,
+        failure_hook: None
+        | (
+            Callable[..., Awaitable[Any]] | dict[type[BaseException], Callable[..., Awaitable[Any]]]
+        ) = None,
+    ) -> R:
+        """
+        Calls :paramref:`func` repeatedly according to the retry policies that
+        this class was instantiated with (:paramref:`CompositeRetryPolicy.retry_policies`).
+
+        :param func: a function that should return the coroutine that will be
+         awaited when retrying if :paramref:`RetryPolicy.retryable_exceptions` is encountered.
+        :param before_hook: if provided will be called before every attempt.
+        :param failure_hook: if provided and is a callable it will be
+         called everytime a retryable exception is encountered. If it is a mapping
+         of exception types to callables, the first exception type that is a parent
+         of any encountered exception will be called.
+        """
+        attempts = {policy: 0 for policy in self._retry_policies}
+        while True:
+            try:
+                if before_hook:
+                    await before_hook()
+                return await func()
+            except Exception as e:
+                will_retry = False
+                attempt = 0
+                for policy in attempts:
+                    if policy.will_retry(e) and attempts[policy] < policy.retries:
+                        attempt = attempts[policy]
+                        attempts[policy] += 1
+                        await policy.delay(attempts[policy])
+                        will_retry = True
+                        break
+
+                if failure_hook:
+                    if isinstance(failure_hook, dict):
+                        for exc_type in failure_hook:
+                            if isinstance(e, exc_type):
+                                await failure_hook[exc_type](e)
+                                break
+                    else:
+                        await failure_hook(e)
+
+                if will_retry:
+                    logger.info(f"Retry attempt {attempt} due to error: {e}")
+                    continue
+
+                raise e
+
+
+def retryable(
+    policy: RetryPolicy,
+    failure_hook: Callable[..., Awaitable[Any]] | None = None,
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
+    """
+    Decorator to be used to apply a retry policy to a coroutine
+    """
+
+    def inner(
+        func: Callable[P, Awaitable[R]],
+    ) -> Callable[P, Awaitable[R]]:
+        @wraps(func)
+        async def _inner(*args: P.args, **kwargs: P.kwargs) -> R:
+            return await policy.call_with_retries(
+                lambda: func(*args, **kwargs), failure_hook=failure_hook
+            )
+
+        return _inner
+
+    return inner