valkey-glide 2.0.0rc3__cp310-cp310-macosx_11_0_arm64.whl → 2.2.3__cp310-cp310-macosx_11_0_arm64.whl

glide/async_commands/cluster_commands.py

@@ -4,27 +4,28 @@ from __future__ import annotations
 
 from typing import Dict, List, Mapping, Optional, Union, cast
 
-from glide.async_commands.batch import ClusterBatch
-from glide.async_commands.command_args import ObjectType
-from glide.async_commands.core import (
-    CoreCommands,
+from glide.glide import ClusterScanCursor, Script
+from glide_shared.commands.batch import ClusterBatch
+from glide_shared.commands.batch_options import ClusterBatchOptions
+from glide_shared.commands.command_args import ObjectType
+from glide_shared.commands.core_options import (
     FlushMode,
     FunctionRestorePolicy,
     InfoSection,
 )
-from glide.constants import (
+from glide_shared.constants import (
     TOK,
     TClusterResponse,
     TEncodable,
     TFunctionListResponse,
     TFunctionStatsSingleNodeResponse,
     TResult,
-    TSingleNodeRoute,
 )
-from glide.protobuf.command_request_pb2 import RequestType
-from glide.routes import Route
+from glide_shared.exceptions import RequestError
+from glide_shared.protobuf.command_request_pb2 import RequestType
+from glide_shared.routes import Route
 
-from ..glide import ClusterScanCursor, Script
+from .core import CoreCommands
 
 
 class ClusterCommands(CoreCommands):
@@ -36,9 +37,13 @@ class ClusterCommands(CoreCommands):
         See the [Valkey GLIDE Wiki](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.
+
             For example - Return a list of all pub/sub clients from all nodes::
 
-                connection.customCommand(["CLIENT", "LIST","TYPE", "PUBSUB"], AllNodes())
+                await client.customCommand(["CLIENT", "LIST","TYPE", "PUBSUB"], AllNodes())
 
         Args:
             command_args (List[TEncodable]): List of the command's arguments, where each argument is either a string or bytes.
@@ -63,13 +68,15 @@ class ClusterCommands(CoreCommands):
         """
         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:
             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
@@ -88,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`.
-
-        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]
+            Optional[List[TResult]]: An array of results, where each entry
+                corresponds to a command's execution result.
 
-            # 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]
+        See Also:
+            [Valkey Transactions (Atomic Batches)](https://valkey.io/docs/topics/transactions/)
+            [Valkey Pipelines (Non-Atomic Batches)](https://valkey.io/docs/topics/pipelining/)
 
-            # 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,
@@ -1078,11 +1066,17 @@ class ClusterCommands(CoreCommands):
         self,
         source: TEncodable,
         destination: TEncodable,
+        # TODO next major release the arguments replace and destinationDB must have their order
+        # swapped to align with the standalone order.
+        # At the moment of the patch release 2.1.1. we can't have a breaking change
         replace: Optional[bool] = None,
+        destinationDB: Optional[int] = None,
     ) -> bool:
         """
-        Copies the value stored at the `source` to the `destination` key. When `replace` is True,
-        removes the `destination` key first if it already exists, otherwise performs no action.
+        Copies the value stored at the `source` to the `destination` key. If `destinationDB`
+        is specified, the value will be copied to the database specified by `destinationDB`,
+        otherwise the current database will be used. When `replace` is True, removes the
+        `destination` key first if it already exists, otherwise performs no action.
 
         See [valkey.io](https://valkey.io/commands/copy) for more details.
 
@@ -1093,6 +1087,7 @@ class ClusterCommands(CoreCommands):
             source (TEncodable): The key to the source value.
             destination (TEncodable): The key where the value should be copied to.
             replace (Optional[bool]): If the destination key should be removed before copying the value to it.
+            destinationDB (Optional[int]): The alternative logical database index for the destination key.
 
         Returns:
             bool: True if the source was copied. Otherwise, returns False.
@@ -1101,12 +1096,20 @@ class ClusterCommands(CoreCommands):
             >>> await client.set("source", "sheep")
             >>> await client.copy(b"source", b"destination")
                 True # Source was copied
+            >>> await client.copy(b"source", b"destination", destinationDB=1)
+                True # Source was copied to DB 1
+            >>> await client.select(1)
             >>> await client.get("destination")
                 b"sheep"
 
         Since: Valkey version 6.2.0.
+               The destinationDB argument is available since Valkey 9.0.0
         """
+
+        # Build command arguments
         args: List[TEncodable] = [source, destination]
+        if destinationDB is not None:
+            args.extend(["DB", str(destinationDB)])
         if replace is True:
             args.append("REPLACE")
         return cast(
@@ -1153,7 +1156,7 @@ class ClusterCommands(CoreCommands):
             args.extend(["VERSION", str(version)])
         if parameters:
             for var in parameters:
-                args.extend(str(var))
+                args.append(str(var))
         return cast(
             TClusterResponse[bytes],
             await self._execute_command(RequestType.Lolwut, args, route),
@@ -1433,7 +1436,7 @@ class ClusterCommands(CoreCommands):
 
         Examples:
             >>> lua_script = Script("return { KEYS[1], ARGV[1] }")
-            >>> await client.invoke_script(lua_script, keys=["foo"], args=["bar"] );
+            >>> await client.invoke_script(lua_script, keys=["foo"], args=["bar"])
                 [b"foo", b"bar"]
         """
         return await self._execute_script(script.get_hash(), keys, args)