Adding support for CAS/CAD commands. (#3837)

* Add DIGEST command support with tests

* Add DELEX command support with tests

* Adding changes related to SET command

* Add experimental annotations for the CAS/CAD methods and new args

Author: petyaslavova

redis/commands/cluster.py

@@ -61,6 +61,7 @@
         "GEOPOS",
         "GEORADIUS",
         "GEORADIUSBYMEMBER",
+        "DIGEST",
         "GET",
         "GETBIT",
         "GETRANGE",

redis/commands/core.py

@@ -47,10 +47,12 @@
 )
 from redis.utils import (
     deprecated_function,
+    experimental_args,
+    experimental_method,
     extract_expire_flags,
 )
 
-from .helpers import list_or_args
+from .helpers import at_most_one_value_set, list_or_args
 
 if TYPE_CHECKING:
     import redis.asyncio.client
@@ -1729,6 +1731,57 @@ def delete(self, *names: KeyT) -> ResponseT:
     def __delitem__(self, name: KeyT):
         self.delete(name)
 
+    @experimental_method()
+    def delex(
+        self,
+        name: KeyT,
+        ifeq: Optional[Union[bytes, str]] = None,
+        ifne: Optional[Union[bytes, str]] = None,
+        ifdeq: Optional[str] = None,  # hex digest
+        ifdne: Optional[str] = None,  # hex digest
+    ) -> int:
+        """
+        Conditionally removes the specified key.
+
+        Warning:
+        **Experimental** since 7.1.
+        This API may change or be removed without notice.
+        The API may change based on feedback.
+
+        Arguments:
+            name: KeyT - the key to delete
+            ifeq match-valu: Optional[Union[bytes, str]] - Delete the key only if its value is equal to match-value
+            ifne match-value: Optional[Union[bytes, str]] - Delete the key only if its value is not equal to match-value
+            ifdeq match-digest: Optional[str] - Delete the key only if the digest of its value is equal to match-digest
+            ifdne match-digest: Optional[str] - Delete the key only if the digest of its value is not equal to match-digest
+
+        Returns:
+            int: 1 if the key was deleted, 0 otherwise.
+        Raises:
+            redis.exceptions.ResponseError: if key exists but is not a string
+                                            and a condition is specified.
+            ValueError: if more than one condition is provided.
+
+
+        Requires Redis 8.4 or greater.
+        For more information, see https://redis.io/commands/delex
+        """
+        conds = [x is not None for x in (ifeq, ifne, ifdeq, ifdne)]
+        if sum(conds) > 1:
+            raise ValueError("Only one of IFEQ/IFNE/IFDEQ/IFDNE may be specified")
+
+        pieces = ["DELEX", name]
+        if ifeq is not None:
+            pieces += ["IFEQ", ifeq]
+        elif ifne is not None:
+            pieces += ["IFNE", ifne]
+        elif ifdeq is not None:
+            pieces += ["IFDEQ", ifdeq]
+        elif ifdne is not None:
+            pieces += ["IFDNE", ifdne]
+
+        return self.execute_command(*pieces)
+
     def dump(self, name: KeyT) -> ResponseT:
         """
         Return a serialized version of the value stored at the specified key.
@@ -1835,6 +1888,32 @@ def expiretime(self, key: str) -> int:
         """
         return self.execute_command("EXPIRETIME", key)
 
+    @experimental_method()
+    def digest(self, name: KeyT) -> Optional[str]:
+        """
+        Return the digest of the value stored at the specified key.
+
+        Warning:
+        **Experimental** since 7.1.
+        This API may change or be removed without notice.
+        The API may change based on feedback.
+
+        Arguments:
+          - name: KeyT - the key to get the digest of
+
+        Returns:
+          - None if the key does not exist
+          - (bulk string) the XXH3 digest of the value as a hex string
+        Raises:
+          - ResponseError if key exists but is not a string
+
+
+        Requires Redis 8.4 or greater.
+        For more information, see https://redis.io/commands/digest
+        """
+        # Bulk string response is already handled (bytes/str based on decode_responses)
+        return self.execute_command("DIGEST", name)
+
     def get(self, name: KeyT) -> ResponseT:
         """
         Return the value at key ``name``, or None if the key doesn't exist
@@ -1883,8 +1962,7 @@ def getex(
 
         For more information, see https://redis.io/commands/getex
         """
-        opset = {ex, px, exat, pxat}
-        if len(opset) > 2 or len(opset) > 1 and persist:
+        if not at_most_one_value_set((ex, px, exat, pxat, persist)):
             raise DataError(
                 "``ex``, ``px``, ``exat``, ``pxat``, "
                 "and ``persist`` are mutually exclusive."
@@ -2072,8 +2150,7 @@ def msetex(
         Available since Redis 8.4
         For more information, see https://redis.io/commands/msetex
         """
-        opset = {ex, px, exat, pxat}
-        if len(opset) > 2 or len(opset) > 1 and keepttl:
+        if not at_most_one_value_set((ex, px, exat, pxat, keepttl)):
             raise DataError(
                 "``ex``, ``px``, ``exat``, ``pxat``, "
                 "and ``keepttl`` are mutually exclusive."
@@ -2327,6 +2404,7 @@ def restore(
 
         return self.execute_command("RESTORE", *params)
 
+    @experimental_args(["ifeq", "ifne", "ifdeq", "ifdne"])
     def set(
         self,
         name: KeyT,
@@ -2339,10 +2417,20 @@ def set(
         get: bool = False,
         exat: Optional[AbsExpiryT] = None,
         pxat: Optional[AbsExpiryT] = None,
+        ifeq: Optional[Union[bytes, str]] = None,
+        ifne: Optional[Union[bytes, str]] = None,
+        ifdeq: Optional[str] = None,  # hex digest of current value
+        ifdne: Optional[str] = None,  # hex digest of current value
     ) -> ResponseT:
         """
         Set the value at key ``name`` to ``value``
 
+        Warning:
+        **Experimental** since 7.1.
+        The usage of the arguments ``ifeq``, ``ifne``, ``ifdeq``, and ``ifdne``
+        is experimental. The API or returned results when those parameters are used
+        may change based on feedback.
+
         ``ex`` sets an expire flag on key ``name`` for ``ex`` seconds.
 
         ``px`` sets an expire flag on key ``name`` for ``px`` milliseconds.
@@ -2366,35 +2454,67 @@ def set(
         ``pxat`` sets an expire flag on key ``name`` for ``ex`` milliseconds,
             specified in unix time.
 
+        ``ifeq`` set the value at key ``name`` to ``value`` only if the current
+            value exactly matches the argument.
+            If key doesn’t exist - it won’t be created.
+            (Requires Redis 8.4 or greater)
+
+        ``ifne`` set the value at key ``name`` to ``value`` only if the current
+            value does not exactly match the argument.
+            If key doesn’t exist - it will be created.
+            (Requires Redis 8.4 or greater)
+
+        ``ifdeq`` set the value at key ``name`` to ``value`` only if the current
+            value XXH3 hex digest exactly matches the argument.
+            If key doesn’t exist - it won’t be created.
+            (Requires Redis 8.4 or greater)
+
+        ``ifdne`` set the value at key ``name`` to ``value`` only if the current
+            value XXH3 hex digest does not exactly match the argument.
+            If key doesn’t exist - it will be created.
+            (Requires Redis 8.4 or greater)
+
         For more information, see https://redis.io/commands/set
         """
-        opset = {ex, px, exat, pxat}
-        if len(opset) > 2 or len(opset) > 1 and keepttl:
+
+        if not at_most_one_value_set((ex, px, exat, pxat, keepttl)):
             raise DataError(
                 "``ex``, ``px``, ``exat``, ``pxat``, "
                 "and ``keepttl`` are mutually exclusive."
             )
 
-        if nx and xx:
-            raise DataError("``nx`` and ``xx`` are mutually exclusive.")
+        # Enforce mutual exclusivity among all conditional switches.
+        if not at_most_one_value_set((nx, xx, ifeq, ifne, ifdeq, ifdne)):
+            raise DataError(
+                "``nx``, ``xx``, ``ifeq``, ``ifne``, ``ifdeq``, ``ifdne`` are mutually exclusive."
+            )
 
         pieces: list[EncodableT] = [name, value]
         options = {}
 
-        pieces.extend(extract_expire_flags(ex, px, exat, pxat))
-
-        if keepttl:
-            pieces.append("KEEPTTL")
-
+        # Conditional modifier (exactly one at most)
         if nx:
             pieces.append("NX")
-        if xx:
+        elif xx:
             pieces.append("XX")
+        elif ifeq is not None:
+            pieces.extend(("IFEQ", ifeq))
+        elif ifne is not None:
+            pieces.extend(("IFNE", ifne))
+        elif ifdeq is not None:
+            pieces.extend(("IFDEQ", ifdeq))
+        elif ifdne is not None:
+            pieces.extend(("IFDNE", ifdne))
 
         if get:
             pieces.append("GET")
             options["get"] = True
 
+        pieces.extend(extract_expire_flags(ex, px, exat, pxat))
+
+        if keepttl:
+            pieces.append("KEEPTTL")
+
         return self.execute_command("SET", *pieces, **options)
 
     def __setitem__(self, name: KeyT, value: EncodableT):
@@ -5201,8 +5321,7 @@ def hgetex(
         if not keys:
             raise DataError("'hgetex' should have at least one key provided")
 
-        opset = {ex, px, exat, pxat}
-        if len(opset) > 2 or len(opset) > 1 and persist:
+        if not at_most_one_value_set((ex, px, exat, pxat, persist)):
             raise DataError(
                 "``ex``, ``px``, ``exat``, ``pxat``, "
                 "and ``persist`` are mutually exclusive."
@@ -5347,8 +5466,7 @@ def hsetex(
                 "'items' must contain a list of key/value pairs."
             )
 
-        opset = {ex, px, exat, pxat}
-        if len(opset) > 2 or len(opset) > 1 and keepttl:
+        if not at_most_one_value_set((ex, px, exat, pxat, keepttl)):
             raise DataError(
                 "``ex``, ``px``, ``exat``, ``pxat``, "
                 "and ``keepttl`` are mutually exclusive."

redis/commands/helpers.py

@@ -1,7 +1,7 @@
 import copy
 import random
 import string
-from typing import List, Tuple
+from typing import Any, Iterable, List, Tuple
 
 import redis
 from redis.typing import KeysT, KeyT
@@ -96,3 +96,22 @@ def get_protocol_version(client):
         return client.connection_pool.connection_kwargs.get("protocol")
     elif isinstance(client, redis.cluster.AbstractRedisCluster):
         return client.nodes_manager.connection_kwargs.get("protocol")
+
+
+def at_most_one_value_set(iterable: Iterable[Any]):
+    """
+    Checks that at most one of the values in the iterable is truthy.
+
+    Args:
+        iterable: An iterable of values to check.
+
+    Returns:
+        True if at most one value is truthy, False otherwise.
+
+    Raises:
+        Might raise an error if the values in iterable are not boolean-compatible.
+        For example if the type of the values implement
+        __len__ or __bool__ methods and they raise an error.
+    """
+    values = (bool(x) for x in iterable)
+    return sum(values) <= 1

redis/utils.py

@@ -346,3 +346,76 @@ def new_init(self, *args, **kwargs):
 
     cls.__init__ = new_init
     return cls
+
+
+def warn_experimental(name, stacklevel=2):
+    import warnings
+
+    msg = (
+        f"Call to experimental method {name}. "
+        "Be aware that the function arguments can "
+        "change or be removed in future versions."
+    )
+    warnings.warn(msg, category=UserWarning, stacklevel=stacklevel)
+
+
+def experimental_method() -> Callable[[C], C]:
+    """
+    Decorator to mark a function as experimental.
+    """
+
+    def decorator(func: C) -> C:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            warn_experimental(func.__name__, stacklevel=2)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def warn_experimental_arg_usage(
+    arg_name: Union[list, str],
+    function_name: str,
+    stacklevel: int = 2,
+):
+    import warnings
+
+    msg = (
+        f"Call to '{function_name}' method with experimental"
+        f" usage of input argument/s '{arg_name}'."
+    )
+    warnings.warn(msg, category=UserWarning, stacklevel=stacklevel)
+
+
+def experimental_args(
+    args_to_warn: list = ["*"],
+) -> Callable[[C], C]:
+    """
+    Decorator to mark specified args of a function as experimental.
+    """
+
+    def decorator(func: C) -> C:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Get function argument names
+            arg_names = func.__code__.co_varnames[: func.__code__.co_argcount]
+
+            provided_args = dict(zip(arg_names, args))
+            provided_args.update(kwargs)
+
+            provided_args.pop("self", None)
+
+            if len(provided_args) == 0:
+                return func(*args, **kwargs)
+
+            for arg in args_to_warn:
+                if arg in provided_args:
+                    warn_experimental_arg_usage(arg, func.__name__, stacklevel=3)
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator