coredis 5.5.0__cp313-cp313-macosx_11_0_arm64.whl

coredis/commands/request.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import functools
+from typing import Any, cast
+
+from coredis._protocols import AbstractExecutor
+from coredis.typing import (
+    Awaitable,
+    Callable,
+    ExecutionParameters,
+    Generator,
+    Serializable,
+    TypeAdapter,
+    TypeVar,
+    ValueT,
+)
+
+#: Covariant type used for generalizing :class:`~coredis.command.CommandRequest`
+CommandResponseT = TypeVar("CommandResponseT", covariant=True)
+
+TransformedResponse = TypeVar("TransformedResponse")
+empty_adapter = TypeAdapter()
+
+
+class CommandRequest(Awaitable[CommandResponseT]):
+    response: Awaitable[CommandResponseT]
+
+    def __init__(
+        self,
+        client: AbstractExecutor,
+        name: bytes,
+        *arguments: ValueT,
+        callback: Callable[..., CommandResponseT],
+        execution_parameters: ExecutionParameters | None = None,
+    ) -> None:
+        """
+        The default command request object which is returned by all
+        methods mirroring redis commands.
+
+        :param client: The instance of the :class:`coredis.Redis` that
+         will be used to call :meth:`~coredis.Redis.execute_command`
+        :param name:  The name of the command
+        :param arguments:  All arguments (in redis format) to be passed to the command
+        :param callback: The callback to be used to transform the RESP response
+        :param execution_parameters:  Any additional parameters to be passed to
+         :meth:`coredis.Redis.execute_command`
+        """
+        self.name = name
+        self.callback = callback
+        self.execution_parameters = execution_parameters or {}
+        self.client: AbstractExecutor = client
+        self.arguments = tuple(
+            self.type_adapter.serialize(k) if isinstance(k, Serializable) else k for k in arguments
+        )
+
+    def run(self) -> Awaitable[CommandResponseT]:
+        if not hasattr(self, "response"):
+            self.response = self.client.execute_command(
+                self, self.callback, **self.execution_parameters
+            )
+
+        return self.response
+
+    def transform(
+        self, transformer: type[TransformedResponse]
+    ) -> CommandRequest[TransformedResponse]:
+        """
+        :param transformer: A type that was registered with the client
+         using :meth:`~coredis.typing.TypeAdapter.register_deserializer`
+         or decorated by :meth:`~coredis.typing.TypeAdapter.deserializer`
+
+        :return: a command request object that when awaited will return the
+         transformed response
+
+         For example when used with a redis command::
+
+           client = coredis.Redis(....)
+           @client.type_adapter.deserializer
+           def _(value: bytes) -> int:
+               return int(value)
+
+           await client.set("fubar", 1)
+           raw: bytes = await client.get("fubar")
+           int_value: int = await client.get("fubar").transform(int)
+        """
+        transform_func = functools.partial(
+            self.type_adapter.deserialize,
+            return_type=transformer,
+        )
+        return cast(type[CommandRequest[TransformedResponse]], self.__class__)(
+            self.client,
+            self.name,
+            *self.arguments,
+            callback=lambda resp, **kwargs: transform_func(self.callback(resp, **kwargs)),
+            execution_parameters=self.execution_parameters,
+        )
+
+    @property
+    def type_adapter(self) -> TypeAdapter:
+        from coredis.client import Client
+
+        if isinstance(self.client, Client):
+            return self.client.type_adapter
+
+        return empty_adapter
+
+    def __await__(self) -> Generator[Any, Any, CommandResponseT]:
+        return self.run().__await__()

coredis/commands/script.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import functools
+import hashlib
+import inspect
+import itertools
+from typing import TYPE_CHECKING, Any, cast
+
+from deprecated.sphinx import versionadded
+
+from coredis._utils import b
+from coredis.exceptions import NoScriptError
+from coredis.retry import ConstantRetryPolicy, retryable
+from coredis.typing import (
+    AnyStr,
+    Awaitable,
+    Callable,
+    Generic,
+    KeyT,
+    P,
+    Parameters,
+    R,
+    RedisValueT,
+    ResponseType,
+    StringT,
+    ValueT,
+    add_runtime_checks,
+    safe_beartype,
+)
+
+if TYPE_CHECKING:
+    import coredis.client
+
+
+class Script(Generic[AnyStr]):
+    """
+    An executable Lua script object returned by :meth:`coredis.Redis.register_script`.
+    Instances of the class are callable and take arguments in the same shape
+    as :meth:`coredis.Redis.evalsha` or :meth:`coredis.Redis.eval`
+    (i.e a list of :paramref:`~__call__.keys` and :paramref:`~__call__.args`).
+
+    Example::
+
+        client = coredis.Redis()
+        await client.set("test", "co")
+        concat = client.register_script("return redis.call('GET', KEYS[1]) + ARGV[1]")
+        assert await concat(['test'], ['redis']) == "coredis"
+    """
+
+    #: SHA of this script once it's registered with the redis server
+    sha: AnyStr
+
+    def __init__(
+        self,
+        registered_client: coredis.client.Client[AnyStr] | None = None,
+        script: StringT | None = None,
+        readonly: bool = False,
+    ):
+        """
+        :param client: The client to use for executing the lua script. If
+         this is ``None`` the client will have to be provided when invoking
+         the script using :meth:`__call__` with the :paramref:`__call__.client`
+         parameter.
+        :param script: The lua script that will be used by :meth:`__call__`
+        :param readonly: If ``True`` the script will be called with
+         :meth:`coredis.Redis.evalsha_ro` instead of :meth:`coredis.Redis.evalsha`
+        """
+        self.registered_client: coredis.client.Client[AnyStr] | None = registered_client
+        self.script: StringT
+        if not script:
+            raise RuntimeError("No script provided")
+        self.script = script
+        self.sha = hashlib.sha1(b(script)).hexdigest()  # type: ignore
+        self.readonly = readonly
+
+    def __call__(
+        self,
+        keys: Parameters[KeyT] | None = None,
+        args: Parameters[ValueT] | None = None,
+        client: coredis.client.Client[AnyStr] | None = None,
+        readonly: bool | None = None,
+    ) -> Awaitable[ResponseType]:
+        """
+        Executes the script registered in :paramref:`Script.script` using
+        :meth:`coredis.Redis.evalsha`. Additionally, if the script was not yet
+        registered on the instance, it will automatically do that as well
+        and cache the sha at :data:`Script.sha`
+
+        :param keys: The keys this script will reference
+        :param args: The arguments expected by the script
+        :param client: The redis client to use instead of :paramref:`Script.client`
+        :param readonly: If ``True`` forces the script to be called with
+         :meth:`coredis.Redis.evalsha_ro`
+        """
+        from coredis.pipeline import Pipeline
+
+        if client is None:
+            client = self.registered_client
+        if not client:
+            raise RuntimeError(
+                "This instance is not bound to a redis client."
+                "Please provide a valid instance to execute the script with"
+            )
+        if readonly is None:
+            readonly = self.readonly
+
+        method = client.evalsha_ro if readonly else client.evalsha
+
+        # make sure the Redis server knows about the script
+        if isinstance(client, Pipeline):
+            # make sure this script is good to go on pipeline
+            cast(Pipeline[AnyStr], client).scripts.add(self)
+            return method(self.sha, keys=keys, args=args)
+        else:
+            return retryable(
+                ConstantRetryPolicy((NoScriptError,), 1, 0),
+                failure_hook=lambda _: client.script_load(self.script),
+            )(method)(self.sha, keys=keys, args=args)
+
+    async def execute(
+        self,
+        keys: Parameters[KeyT] | None = None,
+        args: Parameters[ValueT] | None = None,
+        client: coredis.client.Client[AnyStr] | None = None,
+        readonly: bool | None = None,
+    ) -> ResponseType:
+        """
+        Executes the script registered in :paramref:`Script.script`
+
+        :meta private:
+        """
+        return await self(keys, args, client, readonly)
+
+    @versionadded(version="3.5.0")
+    def wraps(
+        self,
+        key_spec: list[str] | None = None,
+        param_is_key: Callable[[inspect.Parameter], bool] = lambda p: (
+            p.annotation in {"KeyT", KeyT}
+        ),
+        client_arg: str | None = None,
+        runtime_checks: bool = False,
+        readonly: bool | None = None,
+    ) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
+        """
+        Decorator for wrapping a regular python function, method or classmethod
+        signature with a :class:`~coredis.commands.script.Script`. This allows
+        exposing a strict signature instead of that which :meth:`__call__` provides.
+        The callable being decorated should **not** have an implementation as
+        it will never be called.
+
+        The main objective of the decorator is to allow you to have strict (and type safe)
+        signatures for wrappers for lua scripts. Internally the decorator separates
+        ``keys`` from ``args`` before calling :meth:`coredis.Redis.evalsha`. Mapping the
+        decorated methods arguments to key providers is done either by using :paramref:`key_spec`
+        or :paramref:`param_is_key`. All other paramters of the decorated function are assumed
+        to be ``args`` consumed by the lua script.
+
+        By default the decorated method is bound to the :class:`coredis.client.Redis`
+        or :class:`coredis.client.RedisCluster` instance that the :class:`Script` instance
+        was instantiated with. This may however not be the instance you want to eventually
+        execute the method with. For such scenarios the decorated method can accept an additional
+        parameter which has the name declared by :paramref:`client_arg`).
+
+        The following example executes the script with the ``client`` instance used
+        to register the script. The ``key`` parameter is detected as a key provider
+        as it is annotated with the :data:`coredis.typing.KeyT` type, and ``value`` is
+        passed to redis as an ``arg``::
+
+            import coredis
+            from coredis.typing import KeyT, RedisValueT
+            from typing import List
+
+            client = coredis.Redis()
+            @client.register_script("return {KEYS[1], ARGV[1]}").wraps()
+            async def echo_key_value(key: KeyT, value: RedisValueT) -> List[RedisValueT]: ...
+
+            k, v = await echo_key_value("co", "redis")
+            # (b"co", b"redis")
+
+        Alternatively, the following example builds a class method that requires
+        the ``client`` to be passed in explicitly::
+
+            from coredis import Redis
+            from coredis.commands import Script
+
+            class ScriptProvider:
+                @classmethod
+                @Script(script="return KEYS[1]").wraps(
+                    key_spec=["key"],
+                    client_arg="client"
+                )
+                def echo_key(cls, client, key): ...
+
+                @classmethod
+                @Script(script="return ARGS[1]").wraps(
+                    client_arg="client"
+                )
+                def echo_arg(cls, client, value): ...
+
+            echoed = await ScriptProvider.echo_key(Redis(), "coredis")
+            # b"coredis"
+            echoed = await ScriptProvider.echo_value(Redis(), "coredis")
+            # b"coredis"
+
+        :param key_spec: list of parameters of the decorated method that will
+         be passed as the :paramref:`keys` argument to :meth:`__call__`. If provided
+         this parameter takes precedence over using :paramref:`param_is_key` to determine if
+         a parameter is a key provider.
+        :param param_is_key: a callable that accepts a single argument of type
+         :class:`inspect.Parameter` and returns ``True`` if the parameter points
+         to a key that should be appended to the :paramref:`__call__.keys` argument
+         of :meth:`__call__`. The default implementation marks a parameter as a key
+         provider if it is of type :data:`coredis.typing.KeyT` and is only used if
+         :paramref:`key_spec` is ``None``.
+        :param client_arg: The parameter of the decorator that will contain a client instance
+         to be used to execute the script.
+        :param runtime_checks: Whether to enable runtime type checking of input arguments
+         and return values. (requires :pypi:`beartype`). If :data:`False` the function will
+         still get runtime type checking if the environment configuration ``COREDIS_RUNTIME_CHECKS``
+         is set - for details see :ref:`handbook/typing:runtime type checking`.
+        :param readonly: If ``True`` forces this script to be called with
+         :meth:`coredis.Redis.evalsha_ro`
+
+        :return: A function that has a signature mirroring the decorated function.
+        """
+
+        def wrapper(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+            sig = inspect.signature(func)
+            first_arg = list(sig.parameters.keys())[0]
+            runtime_check_wrapper = add_runtime_checks if not runtime_checks else safe_beartype
+            script_instance = self
+            key_params = (
+                key_spec if key_spec else [n for n, p in sig.parameters.items() if param_is_key(p)]
+            )
+            arg_fetch: dict[str, Callable[..., Parameters[Any]]] = {
+                n: (
+                    (lambda v: [v])
+                    if p.kind
+                    in {
+                        inspect.Parameter.POSITIONAL_ONLY,
+                        inspect.Parameter.KEYWORD_ONLY,
+                        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    }
+                    else (
+                        (lambda v: list(itertools.chain.from_iterable(v.items())))
+                        if p.kind == inspect.Parameter.VAR_KEYWORD
+                        else lambda v: list(v)
+                    )
+                )
+                for n, p in sig.parameters.items()
+            }
+            if first_arg in {"self", "cls"}:
+                arg_fetch.pop(first_arg)
+            if client_arg:
+                arg_fetch.pop(client_arg)
+
+            def split_args(
+                bound_arguments: inspect.BoundArguments,
+            ) -> tuple[
+                Parameters[KeyT],
+                Parameters[RedisValueT],
+                coredis.client.Client[AnyStr] | None,
+            ]:
+                bound_arguments.apply_defaults()
+                arguments = bound_arguments.arguments
+                keys: list[KeyT] = []
+                args: list[RedisValueT] = []
+                for name in sig.parameters:
+                    if name not in arg_fetch:
+                        continue
+                    value = arg_fetch[name](arguments[name])
+                    if name in key_params:
+                        keys.extend(value)
+                    else:
+                        args.extend(value)
+                return (
+                    keys,
+                    args,
+                    arguments.get(client_arg) if client_arg else None,
+                )
+
+            @runtime_check_wrapper
+            @functools.wraps(func)
+            async def __inner(
+                *args: P.args,
+                **kwargs: P.kwargs,
+            ) -> R:
+                keys, arguments, client = split_args(sig.bind(*args, **kwargs))
+                # TODO: atleast lie with a cast.
+                #  mypy doesn't like the cast
+                return await script_instance(keys, arguments, client, readonly)  # type: ignore
+
+            return __inner
+
+        return wrapper

coredis/commands/sentinel.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+from coredis.response._callbacks import (
+    AnyStrCallback,
+    DictCallback,
+    IntCallback,
+    SimpleStringCallback,
+)
+from coredis.response._callbacks.sentinel import (
+    GetPrimaryCallback,
+    PrimariesCallback,
+    PrimaryCallback,
+    SentinelInfoCallback,
+    SentinelsStateCallback,
+)
+from coredis.typing import (
+    AnyStr,
+    RedisValueT,
+    ResponsePrimitive,
+    StringT,
+)
+
+from . import CommandMixin
+from ._wrappers import redis_command
+from .constants import CommandName
+from .request import CommandRequest
+
+
+class SentinelCommands(CommandMixin[AnyStr]):
+    @redis_command(
+        CommandName.SENTINEL_CKQUORUM,
+    )
+    def sentinel_ckquorum(self, service_name: StringT) -> CommandRequest[bool]:
+        return CommandRequest(
+            self,
+            CommandName.SENTINEL_CKQUORUM,
+            service_name,
+            callback=SimpleStringCallback(prefix_match=True),
+        )
+
+    @redis_command(CommandName.SENTINEL_CONFIG_GET, version_introduced="6.2.0")
+    def sentinel_config_get(self, name: RedisValueT) -> CommandRequest[dict[AnyStr, AnyStr]]:
+        """
+        Get the current value of a global Sentinel configuration parameter.
+        The specified name may be a wildcard, similar to :meth:`config_get`
+        """
+        return CommandRequest(
+            self,
+            CommandName.SENTINEL_CONFIG_GET,
+            name,
+            callback=DictCallback[AnyStr, AnyStr](),
+        )
+
+    @redis_command(CommandName.SENTINEL_CONFIG_SET, version_introduced="6.2")
+    def sentinel_config_set(self, name: RedisValueT, value: RedisValueT) -> CommandRequest[bool]:
+        """
+        Set the value of a global Sentinel configuration parameter
+        """
+        return CommandRequest(
+            self,
+            CommandName.SENTINEL_CONFIG_SET,
+            name,
+            value,
+            callback=SimpleStringCallback(),
+        )
+
+    @redis_command(
+        CommandName.SENTINEL_GET_MASTER_ADDR_BY_NAME,
+    )
+    def sentinel_get_master_addr_by_name(
+        self, service_name: StringT
+    ) -> CommandRequest[tuple[str, int] | None]:
+        """
+        Returns a (host, port) pair for the given :paramref:`service_name`
+        """
+
+        return CommandRequest(
+            self,
+            CommandName.SENTINEL_GET_MASTER_ADDR_BY_NAME,
+            service_name,
+            callback=GetPrimaryCallback(),
+        )
+
+    @redis_command(
+        CommandName.SENTINEL_FAILOVER,
+    )
+    def sentinel_failover(self, service_name: StringT) -> CommandRequest[bool]:
+        """
+        Force a failover as if the master was not reachable, and without asking
+        for agreement to other Sentinels
+        """
+        return CommandRequest(
+            self, CommandName.SENTINEL_FAILOVER, service_name, callback=SimpleStringCallback()
+        )
+
+    @redis_command(CommandName.SENTINEL_FLUSHCONFIG)
+    def sentinel_flushconfig(self) -> CommandRequest[bool]:
+        """
+        Force Sentinel to rewrite its configuration on disk, including the current Sentinel state.
+        """
+        return CommandRequest(
+            self, CommandName.SENTINEL_FLUSHCONFIG, callback=SimpleStringCallback()
+        )
+
+    @redis_command(CommandName.SENTINEL_INFO_CACHE)
+    def sentinel_infocache(
+        self, *nodenames: StringT
+    ) -> CommandRequest[dict[AnyStr, dict[int, dict[str, ResponsePrimitive]]]]:
+        """
+        Return cached INFO output from masters and replicas.
+        """
+        return CommandRequest(
+            self,
+            CommandName.SENTINEL_INFO_CACHE,
+            *nodenames,
+            callback=SentinelInfoCallback[AnyStr](),
+        )
+
+    @redis_command(
+        CommandName.SENTINEL_MASTER,
+    )
+    def sentinel_master(
+        self, service_name: StringT
+    ) -> CommandRequest[dict[str, ResponsePrimitive]]:
+        """Returns a dictionary containing the specified masters state."""
+
+        return CommandRequest(
+            self, CommandName.SENTINEL_MASTER, service_name, callback=PrimaryCallback()
+        )
+
+    @redis_command(
+        CommandName.SENTINEL_MASTERS,
+    )
+    def sentinel_masters(self) -> CommandRequest[dict[str, dict[str, ResponsePrimitive]]]:
+        """Returns a list of dictionaries containing each master's state."""
+
+        return CommandRequest(self, CommandName.SENTINEL_MASTERS, callback=PrimariesCallback())
+
+    @redis_command(
+        CommandName.SENTINEL_MONITOR,
+    )
+    def sentinel_monitor(
+        self, name: RedisValueT, ip: RedisValueT, port: int, quorum: int
+    ) -> CommandRequest[bool]:
+        """Adds a new master to Sentinel to be monitored"""
+
+        return CommandRequest(
+            self,
+            CommandName.SENTINEL_MONITOR,
+            name,
+            ip,
+            port,
+            quorum,
+            callback=SimpleStringCallback(),
+        )
+
+    @redis_command(CommandName.SENTINEL_MYID, version_introduced="6.2.0")
+    def sentinel_myid(self) -> CommandRequest[AnyStr]:
+        """Return the ID of the Sentinel instance"""
+
+        return CommandRequest(self, CommandName.SENTINEL_MYID, callback=AnyStrCallback[AnyStr]())
+
+    @redis_command(
+        CommandName.SENTINEL_REMOVE,
+    )
+    def sentinel_remove(self, name: RedisValueT) -> CommandRequest[bool]:
+        """Removes a master from Sentinel's monitoring"""
+
+        return CommandRequest(
+            self, CommandName.SENTINEL_REMOVE, name, callback=SimpleStringCallback()
+        )
+
+    @redis_command(
+        CommandName.SENTINEL_SENTINELS,
+    )
+    def sentinel_sentinels(
+        self, service_name: StringT
+    ) -> CommandRequest[tuple[dict[str, ResponsePrimitive], ...]]:
+        """Returns a list of sentinels for :paramref:`service_name`"""
+
+        return CommandRequest(
+            self,
+            CommandName.SENTINEL_SENTINELS,
+            service_name,
+            callback=SentinelsStateCallback(),
+        )
+
+    @redis_command(
+        CommandName.SENTINEL_SET,
+    )
+    def sentinel_set(
+        self, name: RedisValueT, option: RedisValueT, value: RedisValueT
+    ) -> CommandRequest[bool]:
+        """Sets Sentinel monitoring parameters for a given master"""
+
+        return CommandRequest(
+            self,
+            CommandName.SENTINEL_SET,
+            name,
+            option,
+            value,
+            callback=SimpleStringCallback(),
+        )
+
+    @redis_command(
+        CommandName.SENTINEL_SLAVES,
+    )
+    def sentinel_slaves(
+        self, service_name: StringT
+    ) -> CommandRequest[tuple[dict[str, ResponsePrimitive], ...]]:
+        """Returns a list of slaves for paramref:`service_name`"""
+
+        return CommandRequest(
+            self, CommandName.SENTINEL_SLAVES, service_name, callback=SentinelsStateCallback()
+        )
+
+    @redis_command(
+        CommandName.SENTINEL_REPLICAS,
+    )
+    def sentinel_replicas(
+        self, service_name: StringT
+    ) -> CommandRequest[tuple[dict[str, ResponsePrimitive], ...]]:
+        """Returns a list of replicas for :paramref:`service_name`"""
+
+        return CommandRequest(
+            self,
+            CommandName.SENTINEL_REPLICAS,
+            service_name,
+            callback=SentinelsStateCallback(),
+        )
+
+    @redis_command(CommandName.SENTINEL_RESET)
+    def sentinel_reset(self, pattern: StringT) -> CommandRequest[int]:
+        """
+        Reset all the masters with matching name.
+        The pattern argument is a glob-style pattern.
+        The reset process clears any previous state in a master (including a
+        failover in progress), and removes every replica and sentinel already
+        discovered and associated with the master.
+        """
+        return CommandRequest(
+            self,
+            CommandName.SENTINEL_RESET,
+            pattern,
+            callback=IntCallback(),
+        )

coredis/config.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import os
+
+
+class __Config:
+    def __init__(self) -> None:
+        self.__optimized: bool = False
+
+    @property
+    def runtime_checks(self) -> bool:
+        """
+        Whether runtime type checks are to be enabled.
+        Can be enabled by setting the environment variable ``COREDIS_RUNTIME_CHECKS`` to ``true``
+        """
+        return os.environ.get("COREDIS_RUNTIME_CHECKS", "").lower() in [
+            "1",
+            "true",
+            "t",
+        ]
+
+    @property
+    def optimized(self) -> bool:
+        """
+        When ``optimized`` is ``True`` most runtime validations will be disabled.
+        This can be enabled in any of the following ways:
+
+          - By running python in optimized mode using the ``-O`` flag
+          - By setting the environment variable ``COREDIS_OPTIMIZED`` to ``true``
+          - By explicitly setting ``coredis.Config.optimized = True``
+
+        """
+        return (
+            not __debug__
+            or os.environ.get("COREDIS_OPTIMIZED", "").lower()
+            in [
+                "1",
+                "true",
+                "t",
+            ]
+            or self.__optimized
+        )
+
+    @optimized.setter
+    def optimized(self, value: bool) -> None:
+        self.__optimized = value
+
+
+#: Used to configure global behaviors of the coredis library
+Config = __Config()