valkey-glide 2.0.0rc5__pp311-pypy311_pp73-macosx_11_0_arm64.whl → 2.0.1__pp311-pypy311_pp73-macosx_11_0_arm64.whl

glide/__init__.py

@@ -7,6 +7,11 @@ from glide.async_commands.batch import (
     TBatch,
     Transaction,
 )
+from glide.async_commands.batch_options import (
+    BatchOptions,
+    BatchRetryStrategy,
+    ClusterBatchOptions,
+)
 from glide.async_commands.bitmap import (
     BitEncoding,
     BitFieldGet,
@@ -125,6 +130,7 @@ from glide.config import (
     ProtocolVersion,
     ReadFrom,
     ServerCredentials,
+    TlsAdvancedConfiguration,
 )
 from glide.constants import (
     OK,
@@ -168,7 +174,13 @@ from glide.routes import (
     SlotType,
 )
 
-from .glide import ClusterScanCursor, Script
+from .glide import (
+    ClusterScanCursor,
+    OpenTelemetryConfig,
+    OpenTelemetryMetricsConfig,
+    OpenTelemetryTracesConfig,
+    Script,
+)
 
 PubSubMsg = CoreCommands.PubSubMsg
 
@@ -182,6 +194,10 @@ __all__ = [
     "Transaction",
     "TGlideClient",
     "TBatch",
+    # Batch Options
+    "BatchOptions",
+    "BatchRetryStrategy",
+    "ClusterBatchOptions",
     # Config
     "AdvancedGlideClientConfiguration",
     "AdvancedGlideClusterClientConfiguration",
@@ -191,6 +207,9 @@ __all__ = [
     "ReadFrom",
     "ServerCredentials",
     "NodeAddress",
+    "OpenTelemetryConfig",
+    "OpenTelemetryTracesConfig",
+    "OpenTelemetryMetricsConfig",
     "ProtocolVersion",
     "PeriodicChecksManualInterval",
     "PeriodicChecksStatus",
@@ -205,6 +224,7 @@ __all__ = [
     "TJsonUniversalResponse",
     "TOK",
     "TResult",
+    "TlsAdvancedConfiguration",
     "TXInfoStreamFullResponse",
     "TXInfoStreamResponse",
     "FtAggregateResponse",

glide/async_commands/batch.py

@@ -1,9 +1,9 @@
 # Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
 
+import sys
 import threading
 from typing import List, Mapping, Optional, Tuple, TypeVar, Union
 
-from deprecated import deprecated
 from glide.async_commands.bitmap import (
     BitFieldGet,
     BitFieldSubCommands,
@@ -55,8 +55,14 @@ from glide.async_commands.stream import (
     _create_xpending_range_args,
 )
 from glide.constants import TEncodable
+from glide.exceptions import RequestError
 from glide.protobuf.command_request_pb2 import RequestType
 
+if sys.version_info >= (3, 13):
+    from warnings import deprecated
+else:
+    from typing_extensions import deprecated
+
 TBatch = TypeVar("TBatch", bound="BaseBatch")
 
 
@@ -109,7 +115,7 @@ class BaseBatch:
 
     def get(self: TBatch, key: TEncodable) -> TBatch:
         """
-        Get the value associated with the given key, or null if no such value exists.
+        Get the value associated with the given key, or null if no such key exists.
 
         See [valkey.io](https://valkey.io/commands/get/) for details.
 
@@ -273,6 +279,10 @@ class BaseBatch:
         [custom command](https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#custom-command)
         for details on the restrictions and limitations of the custom command API.
 
+        This function should only be used for single-response commands. Commands that don't return complete response and awaits
+        (such as SUBSCRIBE), or that return potentially more than a single response (such as XREAD), or that change the
+        client's behavior (such as entering pub/sub mode on RESP2 connections) shouldn't be called using this function.
+
         Args:
             command_args (List[TEncodable]): List of command arguments.
                 Every part of the command, including the command name and subcommands, should be added as a
@@ -312,6 +322,8 @@ class BaseBatch:
         """
         Get information and statistics about the server.
 
+        Starting from server version 7, command supports multiple section arguments.
+
         See [valkey.io](https://valkey.io/commands/info/) for details.
 
         Args:
@@ -1057,7 +1069,7 @@ class BaseBatch:
         Command response:
             Optional[Mapping[bytes, List[bytes]]]: A map of `key` name mapped to an array of popped elements.
 
-            None if no elements could be popped.
+            `None` if no elements could be popped.
 
         Since: Valkey version 7.0.0.
         """
@@ -1683,8 +1695,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.
 
@@ -1700,16 +1712,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:
@@ -2306,6 +2320,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:
@@ -2412,26 +2430,26 @@ class BaseBatch:
 
         Args:
             key (TEncodable): The key of the stream.
-            start (StreamRangeBound): The starting stream ID bound for the range.
+            start (StreamRangeBound): The starting stream entry ID bound for the range.
 
-                - Use `IdBound` to specify a stream ID.
-                - Use `ExclusiveIdBound` to specify an exclusive bounded stream ID.
+                - Use `IdBound` to specify a stream entry ID.
+                - Since Valkey 6.2.0, use `ExclusiveIdBound` to specify an exclusive bounded stream entry ID.
                 - Use `MinId` to start with the minimum available ID.
 
-            end (StreamRangeBound): The ending stream ID bound for the range.
+            end (StreamRangeBound): The ending stream entry ID bound for the range.
 
-                - Use `IdBound` to specify a stream ID.
-                - Use `ExclusiveIdBound` to specify an exclusive bounded stream ID.
+                - Use `IdBound` to specify a stream entry ID.
+                - Since Valkey 6.2.0, use `ExclusiveIdBound` to specify an exclusive bounded stream entry ID.
                 - Use `MaxId` to end with the maximum available ID.
 
             count (Optional[int]): An optional argument specifying the maximum count of stream entries to return.
                 If `count` is not provided, all stream entries in the range will be returned.
 
         Command response:
-            Optional[Mapping[bytes, List[List[bytes]]]]: A mapping of stream IDs to stream entry data, where entry data is a
+            Optional[Mapping[bytes, List[List[bytes]]]]: A mapping of stream entry IDs to stream entry data, where entry data is a
             list of pairings with format `[[field, entry], [field, entry], ...]`.
 
-            Returns None if the range arguments are not applicable.
+            Returns None if the range arguments are not applicable. Or if count is non-positive.
         """
         args = [key, start.to_arg(), end.to_arg()]
         if count is not None:
@@ -2454,26 +2472,26 @@ class BaseBatch:
 
         Args:
             key (TEncodable): The key of the stream.
-            end (StreamRangeBound): The ending stream ID bound for the range.
+            end (StreamRangeBound): The ending stream entry ID bound for the range.
 
-                - Use `IdBound` to specify a stream ID.
-                - Use `ExclusiveIdBound` to specify an exclusive bounded stream ID.
+                - Use `IdBound` to specify a stream entry ID.
+                - Since Valkey 6.2.0, use `ExclusiveIdBound` to specify an exclusive bounded stream entry ID.
                 - Use `MaxId` to end with the maximum available ID.
 
-            start (StreamRangeBound): The starting stream ID bound for the range.
+            start (StreamRangeBound): The starting stream entry ID bound for the range.
 
-                - Use `IdBound` to specify a stream ID.
-                - Use `ExclusiveIdBound` to specify an exclusive bounded stream ID.
+                - Use `IdBound` to specify a stream entry ID.
+                - Since Valkey 6.2.0, use `ExclusiveIdBound` to specify an exclusive bounded stream entry ID.
                 - Use `MinId` to start with the minimum available ID.
 
             count (Optional[int]): An optional argument specifying the maximum count of stream entries to return.
                 If `count` is not provided, all stream entries in the range will be returned.
 
         Command response:
-            Optional[Mapping[bytes, List[List[bytes]]]]: A mapping of stream IDs to stream entry data, where entry data is a
+            Optional[Mapping[bytes, List[List[bytes]]]]: A mapping of stream entry IDs to stream entry data, where entry data is a
             list of pairings with format `[[field, entry], [field, entry], ...]`.
 
-            Returns None if the range arguments are not applicable.
+            Returns None if the range arguments are not applicable. Or if count is non-positive.
         """
         args = [key, end.to_arg(), start.to_arg()]
         if count is not None:
@@ -2787,7 +2805,7 @@ class BaseBatch:
             min_idle_time_ms (int): Filters the claimed entries to those that have been idle for more than the specified
                 value.
             start (TEncodable): Filters the claimed entries to those that have an ID equal or greater than the specified value.
-            count (Optional[int]): Limits the number of claimed entries to the specified value.
+            count (Optional[int]): Limits the number of claimed entries to the specified value. Default value is 100.
 
         Command response:
             List[Union[str, Mapping[bytes, List[List[bytes]]], List[bytes]]]: A list containing the following elements:
@@ -2832,7 +2850,7 @@ class BaseBatch:
             min_idle_time_ms (int): Filters the claimed entries to those that have been idle for more than the specified
                 value.
             start (TEncodable): Filters the claimed entries to those that have an ID equal or greater than the specified value.
-            count (Optional[int]): Limits the number of claimed entries to the specified value.
+            count (Optional[int]): Limits the number of claimed entries to the specified value. Default value is 100.
 
         Command response:
             List[Union[bytes, List[bytes]]]: A list containing the following elements:
@@ -3263,7 +3281,7 @@ class BaseBatch:
         Commands response:
             Optional[float]: The score of the member.
 
-            If there was a conflict with choosing the XX/NX/LT/GT options, the operation aborts and None is returned.
+            If there was a conflict with choosing the XX/NX/LT/GT options, the operation aborts and `None` is returned.
         """
         args = [key]
         if existing_options:
@@ -4264,10 +4282,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)
 
@@ -5573,13 +5591,13 @@ class ClusterBatch(BaseBatch):
     # TODO: add all CLUSTER commands
 
 
-@deprecated(reason="Use ClusterBatch(is_atomic=True) instead.")
+@deprecated("Use Batch(is_atomic=True) instead.")
 class Transaction(Batch):
     def __init__(self):
         super().__init__(is_atomic=True)
 
 
-@deprecated(reason="Use ClusterBatch(is_atomic=True) instead.")
+@deprecated("Use ClusterBatch(is_atomic=True) instead.")
 class ClusterTransaction(ClusterBatch):
     def __init__(self):
         super().__init__(is_atomic=True)

glide/async_commands/batch_options.py

@@ -0,0 +1,261 @@
+# Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+
+from typing import Optional
+
+from glide.constants import TSingleNodeRoute
+
+
+class BatchRetryStrategy:
+    """
+    Defines a retry strategy for cluster batch requests, allowing control over retries in case of
+    server or connection errors.
+
+    This strategy determines whether failed commands should be retried, impacting execution order
+    and potential side effects.
+
+    Behavior:
+        - If `retry_server_error` is `True`, failed commands with a retriable error (e.g.,
+          `TRYAGAIN`) will be retried.
+        - If `retry_connection_error` is `True`, batch requests will be retried on
+          connection failures.
+
+    Cautions:
+        - **Server Errors:** Retrying may cause commands targeting the same slot to be executed
+          out of order.
+        - **Connection Errors:** Retrying may lead to duplicate executions, since the server might
+          have already received and processed the request before the error occurred.
+
+    Example Scenario:
+        ```
+        MGET key {key}:1
+        SET key "value"
+        ```
+
+        Expected response when keys are empty:
+        ```
+        [None, None]
+        "OK"
+        ```
+
+        However, if the slot is migrating, both commands may return an `ASK` error and be
+        redirected. Upon `ASK` redirection, a multi-key command may return a `TRYAGAIN`
+        error (triggering a retry), while the `SET` command succeeds immediately. This
+        can result in an unintended reordering of commands if the first command is retried
+        after the slot stabilizes:
+        ```
+        ["value", None]
+        "OK"
+        ```
+
+    Note:
+        Currently, retry strategies are supported only for non-atomic batches.
+
+    Default:
+        Both `retry_server_error` and `retry_connection_error` are set to `False`.
+
+    Args:
+        retry_server_error (bool): If `True`, failed commands with a retriable error (e.g., `TRYAGAIN`)
+            will be automatically retried.
+
+            ⚠️ **Warning:** Enabling this flag may cause commands targeting the same slot to execute
+            out of order.
+
+            By default, this is set to `False`.
+
+        retry_connection_error (bool): If `True`, batch requests will be retried in case of connection errors.
+
+            ⚠️ **Warning:** Retrying after a connection error may lead to duplicate executions, since
+            the server might have already received and processed the request before the error occurred.
+
+            By default, this is set to `False`.
+
+    """
+
+    def __init__(
+        self,
+        retry_server_error: bool = False,
+        retry_connection_error: bool = False,
+    ):
+        """
+        Initialize a BatchRetryStrategy.
+
+        Args:
+            retry_server_error (bool): If `True`, failed commands with a retriable error (e.g., `TRYAGAIN`)
+                will be automatically retried.
+
+                ⚠️ **Warning:** Enabling this flag may cause commands targeting the same slot to execute
+                out of order.
+
+                By default, this is set to `False`.
+
+            retry_connection_error (bool): If `True`, batch requests will be retried in case of connection errors.
+
+                ⚠️ **Warning:** Retrying after a connection error may lead to duplicate executions, since
+                the server might have already received and processed the request before the error occurred.
+
+                By default, this is set to `False`.
+
+        """
+        self.retry_server_error = retry_server_error
+        self.retry_connection_error = retry_connection_error
+
+
+class BaseBatchOptions:
+    """
+    Base options settings class for sending a batch request. Shared settings for standalone and
+    cluster batch requests.
+
+    Args:
+        timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
+            to complete. This duration encompasses sending the request, awaiting a response from the server,
+            and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
+            it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.
+    """
+
+    def __init__(
+        self,
+        timeout: Optional[int] = None,
+    ):
+        """
+        Initialize BaseBatchOptions.
+
+        Args:
+            timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
+                to complete. This duration encompasses sending the request, awaiting a response from the server,
+                and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
+                it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.
+        """
+        self.timeout = timeout
+
+
+class BatchOptions(BaseBatchOptions):
+    """
+    Options for a batch request for a standalone client.
+
+    Args:
+        timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
+            to complete. This duration encompasses sending the request, awaiting a response from the server,
+            and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
+            it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.
+    """
+
+    def __init__(
+        self,
+        timeout: Optional[int] = None,
+    ):
+        """
+        Options for a batch request for a standalone client
+
+        Args:
+            timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
+                to complete. This duration encompasses sending the request, awaiting a response from the server,
+                and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
+                it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.
+        """
+        super().__init__(timeout)
+
+
+class ClusterBatchOptions(BaseBatchOptions):
+    """
+    Options for cluster batch operations.
+
+    Args:
+        timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
+            to complete. This duration encompasses sending the request, awaiting a response from the server,
+            and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
+            it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.
+
+        route (Optional[TSingleNodeRoute]): Configures single-node routing for the batch request. The client
+            will send the batch to the specified node defined by `route`.
+
+            If a redirection error occurs:
+
+            - For Atomic Batches (Transactions), the entire transaction will be redirected.
+            - For Non-Atomic Batches (Pipelines), only the commands that encountered redirection errors
+              will be redirected.
+
+        retry_strategy (Optional[BatchRetryStrategy]): ⚠️ **Please see `BatchRetryStrategy` and read carefully before enabling these
+            options.**
+
+            Defines the retry strategy for handling cluster batch request failures.
+
+            This strategy determines whether failed commands should be retried, potentially impacting
+            execution order.
+
+            - If `retry_server_error` is `True`, retriable errors (e.g., TRYAGAIN) will
+              trigger a retry.
+            - If `retry_connection_error` is `True`, connection failures will trigger a
+              retry.
+
+            **Warnings:**
+
+            - Retrying server errors may cause commands targeting the same slot to execute out of
+              order.
+            - Retrying connection errors may lead to duplicate executions, as it is unclear which
+              commands have already been processed.
+
+            **Note:** Currently, retry strategies are supported only for non-atomic batches.
+
+            **Recommendation:** It is recommended to increase the timeout in `timeout`
+            when enabling these strategies.
+
+            **Default:** Both `retry_server_error` and `retry_connection_error` are set to
+            `False`.
+
+    """
+
+    def __init__(
+        self,
+        timeout: Optional[int] = None,
+        route: Optional[TSingleNodeRoute] = None,
+        retry_strategy: Optional[BatchRetryStrategy] = None,
+    ):
+        """
+        Initialize ClusterBatchOptions.
+
+        Args:
+            timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
+                to complete. This duration encompasses sending the request, awaiting a response from the server,
+                and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
+                it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.
+
+            route (Optional[TSingleNodeRoute]): Configures single-node routing for the batch request. The client
+                will send the batch to the specified node defined by `route`.
+
+                If a redirection error occurs:
+
+                - For Atomic Batches (Transactions), the entire transaction will be redirected.
+                - For Non-Atomic Batches (Pipelines), only the commands that encountered redirection errors
+                will be redirected.
+
+            retry_strategy (Optional[BatchRetryStrategy]): ⚠️ **Please see `BatchRetryStrategy` and read carefully before enabling these
+                options.**
+
+                Defines the retry strategy for handling cluster batch request failures.
+
+                This strategy determines whether failed commands should be retried, potentially impacting
+                execution order.
+
+                - If `retry_server_error` is `True`, retriable errors (e.g., TRYAGAIN) will
+                trigger a retry.
+                - If `retry_connection_error` is `True`, connection failures will trigger a
+                retry.
+
+                **Warnings:**
+
+                - Retrying server errors may cause commands targeting the same slot to execute out of
+                order.
+                - Retrying connection errors may lead to duplicate executions, as it is unclear which
+                commands have already been processed.
+
+                **Note:** Currently, retry strategies are supported only for non-atomic batches.
+
+                **Recommendation:** It is recommended to increase the timeout in `timeout`
+                when enabling these strategies.
+
+                **Default:** Both `retry_server_error` and `retry_connection_error` are set to
+                `False`.
+        """
+        super().__init__(timeout)
+        self.retry_strategy = retry_strategy
+        self.route = route