redis 5.3.0b4__py3-none-any.whl → 6.0.0b1__py3-none-any.whl

redis/commands/core.py

@@ -3,8 +3,10 @@
 import datetime
 import hashlib
 import warnings
+from enum import Enum
 from typing import (
     TYPE_CHECKING,
+    Any,
     AsyncIterator,
     Awaitable,
     Callable,
@@ -35,6 +37,7 @@ from redis.typing import (
     GroupT,
     KeysT,
     KeyT,
+    Number,
     PatternT,
     ResponseT,
     ScriptTextT,
@@ -42,6 +45,10 @@ from redis.typing import (
     TimeoutSecT,
     ZScoreBoundT,
 )
+from redis.utils import (
+    deprecated_function,
+    extract_expire_flags,
+)
 
 from .helpers import list_or_args
 
@@ -528,7 +535,7 @@ class ManagementCommands(CommandsProtocol):
             raise DataError("client_id must be a list")
         if client_id:
             args.append(b"ID")
-            args.append(" ".join(client_id))
+            args += client_id
         return self.execute_command("CLIENT LIST", *args, **kwargs)
 
     def client_getname(self, **kwargs) -> ResponseT:
@@ -1835,10 +1842,10 @@ class BasicKeyCommands(CommandsProtocol):
     def getex(
         self,
         name: KeyT,
-        ex: Union[ExpiryT, None] = None,
-        px: Union[ExpiryT, None] = None,
-        exat: Union[AbsExpiryT, None] = None,
-        pxat: Union[AbsExpiryT, None] = None,
+        ex: Optional[ExpiryT] = None,
+        px: Optional[ExpiryT] = None,
+        exat: Optional[AbsExpiryT] = None,
+        pxat: Optional[AbsExpiryT] = None,
         persist: bool = False,
     ) -> ResponseT:
         """
@@ -1861,7 +1868,6 @@ class BasicKeyCommands(CommandsProtocol):
 
         For more information see https://redis.io/commands/getex
         """
-
         opset = {ex, px, exat, pxat}
         if len(opset) > 2 or len(opset) > 1 and persist:
             raise DataError(
@@ -1869,33 +1875,12 @@ class BasicKeyCommands(CommandsProtocol):
                 "and ``persist`` are mutually exclusive."
             )
 
-        pieces: list[EncodableT] = []
-        # similar to set command
-        if ex is not None:
-            pieces.append("EX")
-            if isinstance(ex, datetime.timedelta):
-                ex = int(ex.total_seconds())
-            pieces.append(ex)
-        if px is not None:
-            pieces.append("PX")
-            if isinstance(px, datetime.timedelta):
-                px = int(px.total_seconds() * 1000)
-            pieces.append(px)
-        # similar to pexpireat command
-        if exat is not None:
-            pieces.append("EXAT")
-            if isinstance(exat, datetime.datetime):
-                exat = int(exat.timestamp())
-            pieces.append(exat)
-        if pxat is not None:
-            pieces.append("PXAT")
-            if isinstance(pxat, datetime.datetime):
-                pxat = int(pxat.timestamp() * 1000)
-            pieces.append(pxat)
+        exp_options: list[EncodableT] = extract_expire_flags(ex, px, exat, pxat)
+
         if persist:
-            pieces.append("PERSIST")
+            exp_options.append("PERSIST")
 
-        return self.execute_command("GETEX", name, *pieces)
+        return self.execute_command("GETEX", name, *exp_options)
 
     def __getitem__(self, name: KeyT):
         """
@@ -2253,14 +2238,14 @@ class BasicKeyCommands(CommandsProtocol):
         self,
         name: KeyT,
         value: EncodableT,
-        ex: Union[ExpiryT, None] = None,
-        px: Union[ExpiryT, None] = None,
+        ex: Optional[ExpiryT] = None,
+        px: Optional[ExpiryT] = None,
         nx: bool = False,
         xx: bool = False,
         keepttl: bool = False,
         get: bool = False,
-        exat: Union[AbsExpiryT, None] = None,
-        pxat: Union[AbsExpiryT, None] = None,
+        exat: Optional[AbsExpiryT] = None,
+        pxat: Optional[AbsExpiryT] = None,
     ) -> ResponseT:
         """
         Set the value at key ``name`` to ``value``
@@ -2290,36 +2275,21 @@ class BasicKeyCommands(CommandsProtocol):
 
         For more information see https://redis.io/commands/set
         """
+        opset = {ex, px, exat, pxat}
+        if len(opset) > 2 or len(opset) > 1 and keepttl:
+            raise DataError(
+                "``ex``, ``px``, ``exat``, ``pxat``, "
+                "and ``keepttl`` are mutually exclusive."
+            )
+
+        if nx and xx:
+            raise DataError("``nx`` and ``xx`` are mutually exclusive.")
+
         pieces: list[EncodableT] = [name, value]
         options = {}
-        if ex is not None:
-            pieces.append("EX")
-            if isinstance(ex, datetime.timedelta):
-                pieces.append(int(ex.total_seconds()))
-            elif isinstance(ex, int):
-                pieces.append(ex)
-            elif isinstance(ex, str) and ex.isdigit():
-                pieces.append(int(ex))
-            else:
-                raise DataError("ex must be datetime.timedelta or int")
-        if px is not None:
-            pieces.append("PX")
-            if isinstance(px, datetime.timedelta):
-                pieces.append(int(px.total_seconds() * 1000))
-            elif isinstance(px, int):
-                pieces.append(px)
-            else:
-                raise DataError("px must be datetime.timedelta or int")
-        if exat is not None:
-            pieces.append("EXAT")
-            if isinstance(exat, datetime.datetime):
-                exat = int(exat.timestamp())
-            pieces.append(exat)
-        if pxat is not None:
-            pieces.append("PXAT")
-            if isinstance(pxat, datetime.datetime):
-                pxat = int(pxat.timestamp() * 1000)
-            pieces.append(pxat)
+
+        pieces.extend(extract_expire_flags(ex, px, exat, pxat))
+
         if keepttl:
             pieces.append("KEEPTTL")
 
@@ -2496,7 +2466,7 @@ class BasicKeyCommands(CommandsProtocol):
 
     def unwatch(self) -> None:
         """
-        Unwatches the value at key ``name``, or None of the key doesn't exist
+        Unwatches all previously watched keys for a transaction
 
         For more information see https://redis.io/commands/unwatch
         """
@@ -2567,7 +2537,7 @@ class ListCommands(CommandsProtocol):
     """
 
     def blpop(
-        self, keys: List, timeout: Optional[int] = 0
+        self, keys: List, timeout: Optional[Number] = 0
     ) -> Union[Awaitable[list], list]:
         """
         LPOP a value off of the first non-empty list
@@ -2588,7 +2558,7 @@ class ListCommands(CommandsProtocol):
         return self.execute_command("BLPOP", *keys)
 
     def brpop(
-        self, keys: List, timeout: Optional[int] = 0
+        self, keys: List, timeout: Optional[Number] = 0
     ) -> Union[Awaitable[list], list]:
         """
         RPOP a value off of the first non-empty list
@@ -2609,7 +2579,7 @@ class ListCommands(CommandsProtocol):
         return self.execute_command("BRPOP", *keys)
 
     def brpoplpush(
-        self, src: str, dst: str, timeout: Optional[int] = 0
+        self, src: str, dst: str, timeout: Optional[Number] = 0
     ) -> Union[Awaitable[Optional[str]], Optional[str]]:
         """
         Pop a value off the tail of ``src``, push it on the head of ``dst``
@@ -3413,7 +3383,9 @@ class SetCommands(CommandsProtocol):
         """
         return self.execute_command("SMEMBERS", name, keys=[name])
 
-    def smismember(self, name: str, values: List, *args: List) -> Union[
+    def smismember(
+        self, name: str, values: List, *args: List
+    ) -> Union[
         Awaitable[List[Union[Literal[0], Literal[1]]]],
         List[Union[Literal[0], Literal[1]]],
     ]:
@@ -4160,8 +4132,7 @@ class SortedSetCommands(CommandsProtocol):
             raise DataError("ZADD allows either 'gt' or 'lt', not both")
         if incr and len(mapping) != 1:
             raise DataError(
-                "ZADD option 'incr' only works when passing a "
-                "single element/score pair"
+                "ZADD option 'incr' only works when passing a single element/score pair"
             )
         if nx and (gt or lt):
             raise DataError("Only one of 'nx', 'lt', or 'gr' may be defined.")
@@ -4937,6 +4908,16 @@ class HyperlogCommands(CommandsProtocol):
 AsyncHyperlogCommands = HyperlogCommands
 
 
+class HashDataPersistOptions(Enum):
+    # set the value for each provided key to each
+    # provided value only if all do not already exist.
+    FNX = "FNX"
+
+    # set the value for each provided key to each
+    # provided value only if all already exist.
+    FXX = "FXX"
+
+
 class HashCommands(CommandsProtocol):
     """
     Redis commands for Hash data type.
@@ -4977,6 +4958,80 @@ class HashCommands(CommandsProtocol):
         """
         return self.execute_command("HGETALL", name, keys=[name])
 
+    def hgetdel(
+        self, name: str, *keys: str
+    ) -> Union[
+        Awaitable[Optional[List[Union[str, bytes]]]], Optional[List[Union[str, bytes]]]
+    ]:
+        """
+        Return the value of ``key`` within the hash ``name`` and
+        delete the field in the hash.
+        This command is similar to HGET, except for the fact that it also deletes
+        the key on success from the hash with the provided ```name```.
+
+        Available since Redis 8.0
+        For more information see https://redis.io/commands/hgetdel
+        """
+        if len(keys) == 0:
+            raise DataError("'hgetdel' should have at least one key provided")
+
+        return self.execute_command("HGETDEL", name, "FIELDS", len(keys), *keys)
+
+    def hgetex(
+        self,
+        name: KeyT,
+        *keys: str,
+        ex: Optional[ExpiryT] = None,
+        px: Optional[ExpiryT] = None,
+        exat: Optional[AbsExpiryT] = None,
+        pxat: Optional[AbsExpiryT] = None,
+        persist: bool = False,
+    ) -> Union[
+        Awaitable[Optional[List[Union[str, bytes]]]], Optional[List[Union[str, bytes]]]
+    ]:
+        """
+        Return the values of ``key`` and ``keys`` within the hash ``name``
+        and optionally set their expiration.
+
+        ``ex`` sets an expire flag on ``kyes`` for ``ex`` seconds.
+
+        ``px`` sets an expire flag on ``keys`` for ``px`` milliseconds.
+
+        ``exat`` sets an expire flag on ``keys`` for ``ex`` seconds,
+        specified in unix time.
+
+        ``pxat`` sets an expire flag on ``keys`` for ``ex`` milliseconds,
+        specified in unix time.
+
+        ``persist`` remove the time to live associated with the ``keys``.
+
+        Available since Redis 8.0
+        For more information see https://redis.io/commands/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:
+            raise DataError(
+                "``ex``, ``px``, ``exat``, ``pxat``, "
+                "and ``persist`` are mutually exclusive."
+            )
+
+        exp_options: list[EncodableT] = extract_expire_flags(ex, px, exat, pxat)
+
+        if persist:
+            exp_options.append("PERSIST")
+
+        return self.execute_command(
+            "HGETEX",
+            name,
+            *exp_options,
+            "FIELDS",
+            len(keys),
+            *keys,
+        )
+
     def hincrby(
         self, name: str, key: str, amount: int = 1
     ) -> Union[Awaitable[int], int]:
@@ -5031,8 +5086,10 @@ class HashCommands(CommandsProtocol):
 
         For more information see https://redis.io/commands/hset
         """
+
         if key is None and not mapping and not items:
             raise DataError("'hset' with no key value pairs")
+
         pieces = []
         if items:
             pieces.extend(items)
@@ -5044,6 +5101,89 @@ class HashCommands(CommandsProtocol):
 
         return self.execute_command("HSET", name, *pieces)
 
+    def hsetex(
+        self,
+        name: str,
+        key: Optional[str] = None,
+        value: Optional[str] = None,
+        mapping: Optional[dict] = None,
+        items: Optional[list] = None,
+        ex: Optional[ExpiryT] = None,
+        px: Optional[ExpiryT] = None,
+        exat: Optional[AbsExpiryT] = None,
+        pxat: Optional[AbsExpiryT] = None,
+        data_persist_option: Optional[HashDataPersistOptions] = None,
+        keepttl: bool = False,
+    ) -> Union[Awaitable[int], int]:
+        """
+        Set ``key`` to ``value`` within hash ``name``
+
+        ``mapping`` accepts a dict of key/value pairs that will be
+        added to hash ``name``.
+
+        ``items`` accepts a list of key/value pairs that will be
+        added to hash ``name``.
+
+        ``ex`` sets an expire flag on ``keys`` for ``ex`` seconds.
+
+        ``px`` sets an expire flag on ``keys`` for ``px`` milliseconds.
+
+        ``exat`` sets an expire flag on ``keys`` for ``ex`` seconds,
+            specified in unix time.
+
+        ``pxat`` sets an expire flag on ``keys`` for ``ex`` milliseconds,
+            specified in unix time.
+
+        ``data_persist_option`` can be set to ``FNX`` or ``FXX`` to control the
+            behavior of the command.
+            ``FNX`` will set the value for each provided key to each
+                provided value only if all do not already exist.
+            ``FXX`` will set the value for each provided key to each
+                provided value only if all already exist.
+
+        ``keepttl`` if True, retain the time to live associated with the keys.
+
+        Returns the number of fields that were added.
+
+        Available since Redis 8.0
+        For more information see https://redis.io/commands/hsetex
+        """
+        if key is None and not mapping and not items:
+            raise DataError("'hsetex' with no key value pairs")
+
+        if items and len(items) % 2 != 0:
+            raise DataError(
+                "'hsetex' with odd number of items. "
+                "'items' must contain a list of key/value pairs."
+            )
+
+        opset = {ex, px, exat, pxat}
+        if len(opset) > 2 or len(opset) > 1 and keepttl:
+            raise DataError(
+                "``ex``, ``px``, ``exat``, ``pxat``, "
+                "and ``keepttl`` are mutually exclusive."
+            )
+
+        exp_options: list[EncodableT] = extract_expire_flags(ex, px, exat, pxat)
+        if data_persist_option:
+            exp_options.append(data_persist_option.value)
+
+        if keepttl:
+            exp_options.append("KEEPTTL")
+
+        pieces = []
+        if items:
+            pieces.extend(items)
+        if key is not None:
+            pieces.extend((key, value))
+        if mapping:
+            for pair in mapping.items():
+                pieces.extend(pair)
+
+        return self.execute_command(
+            "HSETEX", name, *exp_options, "FIELDS", int(len(pieces) / 2), *pieces
+        )
+
     def hsetnx(self, name: str, key: str, value: str) -> Union[Awaitable[bool], bool]:
         """
         Set ``key`` to ``value`` within hash ``name`` if ``key`` does not
@@ -5053,6 +5193,11 @@ class HashCommands(CommandsProtocol):
         """
         return self.execute_command("HSETNX", name, key, value)
 
+    @deprecated_function(
+        version="4.0.0",
+        reason="Use 'hset' instead.",
+        name="hmset",
+    )
     def hmset(self, name: str, mapping: dict) -> Union[Awaitable[str], str]:
         """
         Set key to value within hash ``name`` for each corresponding
@@ -5060,12 +5205,6 @@ class HashCommands(CommandsProtocol):
 
         For more information see https://redis.io/commands/hmset
         """
-        warnings.warn(
-            f"{self.__class__.__name__}.hmset() is deprecated. "
-            f"Use {self.__class__.__name__}.hset() instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
         if not mapping:
             raise DataError("'hmset' with 'mapping' of length 0")
         items = []
@@ -6396,12 +6535,12 @@ class FunctionCommands:
         return self.execute_command("FUNCTION LIST", *args)
 
     def _fcall(
-        self, command: str, function, numkeys: int, *keys_and_args: Optional[List]
+        self, command: str, function, numkeys: int, *keys_and_args: Any
     ) -> Union[Awaitable[str], str]:
         return self.execute_command(command, function, numkeys, *keys_and_args)
 
     def fcall(
-        self, function, numkeys: int, *keys_and_args: Optional[List]
+        self, function, numkeys: int, *keys_and_args: Any
     ) -> Union[Awaitable[str], str]:
         """
         Invoke a function.
@@ -6411,7 +6550,7 @@ class FunctionCommands:
         return self._fcall("FCALL", function, numkeys, *keys_and_args)
 
     def fcall_ro(
-        self, function, numkeys: int, *keys_and_args: Optional[List]
+        self, function, numkeys: int, *keys_and_args: Any
     ) -> Union[Awaitable[str], str]:
         """
         This is a read-only variant of the FCALL command that cannot
@@ -6467,131 +6606,6 @@ class FunctionCommands:
 AsyncFunctionCommands = FunctionCommands
 
 
-class GearsCommands:
-    def tfunction_load(
-        self, lib_code: str, replace: bool = False, config: Union[str, None] = None
-    ) -> ResponseT:
-        """
-        Load a new library to RedisGears.
-
-        ``lib_code`` - the library code.
-        ``config`` - a string representation of a JSON object
-        that will be provided to the library on load time,
-        for more information refer to
-        https://github.com/RedisGears/RedisGears/blob/master/docs/function_advance_topics.md#library-configuration
-        ``replace`` - an optional argument, instructs RedisGears to replace the
-        function if its already exists
-
-        For more information see https://redis.io/commands/tfunction-load/
-        """
-        pieces = []
-        if replace:
-            pieces.append("REPLACE")
-        if config is not None:
-            pieces.extend(["CONFIG", config])
-        pieces.append(lib_code)
-        return self.execute_command("TFUNCTION LOAD", *pieces)
-
-    def tfunction_delete(self, lib_name: str) -> ResponseT:
-        """
-        Delete a library from RedisGears.
-
-        ``lib_name`` the library name to delete.
-
-        For more information see https://redis.io/commands/tfunction-delete/
-        """
-        return self.execute_command("TFUNCTION DELETE", lib_name)
-
-    def tfunction_list(
-        self,
-        with_code: bool = False,
-        verbose: int = 0,
-        lib_name: Union[str, None] = None,
-    ) -> ResponseT:
-        """
-        List the functions with additional information about each function.
-
-        ``with_code`` Show libraries code.
-        ``verbose`` output verbosity level, higher number will increase verbosity level
-        ``lib_name`` specifying a library name (can be used multiple times to show multiple libraries in a single command) # noqa
-
-        For more information see https://redis.io/commands/tfunction-list/
-        """
-        pieces = []
-        if with_code:
-            pieces.append("WITHCODE")
-        if verbose >= 1 and verbose <= 3:
-            pieces.append("v" * verbose)
-        else:
-            raise DataError("verbose can be 1, 2 or 3")
-        if lib_name is not None:
-            pieces.append("LIBRARY")
-            pieces.append(lib_name)
-
-        return self.execute_command("TFUNCTION LIST", *pieces)
-
-    def _tfcall(
-        self,
-        lib_name: str,
-        func_name: str,
-        keys: KeysT = None,
-        _async: bool = False,
-        *args: List,
-    ) -> ResponseT:
-        pieces = [f"{lib_name}.{func_name}"]
-        if keys is not None:
-            pieces.append(len(keys))
-            pieces.extend(keys)
-        else:
-            pieces.append(0)
-        if args is not None:
-            pieces.extend(args)
-        if _async:
-            return self.execute_command("TFCALLASYNC", *pieces)
-        return self.execute_command("TFCALL", *pieces)
-
-    def tfcall(
-        self,
-        lib_name: str,
-        func_name: str,
-        keys: KeysT = None,
-        *args: List,
-    ) -> ResponseT:
-        """
-        Invoke a function.
-
-        ``lib_name`` - the library name contains the function.
-        ``func_name`` - the function name to run.
-        ``keys`` - the keys that will be touched by the function.
-        ``args`` - Additional argument to pass to the function.
-
-        For more information see https://redis.io/commands/tfcall/
-        """
-        return self._tfcall(lib_name, func_name, keys, False, *args)
-
-    def tfcall_async(
-        self,
-        lib_name: str,
-        func_name: str,
-        keys: KeysT = None,
-        *args: List,
-    ) -> ResponseT:
-        """
-        Invoke an async function (coroutine).
-
-        ``lib_name`` - the library name contains the function.
-        ``func_name`` - the function name to run.
-        ``keys`` - the keys that will be touched by the function.
-        ``args`` - Additional argument to pass to the function.
-
-        For more information see https://redis.io/commands/tfcall/
-        """
-        return self._tfcall(lib_name, func_name, keys, True, *args)
-
-
-AsyncGearsCommands = GearsCommands
-
-
 class DataAccessCommands(
     BasicKeyCommands,
     HyperlogCommands,
@@ -6635,7 +6649,6 @@ class CoreCommands(
     PubSubCommands,
     ScriptCommands,
     FunctionCommands,
-    GearsCommands,
 ):
     """
     A class containing all of the implemented redis commands. This class is
@@ -6652,7 +6665,6 @@ class AsyncCoreCommands(
     AsyncPubSubCommands,
     AsyncScriptCommands,
     AsyncFunctionCommands,
-    AsyncGearsCommands,
 ):
     """
     A class containing all of the implemented redis commands. This class is

redis/commands/helpers.py

@@ -79,29 +79,6 @@ def parse_list_to_dict(response):
     return res
 
 
-def parse_to_dict(response):
-    if response is None:
-        return {}
-
-    res = {}
-    for det in response:
-        if not isinstance(det, list) or not det:
-            continue
-        if len(det) == 1:
-            res[det[0]] = True
-        elif isinstance(det[1], list):
-            res[det[0]] = parse_list_to_dict(det[1])
-        else:
-            try:  # try to set the attribute. may be provided without value
-                try:  # try to convert the value to float
-                    res[det[0]] = float(det[1])
-                except (TypeError, ValueError):
-                    res[det[0]] = det[1]
-            except IndexError:
-                pass
-    return res
-
-
 def random_string(length=10):
     """
     Returns a random N character long string.
@@ -111,26 +88,6 @@ def random_string(length=10):
     )
 
 
-def quote_string(v):
-    """
-    RedisGraph strings must be quoted,
-    quote_string wraps given v with quotes incase
-    v is a string.
-    """
-
-    if isinstance(v, bytes):
-        v = v.decode()
-    elif not isinstance(v, str):
-        return v
-    if len(v) == 0:
-        return '""'
-
-    v = v.replace("\\", "\\\\")
-    v = v.replace('"', '\\"')
-
-    return f'"{v}"'
-
-
 def decode_dict_keys(obj):
     """Decode the keys of the given dictionary with utf-8."""
     newobj = copy.copy(obj)
@@ -141,33 +98,6 @@ def decode_dict_keys(obj):
     return newobj
 
 
-def stringify_param_value(value):
-    """
-    Turn a parameter value into a string suitable for the params header of
-    a Cypher command.
-    You may pass any value that would be accepted by `json.dumps()`.
-
-    Ways in which output differs from that of `str()`:
-        * Strings are quoted.
-        * None --> "null".
-        * In dictionaries, keys are _not_ quoted.
-
-    :param value: The parameter value to be turned into a string.
-    :return: string
-    """
-
-    if isinstance(value, str):
-        return quote_string(value)
-    elif value is None:
-        return "null"
-    elif isinstance(value, (list, tuple)):
-        return f'[{",".join(map(stringify_param_value, value))}]'
-    elif isinstance(value, dict):
-        return f'{{{",".join(f"{k}:{stringify_param_value(v)}" for k, v in value.items())}}}'  # noqa
-    else:
-        return str(value)
-
-
 def get_protocol_version(client):
     if isinstance(client, redis.Redis) or isinstance(client, redis.asyncio.Redis):
         return client.connection_pool.connection_kwargs.get("protocol")