valkey-glide 2.0.0rc7__cp39-cp39-macosx_11_0_arm64.whl → 2.1.0rc1__cp39-cp39-macosx_11_0_arm64.whl

{glide/async_commands → glide_shared/commands}/batch.py

@@ -4,7 +4,7 @@ import sys
 import threading
 from typing import List, Mapping, Optional, Tuple, TypeVar, Union
 
-from glide.async_commands.bitmap import (
+from glide_shared.commands.bitmap import (
     BitFieldGet,
     BitFieldSubCommands,
     BitwiseOperation,
@@ -12,26 +12,27 @@ from glide.async_commands.bitmap import (
     _create_bitfield_args,
     _create_bitfield_read_only_args,
 )
-from glide.async_commands.command_args import Limit, ListDirection, OrderBy
-from glide.async_commands.core import (
+from glide_shared.commands.command_args import Limit, ListDirection, OrderBy
+from glide_shared.commands.core_options import (
     ConditionalChange,
     ExpireOptions,
     ExpiryGetEx,
     ExpirySet,
     FlushMode,
     FunctionRestorePolicy,
-    GeospatialData,
-    GeoUnit,
+    HashFieldConditionalChange,
     InfoSection,
     InsertPosition,
     UpdateOptions,
     _build_sort_args,
 )
-from glide.async_commands.sorted_set import (
+from glide_shared.commands.sorted_set import (
     AggregationType,
     GeoSearchByBox,
     GeoSearchByRadius,
     GeoSearchCount,
+    GeospatialData,
+    GeoUnit,
     InfBound,
     LexBoundary,
     RangeByIndex,
@@ -43,7 +44,7 @@ from glide.async_commands.sorted_set import (
     _create_zinter_zunion_cmd_args,
     _create_zrange_args,
 )
-from glide.async_commands.stream import (
+from glide_shared.commands.stream import (
     StreamAddOptions,
     StreamClaimOptions,
     StreamGroupOptions,
@@ -54,8 +55,9 @@ from glide.async_commands.stream import (
     StreamTrimOptions,
     _create_xpending_range_args,
 )
-from glide.constants import TEncodable
-from glide.protobuf.command_request_pb2 import RequestType
+from glide_shared.constants import TEncodable
+from glide_shared.exceptions import RequestError
+from glide_shared.protobuf.command_request_pb2 import RequestType
 
 if sys.version_info >= (3, 13):
     from warnings import deprecated
@@ -955,6 +957,391 @@ class BaseBatch:
         """
         return self.append_command(RequestType.HStrlen, [key, field])
 
+    def httl(self: TBatch, key: TEncodable, fields: List[TEncodable]) -> TBatch:
+        """
+        Returns the remaining time to live (in seconds) of hash key's field(s) that have an associated expiration.
+
+        See [valkey.io](https://valkey.io/commands/httl/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            fields (List[TEncodable]): The list of fields to get TTL for.
+
+        Commands response:
+            List[int]: A list of TTL values for each field:
+            - Positive integer: remaining TTL in seconds
+            - `-1`: field exists but has no expiration
+            - `-2`: field does not exist or key does not exist
+
+        Since: Valkey 9.0.0
+        """
+        return self.append_command(
+            RequestType.HTtl, [key, "FIELDS", str(len(fields))] + fields
+        )
+
+    def hpttl(self: TBatch, key: TEncodable, fields: List[TEncodable]) -> TBatch:
+        """
+        Returns the remaining time to live (in milliseconds) of hash key's field(s) that have an associated expiration.
+
+        See [valkey.io](https://valkey.io/commands/hpttl/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            fields (List[TEncodable]): The list of fields to get TTL for.
+
+        Commands response:
+            List[int]: A list of TTL values for each field:
+            - Positive integer: remaining TTL in milliseconds
+            - `-1`: field exists but has no expiration
+            - `-2`: field does not exist or key does not exist
+
+        Since: Valkey 9.0.0
+        """
+        return self.append_command(
+            RequestType.HPTtl, [key, "FIELDS", str(len(fields))] + fields
+        )
+
+    def hexpiretime(self: TBatch, key: TEncodable, fields: List[TEncodable]) -> TBatch:
+        """
+        Returns the expiration Unix timestamp (in seconds) of hash key's field(s) that have an associated expiration.
+
+        See [valkey.io](https://valkey.io/commands/hexpiretime/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            fields (List[TEncodable]): The list of fields to get expiration timestamps for.
+
+        Commands response:
+            List[int]: A list of expiration timestamps for each field:
+            - Positive integer: absolute expiration timestamp in seconds (Unix timestamp)
+            - `-1`: field exists but has no expiration
+            - `-2`: field does not exist or key does not exist
+
+        Since: Valkey 9.0.0
+        """
+        return self.append_command(
+            RequestType.HExpireTime, [key, "FIELDS", str(len(fields))] + fields
+        )
+
+    def hpexpiretime(self: TBatch, key: TEncodable, fields: List[TEncodable]) -> TBatch:
+        """
+        Returns the expiration Unix timestamp (in milliseconds) of hash key's field(s) that have an associated expiration.
+
+        See [valkey.io](https://valkey.io/commands/hpexpiretime/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            fields (List[TEncodable]): The list of fields to get expiration timestamps for.
+
+        Returns:
+            TBatch: The batch object for method chaining.
+
+        Command Response:
+            List[int]: A list of expiration timestamps for each field:
+            - Positive integer: absolute expiration timestamp in milliseconds (Unix timestamp in ms)
+            - `-1`: field exists but has no expiration
+            - `-2`: field does not exist or key does not exist
+
+        Since: Valkey 9.0.0
+        """
+        return self.append_command(
+            RequestType.HPExpireTime, [key, "FIELDS", str(len(fields))] + fields
+        )
+
+    def hsetex(
+        self: TBatch,
+        key: TEncodable,
+        field_value_map: Mapping[TEncodable, TEncodable],
+        field_conditional_change: Optional[HashFieldConditionalChange] = None,
+        expiry: Optional[ExpirySet] = None,
+    ) -> TBatch:
+        """
+        Sets the specified fields to their respective values in the hash stored at `key` with optional expiration.
+
+        See [valkey.io](https://valkey.io/commands/hsetex/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            field_value_map (Mapping[TEncodable, TEncodable]): A field-value map consisting of fields and their corresponding
+                values to be set in the hash stored at the specified key.
+            field_conditional_change (Optional[HashFieldConditionalChange]): Field conditional change option:
+                - ONLY_IF_ALL_EXIST (FXX): Only set fields if all of them already exist.
+                - ONLY_IF_NONE_EXIST (FNX): Only set fields if none of them already exist.
+            expiry (Optional[ExpirySet]): Expiration options for the fields:
+                - EX: Expiration time in seconds.
+                - PX: Expiration time in milliseconds.
+                - EXAT: Absolute expiration time in seconds (Unix timestamp).
+                - PXAT: Absolute expiration time in milliseconds (Unix timestamp).
+                - KEEPTTL: Retain existing TTL.
+
+        Commands response:
+            int: 1 if all fields were set successfully, 0 if none were set due to conditional constraints.
+
+        Since: Valkey 9.0.0
+        """
+        args: List[TEncodable] = [key]
+
+        # Add field conditional change option if specified
+        if field_conditional_change is not None:
+            args.append(field_conditional_change.value)
+
+        # Add expiry options if specified
+        if expiry is not None:
+            args.extend(expiry.get_cmd_args())
+
+        # Add FIELDS keyword and field count
+        args.extend(["FIELDS", str(len(field_value_map))])
+
+        # Add field-value pairs
+        for field, value in field_value_map.items():
+            args.extend([field, value])
+
+        return self.append_command(RequestType.HSetEx, args)
+
+    def hgetex(
+        self: TBatch,
+        key: TEncodable,
+        fields: List[TEncodable],
+        expiry: Optional[ExpiryGetEx] = None,
+    ) -> TBatch:
+        """
+        Retrieves the values of specified fields in the hash stored at `key` and optionally sets their expiration.
+
+        See [valkey.io](https://valkey.io/commands/hgetex/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            fields (List[TEncodable]): The list of fields to retrieve from the hash.
+            expiry (Optional[ExpiryGetEx]): Expiration options for the retrieved fields:
+                - EX: Expiration time in seconds.
+                - PX: Expiration time in milliseconds.
+                - EXAT: Absolute expiration time in seconds (Unix timestamp).
+                - PXAT: Absolute expiration time in milliseconds (Unix timestamp).
+                - PERSIST: Remove expiration from the fields.
+
+        Commands response:
+            Optional[List[Optional[bytes]]]: A list of values associated with the given fields, in the same order as requested.
+            For every field that does not exist in the hash, a null value is returned.
+            If `key` does not exist, it is treated as an empty hash, and the function returns a list of null values.
+
+        Since: Valkey 9.0.0
+        """
+        args: List[TEncodable] = [key]
+
+        # Add expiry options if specified
+        if expiry is not None:
+            args.extend(expiry.get_cmd_args())
+
+        # Add FIELDS keyword and field count
+        args.extend(["FIELDS", str(len(fields))])
+
+        # Add fields
+        args.extend(fields)
+
+        return self.append_command(RequestType.HGetEx, args)
+
+    def hexpire(
+        self: TBatch,
+        key: TEncodable,
+        seconds: int,
+        fields: List[TEncodable],
+        option: Optional[ExpireOptions] = None,
+    ) -> TBatch:
+        """
+        Sets expiration time in seconds for one or more hash fields.
+
+        See [valkey.io](https://valkey.io/commands/hexpire/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            seconds (int): The expiration time in seconds.
+            fields (List[TEncodable]): The list of fields to set expiration for.
+            option (Optional[ExpireOptions]): Conditional expiration option:
+                - HasNoExpiry (NX): Set expiration only when the field has no expiry.
+                - HasExistingExpiry (XX): Set expiration only when the field has an existing expiry.
+                - NewExpiryGreaterThanCurrent (GT): Set expiration only when the new expiry is greater than the current one.
+                - NewExpiryLessThanCurrent (LT): Set expiration only when the new expiry is less than the current one.
+
+        Commands response:
+            List[int]: A list of status codes for each field:
+            - `1`: Expiration time was applied successfully.
+            - `0`: Specified condition was not met.
+            - `-2`: Field does not exist or key does not exist.
+            - `2`: Field was deleted immediately (when seconds is 0 or timestamp is in the past).
+
+        Since: Valkey 9.0.0
+        """
+        args: List[TEncodable] = [key, str(seconds)]
+
+        # Add conditional option if specified
+        if option is not None:
+            args.append(option.value)
+
+        # Add FIELDS keyword and field count
+        args.extend(["FIELDS", str(len(fields))])
+
+        # Add fields
+        args.extend(fields)
+
+        return self.append_command(RequestType.HExpire, args)
+
+    def hpersist(self: TBatch, key: TEncodable, fields: List[TEncodable]) -> TBatch:
+        """
+        Removes the expiration from one or more hash fields, making them persistent.
+
+        See [valkey.io](https://valkey.io/commands/hpersist/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            fields (List[TEncodable]): The list of fields to remove expiration from.
+
+        Commands response:
+            List[int]: A list of status codes for each field:
+            - `1`: Expiration was removed successfully (field became persistent).
+            - `-1`: Field exists but has no expiration.
+            - `-2`: Field does not exist or key does not exist.
+
+        Since: Valkey 9.0.0
+        """
+        args: List[TEncodable] = [key, "FIELDS", str(len(fields))] + fields
+
+        return self.append_command(RequestType.HPersist, args)
+
+    def hpexpire(
+        self: TBatch,
+        key: TEncodable,
+        milliseconds: int,
+        fields: List[TEncodable],
+        option: Optional[ExpireOptions] = None,
+    ) -> TBatch:
+        """
+        Sets expiration time in milliseconds for one or more hash fields.
+
+        See [valkey.io](https://valkey.io/commands/hpexpire/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            milliseconds (int): The expiration time in milliseconds.
+            fields (List[TEncodable]): The list of fields to set expiration for.
+            option (Optional[ExpireOptions]): Conditional expiration option:
+                - HasNoExpiry (NX): Set expiration only when the field has no expiry.
+                - HasExistingExpiry (XX): Set expiration only when the field has an existing expiry.
+                - NewExpiryGreaterThanCurrent (GT): Set expiration only when the new expiry is greater than the current one.
+                - NewExpiryLessThanCurrent (LT): Set expiration only when the new expiry is less than the current one.
+
+        Commands response:
+            List[int]: A list of status codes for each field:
+            - `1`: Expiration time was applied successfully.
+            - `0`: Specified condition was not met.
+            - `-2`: Field does not exist or key does not exist.
+            - `2`: Field was deleted immediately (when milliseconds is 0 or timestamp is in the past).
+
+        Since: Valkey 9.0.0
+        """
+        args: List[TEncodable] = [key, str(milliseconds)]
+
+        # Add conditional option if specified
+        if option is not None:
+            args.append(option.value)
+
+        # Add FIELDS keyword and field count
+        args.extend(["FIELDS", str(len(fields))])
+
+        # Add fields
+        args.extend(fields)
+
+        return self.append_command(RequestType.HPExpire, args)
+
+    def hexpireat(
+        self: TBatch,
+        key: TEncodable,
+        unix_timestamp: int,
+        fields: List[TEncodable],
+        option: Optional[ExpireOptions] = None,
+    ) -> TBatch:
+        """
+        Sets expiration time at absolute Unix timestamp in seconds for one or more hash fields.
+
+        See [valkey.io](https://valkey.io/commands/hexpireat/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            unix_timestamp (int): The absolute expiration time as Unix timestamp in seconds.
+            fields (List[TEncodable]): The list of fields to set expiration for.
+            option (Optional[ExpireOptions]): Conditional expiration option:
+                - HasNoExpiry (NX): Set expiration only when the field has no expiry.
+                - HasExistingExpiry (XX): Set expiration only when the field has an existing expiry.
+                - NewExpiryGreaterThanCurrent (GT): Set expiration only when the new expiry is greater than the current one.
+                - NewExpiryLessThanCurrent (LT): Set expiration only when the new expiry is less than the current one.
+
+        Commands response:
+            List[int]: A list of status codes for each field:
+            - `1`: Expiration time was applied successfully.
+            - `0`: Specified condition was not met.
+            - `-2`: Field does not exist or key does not exist.
+            - `2`: Field was deleted immediately (when timestamp is in the past).
+
+        Since: Valkey 9.0.0
+        """
+        args: List[TEncodable] = [key, str(unix_timestamp)]
+
+        # Add conditional option if specified
+        if option is not None:
+            args.append(option.value)
+
+        # Add FIELDS keyword and field count
+        args.extend(["FIELDS", str(len(fields))])
+
+        # Add fields
+        args.extend(fields)
+
+        return self.append_command(RequestType.HExpireAt, args)
+
+    def hpexpireat(
+        self: TBatch,
+        key: TEncodable,
+        unix_timestamp_ms: int,
+        fields: List[TEncodable],
+        option: Optional[ExpireOptions] = None,
+    ) -> TBatch:
+        """
+        Sets expiration time at absolute Unix timestamp in milliseconds for one or more hash fields.
+
+        See [valkey.io](https://valkey.io/commands/hpexpireat/) for more details.
+
+        Args:
+            key (TEncodable): The key of the hash.
+            unix_timestamp_ms (int): The absolute expiration time as Unix timestamp in milliseconds.
+            fields (List[TEncodable]): The list of fields to set expiration for.
+            option (Optional[ExpireOptions]): Conditional expiration option:
+                - HasNoExpiry (NX): Set expiration only when the field has no expiry.
+                - HasExistingExpiry (XX): Set expiration only when the field has an existing expiry.
+                - NewExpiryGreaterThanCurrent (GT): Set expiration only when the new expiry is greater than the current one.
+                - NewExpiryLessThanCurrent (LT): Set expiration only when the new expiry is less than the current one.
+
+        Commands response:
+            List[int]: A list of status codes for each field:
+            - `1`: Expiration time was applied successfully.
+            - `0`: Specified condition was not met.
+            - `-2`: Field does not exist or key does not exist.
+            - `2`: Field was deleted immediately (when timestamp is in the past).
+
+        Since: Valkey 9.0.0
+        """
+        args: List[TEncodable] = [key, str(unix_timestamp_ms)]
+
+        # Add conditional option if specified
+        if option is not None:
+            args.append(option.value)
+
+        # Add FIELDS keyword and field count
+        args.extend(["FIELDS", str(len(fields))])
+
+        # Add fields
+        args.extend(fields)
+
+        return self.append_command(RequestType.HPExpireAt, args)
+
     def lpush(self: TBatch, key: TEncodable, elements: List[TEncodable]) -> TBatch:
         """
         Insert all the specified values at the head of the list stored at `key`.
@@ -1694,8 +2081,8 @@ class BaseBatch:
         Commands response:
             TOK: A simple "OK" response.
 
-            If `start` exceeds the end of the list, or if `start` is greater than `end`, the result will be an empty list
-            (which causes `key` to be removed).
+            If `start` exceeds the end of the list, or if `start` is greater than `end`, the list is emptied
+            and the key is removed.
 
             If `end` exceeds the actual end of the list, it will be treated like the last element of the list.
 
@@ -1711,16 +2098,18 @@ class BaseBatch:
     ) -> TBatch:
         """
         Removes the first `count` occurrences of elements equal to `element` from the list stored at `key`.
-        If `count` is positive, it removes elements equal to `element` moving from head to tail.
-        If `count` is negative, it removes elements equal to `element` moving from tail to head.
-        If `count` is 0 or greater than the occurrences of elements equal to `element`, it removes all elements
-        equal to `element`.
 
         See [valkey.io](https://valkey.io/commands/lrem/) for more details.
 
         Args:
             key (TEncodable): The key of the list.
             count (int): The count of occurrences of elements equal to `element` to remove.
+
+                - If `count` is positive, it removes elements equal to `element` moving from head to tail.
+                - If `count` is negative, it removes elements equal to `element` moving from tail to head.
+                - If `count` is 0 or greater than the occurrences of elements equal to `element`, it removes all elements
+                  equal to `element`.
+
             element (TEncodable): The element to remove from the list.
 
         Commands response:
@@ -2317,6 +2706,10 @@ class BaseBatch:
             args.append("REPLACE")
         if absttl is True:
             args.append("ABSTTL")
+        if idletime is not None and frequency is not None:
+            raise RequestError(
+                "syntax error: IDLETIME and FREQ cannot be set at the same time."
+            )
         if idletime is not None:
             args.extend(["IDLETIME", str(idletime)])
         if frequency is not None:
@@ -4275,10 +4668,10 @@ class BaseBatch:
             elements (List[TEncodable]): A list of members to add to the HyperLogLog stored at `key`.
 
         Commands response:
-            int: If the HyperLogLog is newly created, or if the HyperLogLog approximated cardinality is
-            altered, then returns 1.
+            bool: If the HyperLogLog is newly created, or if the HyperLogLog approximated cardinality is
+            altered, then returns `True`.
 
-            Otherwise, returns 0.
+            Otherwise, returns `False`.
         """
         return self.append_command(RequestType.PfAdd, [key] + elements)