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

Author: petyaslavova

redis/commands/core.py

@@ -47,6 +47,8 @@
 )
 from redis.utils import (
     deprecated_function,
+    experimental_args,
+    experimental_method,
     extract_expire_flags,
 )
 
@@ -1729,6 +1731,7 @@ def delete(self, *names: KeyT) -> ResponseT:
     def __delitem__(self, name: KeyT):
         self.delete(name)
 
+    @experimental_method()
     def delex(
         self,
         name: KeyT,
@@ -1740,10 +1743,17 @@ def delex(
         """
         Conditionally removes the specified key.
 
-        ifeq match-value - Delete the key only if its value is equal to match-value
-        ifne match-value - Delete the key only if its value is not equal to match-value
-        ifdeq match-digest - Delete the key only if the digest of its value is equal to match-digest
-        ifdne match-digest - Delete the key only if the digest of its value is not equal to match-digest
+        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.
@@ -1878,10 +1888,19 @@ 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
@@ -2385,6 +2404,7 @@ def restore(
 
         return self.execute_command("RESTORE", *params)
 
+    @experimental_args(["ifeq", "ifne", "ifdeq", "ifdne"])
     def set(
         self,
         name: KeyT,
@@ -2405,6 +2425,12 @@ def set(
         """
         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.

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