coredis 5.2.0__cp314-cp314-macosx_11_0_arm64.whl

coredis/commands/_utils.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import datetime
+import time
+import warnings
+from typing import TYPE_CHECKING, Any
+
+from coredis.commands.constants import CommandName
+from coredis.config import Config
+from coredis.exceptions import CommandNotSupportedError, CommandSyntaxError
+
+if TYPE_CHECKING:
+    import coredis.client
+    from coredis.commands._wrappers import CommandDetails
+
+
+def normalized_seconds(value: int | datetime.timedelta) -> int:
+    if isinstance(value, datetime.timedelta):
+        value = value.seconds + value.days * 24 * 3600
+
+    return value
+
+
+def normalized_milliseconds(value: int | datetime.timedelta) -> int:
+    if isinstance(value, datetime.timedelta):
+        ms = int(value.microseconds / 1000)
+        value = (value.seconds + value.days * 24 * 3600) * 1000 + ms
+
+    return value
+
+
+def normalized_time_seconds(value: int | datetime.datetime) -> int:
+    if isinstance(value, datetime.datetime):
+        s = int(value.microsecond / 1000000)
+        value = int(time.mktime(value.timetuple())) + s
+
+    return value
+
+
+def normalized_time_milliseconds(value: int | datetime.datetime) -> int:
+    if isinstance(value, datetime.datetime):
+        ms = int(value.microsecond / 1000)
+        value = int(time.mktime(value.timetuple())) * 1000 + ms
+
+    return value
+
+
+def check_version(
+    instance: coredis.client.Client[Any],
+    function_name: str,
+    command_details: CommandDetails,
+    deprecation_reason: str | None = None,
+    kwargs: dict[str, Any] = {},
+) -> None:
+    if Config.optimized or not any(
+        [
+            command_details.version_introduced,
+            command_details.version_deprecated,
+            command_details.arguments,
+        ]
+    ):
+        return
+    if getattr(instance, "verify_version", False) and not getattr(instance, "noreply", False):
+        server_version = getattr(instance, "server_version", None)
+        if not server_version:
+            return
+        if (
+            command_details.version_introduced
+            and server_version < command_details.version_introduced
+        ):
+            raise CommandNotSupportedError(
+                command_details.command.decode("latin-1"),
+                str(instance.server_version),
+            )
+        elif command_details.arguments and set(command_details.arguments.keys()).intersection(
+            kwargs.keys()
+        ):
+            for argument, minimum_version in [
+                (arg, ver) for (arg, ver) in command_details.arguments.items() if arg in kwargs
+            ]:
+                if minimum_version and server_version < minimum_version:
+                    raise CommandSyntaxError(
+                        {argument},
+                        (
+                            f"{command_details.command.decode('latin-1')} with `{argument}` "
+                            f"is not supported in redis version {server_version}"
+                        ),
+                    )
+        elif (
+            command_details.version_deprecated
+            and server_version >= command_details.version_deprecated
+        ):
+            warnings.warn(
+                (
+                    deprecation_reason.strip()
+                    if deprecation_reason
+                    else (
+                        f"{function_name}() is deprecated since redis version "
+                        "{command_details.version_deprecated}."
+                    )
+                ),
+                category=DeprecationWarning,
+                stacklevel=3,
+            )
+
+
+def redis_command_link(command: CommandName) -> str:
+    return f"`{str(command)} <https://redis.io/commands/{str(command).lower().replace(' ', '-')}>`_"

coredis/commands/_validators.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any
+
+from coredis.config import Config
+from coredis.exceptions import CommandSyntaxError
+from coredis.typing import (
+    Callable,
+    Iterable,
+    ParamSpec,
+    TypeVar,
+)
+
+R = TypeVar("R")
+P = ParamSpec("P")
+
+
+class RequiredParameterError(CommandSyntaxError):
+    def __init__(self, arguments: set[str], details: str | None):
+        message = (
+            f"One of [{','.join(arguments)}] must be provided.{' ' + details if details else ''}"
+        )
+        super().__init__(arguments, message)
+
+
+class MutuallyExclusiveParametersError(CommandSyntaxError):
+    def __init__(self, arguments: set[str], details: str | None):
+        message = (
+            f"The [{','.join(arguments)}] parameters are mutually exclusive."
+            f"{' ' + details if details else ''}"
+        )
+        super().__init__(arguments, message)
+
+
+class MutuallyInclusiveParametersMissing(CommandSyntaxError):
+    def __init__(self, arguments: set[str], leaders: set[str], details: str | None):
+        if leaders:
+            message = (
+                f"The [{','.join(arguments)}] parameters(s)"
+                " must be provided together with [{','.join(leaders)}]."
+                f"{' ' + details if details else ''}"
+            )
+        else:
+            message = (
+                f"The [{','.join(arguments)}] parameters are mutually"
+                " inclusive and must be provided together."
+                f"{' ' + details if details else ''}"
+            )
+        super().__init__(arguments, message)
+
+
+def mutually_exclusive_parameters(
+    *exclusive_params: str | Iterable[str],
+    details: str | None = None,
+    required: bool = False,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    primary = {k for k in exclusive_params if isinstance(k, str)}
+    secondary = [k for k in set(exclusive_params) - primary]
+
+    def wrapper(
+        func: Callable[P, R],
+    ) -> Callable[P, R]:
+        sig = inspect.signature(func)
+
+        @functools.wraps(func)
+        def wrapped(*args: P.args, **kwargs: P.kwargs) -> R:
+            if not Config.optimized:
+                call_args = sig.bind_partial(*args, **kwargs)
+                params = {
+                    k
+                    for k in primary
+                    if not call_args.arguments.get(k) == getattr(sig.parameters.get(k), "default")
+                }
+
+                if params:
+                    for group in secondary:
+                        for k in group:
+                            if not call_args.arguments.get(k) == getattr(
+                                sig.parameters.get(k), "default"
+                            ):
+                                params.add(k)
+
+                                break
+
+                if len(params) > 1:
+                    raise MutuallyExclusiveParametersError(params, details)
+                if len(params) == 0 and required:
+                    raise RequiredParameterError(primary, details)
+
+            return func(*args, **kwargs)
+
+        return wrapped if not Config.optimized else func
+
+    return wrapper
+
+
+def mutually_inclusive_parameters(
+    *inclusive_params: str,
+    leaders: Iterable[str] | None = None,
+    details: str | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    _leaders = set(leaders or [])
+    _inclusive_params = set(inclusive_params)
+
+    def wrapper(
+        func: Callable[P, R],
+    ) -> Callable[P, R]:
+        sig = inspect.signature(func)
+
+        @functools.wraps(func)
+        def wrapped(*args: P.args, **kwargs: P.kwargs) -> R:
+            if not Config.optimized:
+                call_args = sig.bind_partial(*args, **kwargs)
+                params = {
+                    k
+                    for k in _inclusive_params | _leaders
+                    if not call_args.arguments.get(k) == getattr(sig.parameters.get(k), "default")
+                }
+                if _leaders and _leaders & params != _leaders and len(params) > 0:
+                    raise MutuallyInclusiveParametersMissing(_inclusive_params, _leaders, details)
+                elif not _leaders and params and len(params) != len(_inclusive_params):
+                    raise MutuallyInclusiveParametersMissing(_inclusive_params, _leaders, details)
+            return func(*args, **kwargs)
+
+        return wrapped if not Config.optimized else func
+
+    return wrapper
+
+
+def ensure_iterable_valid(
+    argument: str,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    def iterable_valid(value: Any) -> bool:
+        return isinstance(value, Iterable) and not isinstance(value, (str, bytes))
+
+    def wrapper(
+        func: Callable[P, R],
+    ) -> Callable[P, R]:
+        sig = inspect.signature(func)
+        expected_type = sig.parameters[argument].annotation
+
+        @functools.wraps(func)
+        def wrapped(*args: P.args, **kwargs: P.kwargs) -> R:
+            if Config.optimized:
+                return func(*args, **kwargs)
+            bound = sig.bind_partial(*args, **kwargs)
+            value = bound.arguments.get(argument)
+            if not iterable_valid(value):
+                raise TypeError(
+                    f"{func.__name__} parameter {argument}={value!r} violates expected iterable of type {expected_type}"
+                )
+
+            return func(*args, **kwargs)
+
+        return wrapped if not Config.optimized else func
+
+    return wrapper

coredis/commands/_wrappers.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import dataclasses
+import functools
+import textwrap
+import warnings
+
+from packaging import version
+
+from coredis.commands._utils import check_version, redis_command_link
+from coredis.commands.constants import CommandFlag, CommandGroup, CommandName, NodeFlag
+from coredis.commands.request import CommandRequest
+from coredis.globals import CACHEABLE_COMMANDS, COMMAND_FLAGS, READONLY_COMMANDS
+from coredis.response._callbacks import ClusterMultiNodeCallback
+from coredis.typing import (
+    Callable,
+    NamedTuple,
+    P,
+    R,
+    add_runtime_checks,
+)
+
+
+class RedirectUsage(NamedTuple):
+    reason: str
+    warn: bool
+
+
+@dataclasses.dataclass
+class CommandDetails:
+    command: bytes
+    group: CommandGroup | None
+    version_introduced: version.Version | None
+    version_deprecated: version.Version | None
+    _arguments: dict[str, dict[str, str]] | None
+    cluster: ClusterCommandConfig
+    flags: set[CommandFlag]
+    redirect_usage: RedirectUsage | None
+    arguments: dict[str, version.Version] = dataclasses.field(
+        init=False, default_factory=lambda: {}
+    )
+
+    def __post_init__(self) -> None:
+        self.arguments = {
+            k: version.Version(v["version_introduced"])
+            for k, v in (self._arguments or {}).items()
+            if v.get("version_introduced")
+        }
+
+
+@dataclasses.dataclass
+class ClusterCommandConfig:
+    enabled: bool = True
+    combine: ClusterMultiNodeCallback | None = None  # type: ignore
+    route: NodeFlag | None = None
+    split: NodeFlag | None = None
+
+    @property
+    def multi_node(self) -> bool:
+        return (self.route or self.split) in [
+            NodeFlag.ALL,
+            NodeFlag.PRIMARIES,
+            NodeFlag.REPLICAS,
+            NodeFlag.SLOT_ID,
+        ]
+
+
+def redis_command(
+    command_name: CommandName,
+    *,
+    group: CommandGroup | None = None,
+    version_introduced: str | None = None,
+    version_deprecated: str | None = None,
+    deprecation_reason: str | None = None,
+    redirect_usage: RedirectUsage | None = None,
+    arguments: dict[str, dict[str, str]] | None = None,
+    flags: set[CommandFlag] | None = None,
+    cluster: ClusterCommandConfig = ClusterCommandConfig(),
+    cacheable: bool | None = None,
+) -> Callable[[Callable[P, CommandRequest[R]]], Callable[P, CommandRequest[R]]]:
+    readonly = False
+    if flags and CommandFlag.READONLY in flags:
+        READONLY_COMMANDS.add(command_name)
+        readonly = True
+
+    if not readonly and cacheable:  # noqa
+        raise RuntimeError(f"Can't decorate non readonly command {command_name} with cache config")
+    if cacheable:
+        CACHEABLE_COMMANDS.add(command_name)
+
+    COMMAND_FLAGS[command_name] = flags or set()
+
+    command_details = CommandDetails(
+        command_name,
+        group,
+        version.Version(version_introduced) if version_introduced else None,
+        version.Version(version_deprecated) if version_deprecated else None,
+        arguments,
+        cluster or ClusterCommandConfig(),
+        flags or set(),
+        redirect_usage,
+    )
+
+    def wrapper(
+        func: Callable[P, CommandRequest[R]],
+    ) -> Callable[P, CommandRequest[R]]:
+        runtime_checkable = add_runtime_checks(func)
+
+        @functools.wraps(func)
+        def wrapped(*args: P.args, **kwargs: P.kwargs) -> CommandRequest[R]:
+            from coredis import Redis, RedisCluster
+
+            is_regular_client = isinstance(args[0], (Redis, RedisCluster))
+            if redirect_usage and is_regular_client:
+                if redirect_usage.warn:
+                    warnings.warn(redirect_usage.reason, UserWarning, stacklevel=2)
+                else:
+                    raise NotImplementedError(redirect_usage.reason)
+            runtime_checking = not getattr(args[0], "noreply", None) and is_regular_client
+            check_version(
+                args[0],  # type: ignore
+                func.__name__,
+                command_details,
+                deprecation_reason,
+                kwargs,
+            )
+            return (func if not runtime_checking else runtime_checkable)(*args, **kwargs)
+
+        wrapped.__doc__ = textwrap.dedent(wrapped.__doc__ or "")
+        if group:
+            wrapped.__doc__ = f"""
+{wrapped.__doc__}
+
+Redis command documentation: {redis_command_link(command_name)}
+"""
+        if version_introduced or command_details.arguments:
+            wrapped.__doc__ += """
+Compatibility:
+"""
+
+        if version_introduced:
+            wrapped.__doc__ += f"""
+- New in :redis-version:`{version_introduced}`
+"""
+        if version_deprecated and deprecation_reason:
+            wrapped.__doc__ += f"""
+- Deprecated in :redis-version:`{version_deprecated}`
+      {deprecation_reason.strip()}
+"""
+        elif version_deprecated:
+            wrapped.__doc__ += f"""
+- Deprecated in :redis-version:`{version_deprecated}`
+"""
+        if command_details.arguments:
+            for argument, min_version in command_details.arguments.items():
+                wrapped.__doc__ += f"""
+- :paramref:`{argument}`: New in :redis-version:`{min_version}`
+"""
+        if cacheable:
+            wrapped.__doc__ += """
+.. hint:: Supports client side caching
+"""
+        if redirect_usage:
+            if redirect_usage.warn:
+                preamble = f".. warning:: Using ``{func.__name__}`` directly is not recommended."
+            else:
+                preamble = f".. danger:: Using ``{func.__name__}`` directly is not supported."
+            wrapped.__doc__ += f"""
+{preamble} {redirect_usage.reason}
+"""
+
+        setattr(wrapped, "__coredis_command", command_details)
+        return wrapped
+
+    return wrapper

coredis/commands/bitfield.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import enum
+
+from coredis._protocols import AbstractExecutor
+from coredis.commands.constants import CommandName
+from coredis.commands.request import CommandRequest
+from coredis.exceptions import ReadOnlyError
+from coredis.response._callbacks import NoopCallback
+from coredis.tokens import PrefixToken, PureToken
+from coredis.typing import (
+    AnyStr,
+    CommandArgList,
+    Generic,
+    KeyT,
+    Literal,
+    ResponseType,
+)
+
+
+class BitFieldSubCommand(bytes, enum.Enum):
+    SET = PrefixToken.SET
+    GET = PrefixToken.GET
+    INCRBY = PrefixToken.INCRBY
+    OVERFLOW = PrefixToken.OVERFLOW
+
+
+class BitFieldOperation(Generic[AnyStr]):
+    """
+    The command treats a Redis string as a array of bits,
+    and is capable of addressing specific integer fields
+    of varying bit widths and arbitrary non (necessary) aligned offset.
+
+    The supported types are up to 64 bits for signed integers,
+    and up to 63 bits for unsigned integers.
+
+    Offset can be num prefixed with `#` character or num directly.
+
+    Redis command documentation: `BITFIELD <https://redios.io/commands/bitfield>`__
+    """
+
+    def __init__(self, redis_client: AbstractExecutor, key: KeyT, readonly: bool = False) -> None:
+        self._command = CommandName.BITFIELD if not readonly else CommandName.BITFIELD_RO
+        self._command_stack: CommandArgList = [key]
+        self.redis = redis_client
+        self.readonly = readonly
+
+    def __del__(self) -> None:
+        self._command_stack.clear()
+
+    def set(self, encoding: str, offset: int | str, value: int) -> BitFieldOperation[AnyStr]:
+        """
+        Set the specified bit field and returns its old value.
+        """
+
+        if self.readonly:
+            raise ReadOnlyError()
+
+        self._command_stack.extend([BitFieldSubCommand.SET, encoding, offset, value])
+
+        return self
+
+    def get(self, encoding: str, offset: int | str) -> BitFieldOperation[AnyStr]:
+        """
+        Returns the specified bit field.
+        """
+
+        self._command_stack.extend([BitFieldSubCommand.GET, encoding, offset])
+
+        return self
+
+    def incrby(self, encoding: str, offset: int | str, increment: int) -> BitFieldOperation[AnyStr]:
+        """
+        Increments or decrements (if a negative increment is given)
+        the specified bit field and returns the new value.
+        """
+
+        if self.readonly:
+            raise ReadOnlyError()
+
+        self._command_stack.extend([BitFieldSubCommand.INCRBY, encoding, offset, increment])
+
+        return self
+
+    def overflow(
+        self,
+        behavior: Literal[PureToken.SAT, PureToken.WRAP, PureToken.FAIL] = PureToken.SAT,
+    ) -> BitFieldOperation[AnyStr]:
+        """
+        fine-tune the behavior of the increment or decrement overflow,
+        have no effect unless used before :meth:`incrby`
+        three :paramref:`behavior` types are available: ``WRAP|SAT|FAIL``
+        """
+
+        if self.readonly:
+            raise ReadOnlyError()
+        self._command_stack.extend([BitFieldSubCommand.OVERFLOW, behavior])
+
+        return self
+
+    def exc(self) -> CommandRequest[ResponseType]:
+        """execute commands in command stack"""
+
+        return CommandRequest(
+            self.redis,
+            self._command,
+            *self._command_stack,
+            callback=NoopCallback(),
+            execution_parameters={"decode": False},
+        )