valkey-glide 2.0.0rc7__cp39-cp39-macosx_10_7_x86_64.whl → 2.0.1__cp39-cp39-macosx_10_7_x86_64.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

@@ -55,6 +55,7 @@ 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):
@@ -1694,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.
 
@@ -1711,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:
@@ -2317,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:
@@ -4275,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)
 

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

glide/async_commands/cluster_commands.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import Dict, List, Mapping, Optional, Union, cast
 
 from glide.async_commands.batch import ClusterBatch
+from glide.async_commands.batch_options import ClusterBatchOptions
 from glide.async_commands.command_args import ObjectType
 from glide.async_commands.core import (
     CoreCommands,
@@ -19,8 +20,8 @@ from glide.constants import (
     TFunctionListResponse,
     TFunctionStatsSingleNodeResponse,
     TResult,
-    TSingleNodeRoute,
 )
+from glide.exceptions import RequestError
 from glide.protobuf.command_request_pb2 import RequestType
 from glide.routes import Route
 
@@ -74,8 +75,8 @@ class ClusterCommands(CoreCommands):
         Args:
             sections (Optional[List[InfoSection]]): A list of InfoSection values specifying which sections of
                 information to retrieve. When no parameter is provided, the default option is assumed.
-            route (Optional[Route]): The command will be routed to all primaries, unless `route` is provided, in which
-                case the client will route the command to the nodes defined by `route`. Defaults to None.
+            route (Optional[Route]): The command will be routed to all primaries, unless `route` is provided, in
+                which case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Returns:
             TClusterResponse[bytes]: If a single node route is requested, returns a bytes string containing the information for
@@ -94,128 +95,109 @@ class ClusterCommands(CoreCommands):
         self,
         batch: ClusterBatch,
         raise_on_error: bool,
-        route: Optional[TSingleNodeRoute] = None,
-        timeout: Optional[int] = None,
-        retry_server_error: bool = False,
-        retry_connection_error: bool = False,
+        options: Optional[ClusterBatchOptions] = None,
     ) -> Optional[List[TResult]]:
         """
         Executes a batch by processing the queued commands.
 
-        See [Valkey Transactions (Atomic Batches)](https://valkey.io/docs/topics/transactions/) for details.
-        See [Valkey Pipelines (Non-Atomic Batches)](https://valkey.io/docs/topics/pipelining/) for details.
-
-        #### Routing Behavior:
-
-        - If a `route` is specified:
-            - The entire batch is sent to the specified node.
+        **Routing Behavior:**
 
+        - If a `route` is specified in `ClusterBatchOptions`, the entire batch is sent
+          to the specified node.
         - If no `route` is specified:
-            - Atomic batches (Transactions): Routed to the slot owner of the first key in the batch.
-              If no key is found, the request is sent to a random node.
-            - Non-atomic batches (Pipelines): Each command is routed to the node owning the corresponding
-              key's slot. If no key is present, routing follows the command's default request policy.
-              Multi-node commands are automatically split and dispatched to the appropriate nodes.
+            - **Atomic batches (Transactions):** Routed to the slot owner of the
+              first key in the batch. If no key is found, the request is sent to a random node.
+            - **Non-atomic batches (Pipelines):** Each command is routed to the node
+              owning the corresponding key's slot. If no key is present, routing follows the
+              command's request policy. Multi-node commands are automatically split and
+              dispatched to the appropriate nodes.
 
-        #### Behavior notes:
+        **Behavior notes:**
 
-        - Atomic Batches (Transactions): All key-based commands must map to the same hash slot.
-          If keys span different slots, the transaction will fail. If the transaction fails due to a
-          `WATCH` command, `exec` will return `None`.
+        - **Atomic Batches (Transactions):** All key-based commands must map to the
+          same hash slot. If keys span different slots, the transaction will fail. If the
+          transaction fails due to a `WATCH` command, `EXEC` will return `None`.
 
-        #### Retry and Redirection:
+        **Retry and Redirection:**
 
         - If a redirection error occurs:
-            - Atomic batches (Transactions): The entire transaction will be redirected.
-            - Non-atomic batches (Pipelines): Only commands that encountered redirection errors will be redirected.
-
-        - Retries for failures will be handled according to the `retry_server_error` and
-          `retry_connection_error` parameters.
+            - **Atomic batches (Transactions):** The entire transaction will be
+              redirected.
+            - **Non-atomic batches:** Only commands that encountered redirection
+              errors will be redirected.
+        - Retries for failures will be handled according to the configured `BatchRetryStrategy`.
 
         Args:
-            batch (ClusterBatch): A `ClusterBatch` object containing a list of commands to be executed.
-            raise_on_error (bool): Determines how errors are handled within the batch response. When set to
-                `True`, the first encountered error in the batch will be raised as a `RequestError`
-                exception after all retries and reconnections have been executed. When set to `False`,
-                errors will be included as part of the batch response array, allowing the caller to process both
-                successful and failed commands together. In this case, error details will be provided as
-                instances of `RequestError`.
-            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.
-            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, a timeout error will be raised. If not explicitly set,
-                the client's default request timeout will be used.
-            retry_server_error (bool): If `True`, retriable server errors (e.g., `TRYAGAIN`) will trigger a retry.
-                Warning: Retrying server errors may cause commands targeting the same slot to execute out of order.
-                Note: Currently supported only for non-atomic batches. Recommended to increase timeout when enabled.
-            retry_connection_error (bool): If `True`, connection failures will trigger a retry. Warning:
-                Retrying connection errors may lead to duplicate executions, as it is unclear which commands have
-                already been processed. Note: Currently supported only for non-atomic batches. Recommended to increase
-                timeout when enabled.
+            batch (ClusterBatch): A `ClusterBatch` containing the commands to execute.
+            raise_on_error (bool): Determines how errors are handled within the batch response.
+                When set to `True`, the first encountered error in the batch will be raised as an
+                exception of type `RequestError` after all retries and reconnections have been
+                executed.
+                When set to `False`, errors will be included as part of the batch response,
+                allowing the caller to process both successful and failed commands together. In this case,
+                error details will be provided as instances of `RequestError`.
+            options (Optional[ClusterBatchOptions]): A `ClusterBatchOptions` object containing execution options.
 
         Returns:
-            Optional[List[TResult]]: A list of results corresponding to the execution of each command in the batch.
-                If a command returns a value, it will be included in the list. If a command doesn't return a value,
-                the list entry will be `None`. If the batch failed due to a `WATCH` command, `exec` will return
-                `None`.
+            Optional[List[TResult]]: An array of results, where each entry
+                corresponds to a command's execution result.
 
-        Examples:
-            # Example 1: Atomic Batch (Transaction)
-            >>> atomic_batch = ClusterBatch(is_atomic=True)  # Atomic (Transaction)
-            >>> atomic_batch.set("key", "1")
-            >>> atomic_batch.incr("key")
-            >>> atomic_batch.get("key")
-            >>> atomic_result = await cluster_client.exec(atomic_batch, false)
-            >>> print(f"Atomic Batch Result: {atomic_result}")
-            # Expected Output: Atomic Batch Result: [OK, 2, 2]
+        See Also:
+            [Valkey Transactions (Atomic Batches)](https://valkey.io/docs/topics/transactions/)
+            [Valkey Pipelines (Non-Atomic Batches)](https://valkey.io/docs/topics/pipelining/)
 
-            # Example 2: Non-Atomic Batch (Pipeline)
-            >>> non_atomic_batch = ClusterBatch(is_atomic=False)  # Non-Atomic (Pipeline)
-            >>> non_atomic_batch.set("key1", "value1")
-            >>> non_atomic_batch.set("key2", "value2")
-            >>> non_atomic_batch.get("key1")
-            >>> non_atomic_batch.get("key2")
-            >>> non_atomic_result = await cluster_client.exec(non_atomic_batch, false)
-            >>> print(f"Non-Atomic Batch Result: {non_atomic_result}")
-            # Expected Output: Non-Atomic Batch Result: [OK, OK, value1, value2]
-
-            # Example 3: Atomic batch with options
+        Examples:
+            # Atomic batch (transaction): all keys must share the same hash slot
+            >>> options = ClusterBatchOptions(timeout=1000)  # Set a timeout of 1000 milliseconds
             >>> atomic_batch = ClusterBatch(is_atomic=True)
             >>> atomic_batch.set("key", "1")
             >>> atomic_batch.incr("key")
             >>> atomic_batch.get("key")
-            >>> atomic_result = await cluster_client.exec(
-            ...     atomic_batch,
-            ...     timeout=1000,  # Set a timeout of 1000 milliseconds
-            ...     raise_on_error=False  # Do not raise an error on failure
-            ... )
+            >>> atomic_result = await cluster_client.exec(atomic_batch, False, options)
             >>> print(f"Atomic Batch Result: {atomic_result}")
             # Output: Atomic Batch Result: [OK, 2, 2]
 
-            # Example 4: Non-atomic batch with retry options
+            # Non-atomic batch (pipeline): keys may span different hash slots
+            >>> retry_strategy = BatchRetryStrategy(retry_server_error=True, retry_connection_error=False)
+            >>> pipeline_options = ClusterBatchOptions(retry_strategy=retry_strategy)
             >>> non_atomic_batch = ClusterBatch(is_atomic=False)
             >>> non_atomic_batch.set("key1", "value1")
             >>> non_atomic_batch.set("key2", "value2")
             >>> non_atomic_batch.get("key1")
             >>> non_atomic_batch.get("key2")
-            >>> non_atomic_result = await cluster_client.exec(
-            ...     non_atomic_batch,
-            ...     raise_on_error=False,
-            ...     retry_server_error=True,
-            ...     retry_connection_error=False
-            ... )
+            >>> non_atomic_result = await cluster_client.exec(non_atomic_batch, False, pipeline_options)
             >>> print(f"Non-Atomic Batch Result: {non_atomic_result}")
             # Output: Non-Atomic Batch Result: [OK, OK, value1, value2]
         """
         commands = batch.commands[:]
+
+        if (
+            batch.is_atomic
+            and options
+            and options.retry_strategy
+            and (
+                options.retry_strategy.retry_server_error
+                or options.retry_strategy.retry_connection_error
+            )
+        ):
+            raise RequestError(
+                "Retry strategies are not supported for atomic batches (transactions). "
+            )
+
+        # Extract values to make the _execute_batch call cleaner
+        retry_server_error = (
+            options.retry_strategy.retry_server_error
+            if options and options.retry_strategy
+            else False
+        )
+        retry_connection_error = (
+            options.retry_strategy.retry_connection_error
+            if options and options.retry_strategy
+            else False
+        )
+        route = options.route if options else None
+        timeout = options.timeout if options else None
+
         return await self._execute_batch(
             commands,
             batch.is_atomic,