valkey-glide 1.2.0rc14__cp311-cp311-macosx_11_0_arm64.whl → 2.2.3__cp311-cp311-macosx_11_0_arm64.whl

glide/async_commands/cluster_commands.py

@@ -2,30 +2,30 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, List, Mapping, Optional, Set, Union, cast
+from typing import Dict, List, Mapping, Optional, Union, cast
 
-from glide.async_commands.command_args import Limit, ObjectType, OrderBy
-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,
-    _build_sort_args,
 )
-from glide.async_commands.transaction import ClusterTransaction
-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):
@@ -37,13 +37,19 @@ 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.
 
-            @example - Return a list of all pub/sub clients from all nodes:
+        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::
+
+                await client.customCommand(["CLIENT", "LIST","TYPE", "PUBSUB"], AllNodes())
 
-                connection.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.
             Every part of the command, including the command name and subcommands, should be added as a separate value in args.
-            route (Optional[Route]): The command will be routed automatically based on the passed command's default request policy, unless `route` is provided, in which
+            route (Optional[Route]): The command will be routed automatically based on the passed command's default request
+                policy, unless `route` is provided, in which
             case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Returns:
@@ -61,13 +67,16 @@ class ClusterCommands(CoreCommands):
     ) -> TClusterResponse[bytes]:
         """
         Get information and statistics about the server.
-        See https://valkey.io/commands/info/ for details.
+
+        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.
+                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.
 
         Returns:
             TClusterResponse[bytes]: If a single node route is requested, returns a bytes string containing the information for
@@ -84,27 +93,120 @@ class ClusterCommands(CoreCommands):
 
     async def exec(
         self,
-        transaction: ClusterTransaction,
-        route: Optional[TSingleNodeRoute] = None,
+        batch: ClusterBatch,
+        raise_on_error: bool,
+        options: Optional[ClusterBatchOptions] = None,
     ) -> Optional[List[TResult]]:
         """
-        Execute a transaction by processing the queued commands.
-        See https://valkey.io/docs/topics/transactions/ for details on Transactions.
+        Executes a batch by processing the queued commands.
+
+        **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 request policy. Multi-node commands are automatically split and
+              dispatched to the appropriate nodes.
+
+        **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`.
+
+        **Retry and Redirection:**
+
+        - If a redirection error occurs:
+            - **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:
-            transaction (ClusterTransaction): A `ClusterTransaction` object containing a list of commands to be executed.
-            route (Optional[TSingleNodeRoute]): If `route` is not provided, the transaction will be routed to the slot owner of the
-                first key found in the transaction. If no key is found, the command will be sent to a random node.
-                If `route` is provided, the client will route the command to the nodes defined by `route`.
+            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 transaction. 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 transaction failed due to a WATCH command, `exec` will return `None`.
-        """
-        commands = transaction.commands[:]
-        return await self._execute_transaction(commands, route)
+            Optional[List[TResult]]: An array of results, where each entry
+                corresponds to a command's execution result.
+
+        See Also:
+            [Valkey Transactions (Atomic Batches)](https://valkey.io/docs/topics/transactions/)
+            [Valkey Pipelines (Non-Atomic Batches)](https://valkey.io/docs/topics/pipelining/)
+
+        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, False, options)
+            >>> print(f"Atomic Batch Result: {atomic_result}")
+            # Output: Atomic Batch Result: [OK, 2, 2]
+
+            # 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, 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,
+            raise_on_error,
+            retry_server_error,
+            retry_connection_error,
+            route,
+            timeout,
+        )
 
     async def config_resetstat(
         self,
@@ -112,11 +214,12 @@ class ClusterCommands(CoreCommands):
     ) -> TOK:
         """
         Resets the statistics reported by the server using the INFO and LATENCY HISTOGRAM commands.
-        See https://valkey.io/commands/config-resetstat/ for details.
+
+        See [valkey.io](https://valkey.io/commands/config-resetstat/) for details.
 
         Args:
-            route (Optional[Route]): The command will be routed automatically to all nodes, 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 automatically to all nodes, unless `route` is provided, in
+                which case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Returns:
             OK: Returns "OK" to confirm that the statistics were successfully reset.
@@ -131,11 +234,12 @@ class ClusterCommands(CoreCommands):
     ) -> TOK:
         """
         Rewrite the configuration file with the current configuration.
-        See https://valkey.io/commands/config-rewrite/ for details.
+
+        See [valkey.io](https://valkey.io/commands/config-rewrite/) for details.
 
         Args:
-            route (Optional[TRoute]): The command will be routed automatically to all nodes, unless `route` is provided, in which
-            case the client will route the command to the nodes defined by `route`. Defaults to None.
+            route (Optional[TRoute]): The command will be routed automatically to all nodes, unless `route` is provided, in
+                which case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Returns:
             OK: OK is returned when the configuration was rewritten properly. Otherwise an error is raised.
@@ -154,15 +258,18 @@ class ClusterCommands(CoreCommands):
     ) -> TClusterResponse[int]:
         """
         Returns the current connection id.
-        See https://valkey.io/commands/client-id/ for more information.
+
+        See [valkey.io](https://valkey.io/commands/client-id/) for more information.
 
         Args:
             route (Optional[Route]): The command will be sent to a random node, unless `route` is provided, in which
-            case the client will route the command to the nodes defined by `route`.
+                case the client will route the command to the nodes defined by `route`.
 
         Returns:
             TClusterResponse[int]: The id of the client.
+
             If a single node route is requested, returns a int representing the client's id.
+
             Otherwise, returns a dict of [byte , int] where each key contains the address of
             the queried node and the value contains the client's id.
         """
@@ -176,14 +283,14 @@ class ClusterCommands(CoreCommands):
     ) -> bytes:
         """
         Ping the server.
-        See https://valkey.io/commands/ping/ for more details.
+
+        See [valkey.io](https://valkey.io/commands/ping/) for more details.
 
         Args:
             message (Optional[TEncodable]): An optional message to include in the PING command. If not provided,
-            the server will respond with b"PONG". If provided, the server will respond with a copy of the message.
-
+                the server will respond with b"PONG". If provided, the server will respond with a copy of the message.
             route (Optional[Route]): The command will be sent to all primaries, unless `route` is provided, in which
-            case the client will route the command to the nodes defined by `route`
+                case the client will route the command to the nodes defined by `route`
 
         Returns:
            bytes: b'PONG' if `message` is not provided, otherwise return a copy of `message`.
@@ -204,18 +311,22 @@ class ClusterCommands(CoreCommands):
     ) -> TClusterResponse[Dict[bytes, bytes]]:
         """
         Get the values of configuration parameters.
-        See https://valkey.io/commands/config-get/ for details.
+        Starting from server version 7, command supports multiple parameters.
+
+        See [valkey.io](https://valkey.io/commands/config-get/) for details.
 
         Args:
             parameters (List[TEncodable]): A list of configuration parameter names to retrieve values for.
-
             route (Optional[Route]): The command will be routed to a random node, unless `route` is provided,
-            in which case the client will route the command to the nodes defined by `route`.
+                in which case the client will route the command to the nodes defined by `route`.
 
         Returns:
             TClusterResponse[Dict[bytes, bytes]]: A dictionary of values corresponding to the
             configuration parameters.
-            When specifying a route other than a single node, response will be : {Address (bytes) : response (Dict[bytes, bytes]) , ... }
+            When specifying a route other than a single node, response will be::
+
+                {Address (bytes) : response (Dict[bytes, bytes]) , ... }
+
             with type of Dict[bytes, Dict[bytes, bytes]].
 
         Examples:
@@ -236,14 +347,15 @@ class ClusterCommands(CoreCommands):
     ) -> TOK:
         """
         Set configuration parameters to the specified values.
-        See https://valkey.io/commands/config-set/ for details.
+        Starting from server version 7, command supports multiple parameters.
+
+        See [valkey.io](https://valkey.io/commands/config-set/) for details.
 
         Args:
             parameters_map (Mapping[TEncodable, TEncodable]): A map consisting of configuration
-            parameters and their respective values to set.
-
+                parameters and their respective values to set.
             route (Optional[Route]): The command will be routed to all nodes, unless `route` is provided,
-            in which case the client will route the command to the nodes defined by `route`.
+                in which case the client will route the command to the nodes defined by `route`.
 
         Returns:
             OK: Returns OK if all configurations have been successfully set. Otherwise, raises an error.
@@ -265,17 +377,22 @@ class ClusterCommands(CoreCommands):
     ) -> TClusterResponse[Optional[bytes]]:
         """
         Get the name of the connection to which the request is routed.
-        See https://valkey.io/commands/client-getname/ for more details.
+
+        See [valkey.io](https://valkey.io/commands/client-getname/) for more details.
 
         Args:
             route (Optional[Route]): The command will be routed to a random node, unless `route` is provided,
-            in which case the client will route the command to the nodes defined by `route`.
+                in which case the client will route the command to the nodes defined by `route`.
 
         Returns:
             TClusterResponse[Optional[bytes]]: The name of the client connection as a bytes string if a name is set,
             or None if no name is assigned.
-            When specifying a route other than a single node, response will be:
-            {Address (bytes) : response (Optional[bytes]) , ... } with type of Dict[str, Optional[str]].
+
+            When specifying a route other than a single node, response will be::
+
+                {Address (bytes) : response (Optional[bytes]) , ... }
+
+            with type of Dict[str, Optional[str]].
 
         Examples:
             >>> await client.client_getname()
@@ -291,15 +408,18 @@ class ClusterCommands(CoreCommands):
     async def dbsize(self, route: Optional[Route] = None) -> int:
         """
         Returns the number of keys in the database.
-        See https://valkey.io/commands/dbsize for more details.
+
+        See [valkey.io](https://valkey.io/commands/dbsize) for more details.
 
         Args:
             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`.
+                in which case the client will route the command to the nodes defined by `route`.
 
         Returns:
             int: The number of keys in the database.
-            In the case of routing the query to multiple nodes, returns the aggregated number of keys across the different nodes.
+
+            In the case of routing the query to multiple nodes, returns the aggregated number of keys across the
+            different nodes.
 
         Examples:
             >>> await client.dbsize()
@@ -313,17 +433,21 @@ class ClusterCommands(CoreCommands):
         """
         Echoes the provided `message` back.
 
-        See https://valkey.io/commands/echo for more details.
+        See [valkey.io](https://valkey.io/commands/echo) for more details.
 
         Args:
             message (TEncodable): The message to be echoed back.
             route (Optional[Route]): The command will be routed to a random node, unless `route` is provided,
-            in which case the client will route the command to the nodes defined by `route`.
+                in which case the client will route the command to the nodes defined by `route`.
 
         Returns:
             TClusterResponse[bytes]: The provided `message`.
-            When specifying a route other than a single node, response will be:
-            {Address (bytes) : response (bytes) , ... } with type of Dict[bytes, bytes].
+
+            When specifying a route other than a single node, response will be::
+
+                {Address (bytes) : response (bytes) , ... }
+
+            with type of Dict[bytes, bytes].
 
         Examples:
             >>> await client.echo(b"Valkey GLIDE")
@@ -345,7 +469,7 @@ class ClusterCommands(CoreCommands):
         """
         Loads a library to Valkey.
 
-        See https://valkey.io/commands/function-load/ for more details.
+        See [valkey.io](https://valkey.io/commands/function-load/) for more details.
 
         Args:
             library_code (TEncodable): The source code that implements the library.
@@ -358,7 +482,7 @@ class ClusterCommands(CoreCommands):
             bytes: The library name that was loaded.
 
         Examples:
-            >>> code = "#!lua name=mylib \n redis.register_function('myfunc', function(keys, args) return args[1] end)"
+            >>> code = "#!lua name=mylib \\n redis.register_function('myfunc', function(keys, args) return args[1] end)"
             >>> await client.function_load(code, True, RandomNode())
                 b"mylib"
 
@@ -382,7 +506,7 @@ class ClusterCommands(CoreCommands):
         """
         Returns information about the functions and libraries.
 
-        See https://valkey.io/commands/function-list/ for more details.
+        See [valkey.io](https://valkey.io/commands/function-list/) for more details.
 
         Args:
             library_name_pattern (Optional[TEncodable]):  A wildcard pattern for matching library names.
@@ -404,7 +528,9 @@ class ClusterCommands(CoreCommands):
                         b"description": None,
                         b"flags": {b"no-writes"},
                     }],
-                    b"library_code": b"#!lua name=mylib \n redis.register_function('myfunc', function(keys, args) return args[1] end)"
+                    b"library_code":
+                        b"#!lua name=mylib \\n redis.register_function('myfunc', function(keys, args) " \\
+                        b"return args[1] end)"
                 }]
 
         Since: Valkey 7.0.0.
@@ -429,7 +555,7 @@ class ClusterCommands(CoreCommands):
         """
         Deletes all function libraries.
 
-        See https://valkey.io/commands/function-flush/ for more details.
+        See [valkey.io](https://valkey.io/commands/function-flush/) for more details.
 
         Args:
             mode (Optional[FlushMode]): The flushing mode, could be either `SYNC` or `ASYNC`.
@@ -460,10 +586,10 @@ class ClusterCommands(CoreCommands):
         """
         Deletes a library and all its functions.
 
-        See https://valkey.io/commands/function-delete/ for more details.
+        See [valkey.io](https://valkey.io/commands/function-delete/) for more details.
 
         Args:
-            library_code (TEncodable): The library name to delete
+            library_name (TEncodable): The library name to delete
             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`.
 
@@ -490,7 +616,7 @@ class ClusterCommands(CoreCommands):
         Kills a function that is currently executing.
         This command only terminates read-only functions.
 
-        See https://valkey.io/commands/function-kill/ for more details.
+        See [valkey.io](https://valkey.io/commands/function-kill/) for more details.
 
         Args:
             route (Optional[Route]): The command will be routed to all nodes, unless `route` is provided,
@@ -522,7 +648,8 @@ class ClusterCommands(CoreCommands):
     ) -> TClusterResponse[TResult]:
         """
         Invokes a previously loaded function.
-        See https://valkey.io/commands/fcall/ for more details.
+
+        See [valkey.io](https://valkey.io/commands/fcall/) for more details.
 
         Args:
             function (TEncodable): The function name.
@@ -532,13 +659,18 @@ class ClusterCommands(CoreCommands):
                 case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Returns:
-            TClusterResponse[TResult]:
-                If a single node route is requested, returns a Optional[TResult] representing the function's return value.
-                Otherwise, returns a dict of [bytes , Optional[TResult]] where each key contains the address of
-                the queried node and the value contains the function's return value.
+            TClusterResponse[TResult]: If a single node route is requested,
+            returns a Optional[TResult] representing the function's return value.
+
+            Otherwise, returns a dict of [bytes , Optional[TResult]] where each key contains the address of
+            the queried node and the value contains the function's return value.
 
         Example:
-            >>> await client.fcall("Deep_Thought", ["Answer", "to", "the", "Ultimate", "Question", "of", "Life,", "the", "Universe,", "and", "Everything"], RandomNode())
+            >>> await client.fcall(
+            ...     "Deep_Thought",
+            ...     ["Answer", "to", "the", "Ultimate", "Question", "of", "Life,", "the", "Universe,", "and", "Everything"],
+            ...     RandomNode()
+            ... )
                 b'new_value' # Returns the function's return value.
 
         Since: Valkey version 7.0.0.
@@ -560,7 +692,7 @@ class ClusterCommands(CoreCommands):
         """
         Invokes a previously loaded read-only function.
 
-        See https://valkey.io/commands/fcall_ro for more details.
+        See [valkey.io](https://valkey.io/commands/fcall_ro) for more details.
 
         Args:
             function (TEncodable): The function name.
@@ -593,17 +725,19 @@ class ClusterCommands(CoreCommands):
         Returns information about the function that's currently running and information about the
         available execution engines.
 
-        See https://valkey.io/commands/function-stats/ for more details
+        See [valkey.io](https://valkey.io/commands/function-stats/) for more details
 
         Args:
-            route (Optional[Route]): The command will be routed automatically to all nodes, 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 automatically to all nodes, unless `route` is provided, in
+                which case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Returns:
             TClusterResponse[TFunctionStatsSingleNodeResponse]: A `Mapping` with two keys:
+
                 - `running_script` with information about the running script.
                 - `engines` with information about available engines and their stats.
-                See example for more details.
+
+            See example for more details.
 
         Examples:
             >>> await client.function_stats(RandomNode())
@@ -634,7 +768,7 @@ class ClusterCommands(CoreCommands):
         """
         Returns the serialized payload of all loaded libraries.
 
-        See https://valkey.io/commands/function-dump/ for more details.
+        See [valkey.io](https://valkey.io/commands/function-dump/) for more details.
 
         Args:
             route (Optional[Route]): The command will be routed to a random node, unless
@@ -667,7 +801,7 @@ class ClusterCommands(CoreCommands):
         """
         Restores libraries from the serialized payload returned by the `function_dump` command.
 
-        See https://valkey.io/commands/function-restore/ for more details.
+        See [valkey.io](https://valkey.io/commands/function-restore/) for more details.
 
         Args:
             payload (bytes): The serialized data from the `function_dump` command.
@@ -704,24 +838,32 @@ class ClusterCommands(CoreCommands):
         """
         Returns the server time.
 
-        See https://valkey.io/commands/time/ for more details.
+        See [valkey.io](https://valkey.io/commands/time/) for more details.
 
         Args:
             route (Optional[Route]): The command will be routed to a random node, unless `route` is provided,
-            in which case the client will route the command to the nodes defined by `route`.
+                in which case the client will route the command to the nodes defined by `route`.
 
         Returns:
             TClusterResponse[Optional[bytes]]:  The current server time as a two items `array`:
             A Unix timestamp and the amount of microseconds already elapsed in the current second.
             The returned `array` is in a [Unix timestamp, Microseconds already elapsed] format.
-            When specifying a route other than a single node, response will be:
-            {Address (bytes) : response (List[bytes]) , ... } with type of Dict[bytes, List[bytes]].
+
+            When specifying a route other than a single node, response will be::
+
+                {Address (bytes) : response (List[bytes]) , ... }
+
+            with type of Dict[bytes, List[bytes]].
 
         Examples:
             >>> await client.time()
                 [b'1710925775', b'913580']
             >>> await client.time(AllNodes())
-                {b'addr': [b'1710925775', b'913580'], b'addr2': [b'1710925775', b'913580'], b'addr3': [b'1710925775', b'913580']}
+                {
+                    b'addr': [b'1710925775', b'913580'],
+                    b'addr2': [b'1710925775', b'913580'],
+                    b'addr3': [b'1710925775', b'913580']
+                }
         """
         return cast(
             TClusterResponse[List[bytes]],
@@ -732,7 +874,7 @@ class ClusterCommands(CoreCommands):
         """
         Returns the Unix time of the last DB save timestamp or startup timestamp if no save was made since then.
 
-        See https://valkey.io/commands/lastsave for more details.
+        See [valkey.io](https://valkey.io/commands/lastsave) for more details.
 
         Args:
             route (Optional[Route]): The command will be routed to a random node, unless `route` is provided,
@@ -740,15 +882,19 @@ class ClusterCommands(CoreCommands):
 
         Returns:
             TClusterResponse[int]: The Unix time of the last successful DB save.
-                If no route is provided, or a single node route is requested, returns an int representing the Unix time
-                of the last successful DB save. Otherwise, returns a dict of [bytes , int] where each key contains the
-                address of the queried node and the value contains the Unix time of the last successful DB save.
+
+            If no route is provided, or a single node route is requested, returns an int representing the Unix time
+            of the last successful DB save.
+
+            Otherwise, returns a dict of [bytes , int] where each key contains the
+            address of the queried node and the value contains the Unix time of the last successful DB save.
 
         Examples:
             >>> await client.lastsave()
                 1710925775  # Unix time of the last DB save
             >>> await client.lastsave(AllNodes())
-                {b'addr1': 1710925775, b'addr2': 1710925775, b'addr3': 1710925775}  # Unix time of the last DB save on each node
+                {b'addr1': 1710925775, b'addr2': 1710925775, b'addr3': 1710925775}  # Unix time of the last DB save on
+                                                                                    # each node
         """
         return cast(
             TClusterResponse[int],
@@ -766,7 +912,9 @@ class ClusterCommands(CoreCommands):
         This command aggregates PUBLISH and SPUBLISH commands functionalities.
         The mode is selected using the 'sharded' parameter.
         For both sharded and non-sharded mode, request is routed using hashed channel as key.
-        See https://valkey.io/commands/publish and https://valkey.io/commands/spublish for more details.
+
+        See [PUBLISH](https://valkey.io/commands/publish) and [SPUBLISH](https://valkey.io/commands/spublish)
+        for more details.
 
         Args:
             message (TEncodable): Message to publish.
@@ -794,15 +942,15 @@ class ClusterCommands(CoreCommands):
         Lists the currently active shard channels.
         The command is routed to all nodes, and aggregates the response to a single array.
 
-        See https://valkey.io/commands/pubsub-shardchannels for more details.
+        See [valkey.io](https://valkey.io/commands/pubsub-shardchannels) for more details.
 
         Args:
             pattern (Optional[TEncodable]): A glob-style pattern to match active shard channels.
-                                If not provided, all active shard channels are returned.
+                If not provided, all active shard channels are returned.
 
         Returns:
             List[bytes]: A list of currently active shard channels matching the given pattern.
-                    If no pattern is specified, all active shard channels are returned.
+            If no pattern is specified, all active shard channels are returned.
 
         Examples:
             >>> await client.pubsub_shardchannels()
@@ -824,13 +972,14 @@ class ClusterCommands(CoreCommands):
         Returns the number of subscribers (exclusive of clients subscribed to patterns) for the specified shard channels.
 
         Note that it is valid to call this command without channels. In this case, it will just return an empty map.
-        The command is routed to all nodes, and aggregates the response to a single map of the channels and their number of subscriptions.
+        The command is routed to all nodes, and aggregates the response to a single map of the channels and their number of
+        subscriptions.
 
-        See https://valkey.io/commands/pubsub-shardnumsub for more details.
+        See [valkey.io](https://valkey.io/commands/pubsub-shardnumsub) for more details.
 
         Args:
             channels (Optional[List[TEncodable]]): The list of shard channels to query for the number of subscribers.
-                                            If not provided, returns an empty map.
+                If not provided, returns an empty map.
 
         Returns:
             Mapping[bytes, int]: A map where keys are the shard channel names and values are the number of subscribers.
@@ -855,7 +1004,7 @@ class ClusterCommands(CoreCommands):
         """
         Deletes all the keys of all the existing databases. This command never fails.
 
-        See https://valkey.io/commands/flushall for more details.
+        See [valkey.io](https://valkey.io/commands/flushall) for more details.
 
         Args:
             flush_mode (Optional[FlushMode]): The flushing mode, could be either `SYNC` or `ASYNC`.
@@ -886,7 +1035,7 @@ class ClusterCommands(CoreCommands):
         """
         Deletes all the keys of the currently selected database. This command never fails.
 
-        See https://valkey.io/commands/flushdb for more details.
+        See [valkey.io](https://valkey.io/commands/flushdb) for more details.
 
         Args:
             flush_mode (Optional[FlushMode]): The flushing mode, could be either `SYNC` or `ASYNC`.
@@ -917,13 +1066,19 @@ 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 https://valkey.io/commands/copy for more details.
+        See [valkey.io](https://valkey.io/commands/copy) for more details.
 
         Note:
             Both `source` and `destination` must map to the same hash slot.
@@ -932,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.
@@ -940,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(
@@ -962,20 +1126,26 @@ class ClusterCommands(CoreCommands):
         """
         Displays a piece of generative computer art and the Valkey version.
 
-        See https://valkey.io/commands/lolwut for more details.
+        See [valkey.io](https://valkey.io/commands/lolwut) for more details.
 
         Args:
             version (Optional[int]): Version of computer art to generate.
             parameters (Optional[List[int]]): Additional set of arguments in order to change the output:
-                For version `5`, those are length of the line, number of squares per row, and number of squares per column.
-                For version `6`, those are number of columns and number of lines.
+
+                - For version `5`, those are length of the line, number of squares per row, and number of squares per column.
+                - For version `6`, those are number of columns and number of lines.
+
             route (Optional[Route]): The command will be routed to a random node, unless `route` is provided,
                 in which case the client will route the command to the nodes defined by `route`.
 
         Returns:
             TClusterResponse[bytes]: A piece of generative computer art along with the current Valkey version.
-            When specifying a route other than a single node, response will be:
-            {Address (bytes) : response (bytes) , ... } with type of Dict[bytes, bytes].
+
+            When specifying a route other than a single node, response will be::
+
+                {Address (bytes) : response (bytes) , ... }
+
+            with type of Dict[bytes, bytes].
 
         Examples:
             >>> await client.lolwut(6, [40, 20], RandomNode());
@@ -986,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),
@@ -996,7 +1166,7 @@ class ClusterCommands(CoreCommands):
         """
         Returns a random existing key name.
 
-        See https://valkey.io/commands/randomkey for more details.
+        See [valkey.io](https://valkey.io/commands/randomkey) for more details.
 
         Args:
             route (Optional[Route]): The command will be routed to all primary nodes, unless `route` is provided,
@@ -1025,13 +1195,13 @@ class ClusterCommands(CoreCommands):
         and acknowledged by at least `numreplicas` of replicas. If `timeout` is
         reached, the command returns even if the specified number of replicas were not yet reached.
 
-        See https://valkey.io/commands/wait for more details.
+        See [valkey.io](https://valkey.io/commands/wait) for more details.
 
         Args:
             numreplicas (int): The number of replicas to reach.
             timeout (int): The timeout value specified in milliseconds. A value of 0 will block indefinitely.
             route (Optional[Route]): The command will be routed to all primary nodes, unless `route` is provided,
-            in which case the client will route the command to the nodes defined by `route`.
+                in which case the client will route the command to the nodes defined by `route`.
 
         Returns:
             int: The number of replicas reached by all the writes performed in the context of the current connection.
@@ -1039,7 +1209,7 @@ class ClusterCommands(CoreCommands):
         Examples:
             >>> await client.set("key", "value");
             >>> await client.wait(1, 1000);
-            // return 1 when a replica is reached or 0 if 1000ms is reached.
+            # return 1 when a replica is reached or 0 if 1000ms is reached.
         """
         args: List[TEncodable] = [str(numreplicas), str(timeout)]
         return cast(
@@ -1052,7 +1222,7 @@ class ClusterCommands(CoreCommands):
         Flushes all the previously watched keys for a transaction. Executing a transaction will
         automatically flush all previously watched keys.
 
-        See https://valkey.io/commands/unwatch for more details.
+        See [valkey.io](https://valkey.io/commands/unwatch) for more details.
 
         Args:
             route (Optional[Route]): The command will be routed to all primary nodes, unless `route` is provided,
@@ -1076,67 +1246,87 @@ class ClusterCommands(CoreCommands):
         match: Optional[TEncodable] = None,
         count: Optional[int] = None,
         type: Optional[ObjectType] = None,
+        allow_non_covered_slots: bool = False,
     ) -> List[Union[ClusterScanCursor, List[bytes]]]:
         """
-        Incrementally iterates over the keys in the Cluster.
+        Incrementally iterates over the keys in the cluster.
         The method returns a list containing the next cursor and a list of keys.
 
-        This command is similar to the SCAN command, but it is designed to work in a Cluster environment.
-        For each iteration the new cursor object should be used to continue the scan.
+        This command is similar to the SCAN command but is designed to work in a cluster environment.
+        For each iteration, the new cursor object should be used to continue the scan.
         Using the same cursor object for multiple iterations will result in the same keys or unexpected behavior.
-        For more information about the Cluster Scan implementation,
-        see [Cluster Scan](https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#cluster-scan).
+        For more information about the Cluster Scan implementation, see
+        [Cluster Scan](https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#cluster-scan).
 
-        As the SCAN command, the method can be used to iterate over the keys in the database,
-        to return all keys the database have from the time the scan started till the scan ends.
-        The same key can be returned in multiple scans iteration.
+        Like the SCAN command, the method can be used to iterate over the keys in the database,
+        returning all keys the database has from when the scan started until the scan ends.
+        The same key can be returned in multiple scan iterations.
 
-        See https://valkey.io/commands/scan/ for more details.
+        See [valkey.io](https://valkey.io/commands/scan/) for more details.
 
         Args:
             cursor (ClusterScanCursor): The cursor object that wraps the scan state.
-              To start a new scan, create a new empty ClusterScanCursor using ClusterScanCursor().
+                To start a new scan, create a new empty ClusterScanCursor using ClusterScanCursor().
             match (Optional[TEncodable]): A pattern to match keys against.
             count (Optional[int]): The number of keys to return in a single iteration.
-              The actual number returned can vary and is not guaranteed to match this count exactly.
-              This parameter serves as a hint to the server on the number of steps to perform in each iteration.
-              The default value is 10.
+                The actual number returned can vary and is not guaranteed to match this count exactly.
+                This parameter serves as a hint to the server on the number of steps to perform in each iteration.
+                The default value is 10.
             type (Optional[ObjectType]): The type of object to scan for.
+            allow_non_covered_slots (bool): If set to True, the scan will perform even if some slots are not covered by any
+                node.
+                It's important to note that when set to True, the scan has no guarantee to cover all keys in the cluster,
+                and the method loses its way to validate the progress of the scan. Defaults to False.
 
         Returns:
             List[Union[ClusterScanCursor, List[TEncodable]]]: A list containing the next cursor and a list of keys,
-              formatted as [ClusterScanCursor, [key1, key2, ...]].
+            formatted as [ClusterScanCursor, [key1, key2, ...]].
 
         Examples:
-            >>> # In the following example, we will iterate over the keys in the cluster.
-                await client.mset({b'key1': b'value1', b'key2': b'value2', b'key3': b'value3'})
-                cursor = ClusterScanCursor()
-                all_keys = []
-                while not cursor.is_finished():
-                    cursor, keys = await client.scan(cursor, count=10)
-                    all_keys.extend(keys)
-                print(all_keys) # [b'key1', b'key2', b'key3']
-            >>> # In the following example, we will iterate over the keys in the cluster that match the pattern "*key*".
-                await client.mset({b"key1": b"value1", b"key2": b"value2", b"not_my_key": b"value3", b"something_else": b"value4"})
-                cursor = ClusterScanCursor()
-                all_keys = []
-                while not cursor.is_finished():
-                    cursor, keys = await client.scan(cursor, match=b"*key*", count=10)
-                    all_keys.extend(keys)
-                print(all_keys) # [b'my_key1', b'my_key2', b'not_my_key']
-            >>> # In the following example, we will iterate over the keys in the cluster that are of type STRING.
-                await client.mset({b'key1': b'value1', b'key2': b'value2', b'key3': b'value3'})
-                await client.sadd(b"this_is_a_set", [b"value4"])
-                cursor = ClusterScanCursor()
-                all_keys = []
-                while not cursor.is_finished():
-                    cursor, keys = await client.scan(cursor, type=ObjectType.STRING)
-                    all_keys.extend(keys)
-                print(all_keys) # [b'key1', b'key2', b'key3']
+            >>> # Iterate over all keys in the cluster.
+            >>> await client.mset({b'key1': b'value1', b'key2': b'value2', b'key3': b'value3'})
+            >>> cursor = ClusterScanCursor()
+            >>> all_keys = []
+            >>> while not cursor.is_finished():
+            >>>     cursor, keys = await client.scan(cursor, count=10, allow_non_covered_slots=False)
+            >>>     all_keys.extend(keys)
+            >>> print(all_keys)  # [b'key1', b'key2', b'key3']
+
+            >>> # Iterate over keys matching the pattern "*key*".
+            >>> await client.mset(
+            ...     {
+            ...         b"key1": b"value1",
+            ...         b"key2": b"value2",
+            ...         b"not_my_key": b"value3",
+            ...         b"something_else": b"value4"
+            ...     }
+            ... )
+            >>> cursor = ClusterScanCursor()
+            >>> all_keys = []
+            >>> while not cursor.is_finished():
+            >>>     cursor, keys = await client.scan(cursor, match=b"*key*", count=10, allow_non_covered_slots=False)
+            >>>     all_keys.extend(keys)
+            >>> print(all_keys)  # [b'key1', b'key2', b'not_my_key']
+
+            >>> # Iterate over keys of type STRING.
+            >>> await client.mset({b'key1': b'value1', b'key2': b'value2', b'key3': b'value3'})
+            >>> await client.sadd(b"this_is_a_set", [b"value4"])
+            >>> cursor = ClusterScanCursor()
+            >>> all_keys = []
+            >>> while not cursor.is_finished():
+            >>>     cursor, keys = await client.scan(cursor, type=ObjectType.STRING, allow_non_covered_slots=False)
+            >>>     all_keys.extend(keys)
+            >>> print(all_keys)  # [b'key1', b'key2', b'key3']
         """
         return cast(
             List[Union[ClusterScanCursor, List[bytes]]],
-            await self._cluster_scan(cursor, match, count, type),
+            await self._cluster_scan(
+                cursor=cursor,
+                match=match,
+                count=count,
+                type=type,
+                allow_non_covered_slots=allow_non_covered_slots,
+            ),
         )
 
     async def script_exists(
@@ -1145,7 +1335,7 @@ class ClusterCommands(CoreCommands):
         """
         Check existence of scripts in the script cache by their SHA1 digest.
 
-        See https://valkey.io/commands/script-exists for more details.
+        See [valkey.io](https://valkey.io/commands/script-exists) for more details.
 
         Args:
             sha1s (List[TEncodable]): List of SHA1 digests of the scripts to check.
@@ -1171,12 +1361,12 @@ class ClusterCommands(CoreCommands):
         """
         Flush the Lua scripts cache.
 
-        See https://valkey.io/commands/script-flush for more details.
+        See [valkey.io](https://valkey.io/commands/script-flush) for more details.
 
         Args:
             mode (Optional[FlushMode]): The flushing mode, could be either `SYNC` or `ASYNC`.
-            route (Optional[Route]): The command will be routed automatically to all nodes, 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 automatically to all nodes, unless `route` is provided, in
+                which case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Returns:
             TOK: A simple `OK` response.
@@ -1201,12 +1391,14 @@ class ClusterCommands(CoreCommands):
         Kill the currently executing Lua script, assuming no write operation was yet performed by the script.
         The command is routed to all nodes, and aggregates the response to a single array.
 
-        See https://valkey.io/commands/script-kill for more details.
+        See [valkey.io](https://valkey.io/commands/script-kill) for more details.
+
+        Args:
+            route (Optional[Route]): The command will be routed automatically to all nodes, unless `route` is provided, in
+                which case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Returns:
             TOK: A simple `OK` response.
-            route (Optional[Route]): The command will be routed automatically to all nodes, unless `route` is provided, in which
-                case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Examples:
             >>> await client.script_kill()
@@ -1227,9 +1419,11 @@ class ClusterCommands(CoreCommands):
         If the script has not already been loaded, it will be loaded automatically using the `SCRIPT LOAD` command.
         After that, it will be invoked using the `EVALSHA` command.
 
-        When in cluster mode, `key`s must map to the same hash slot.
+        Note:
+            When in cluster mode, each `key` must map to the same hash slot.
 
-        See https://valkey.io/commands/script-load/ and https://valkey.io/commands/evalsha/ for more details.
+        See [SCRIPT LOAD](https://valkey.io/commands/script-load/) and [EVALSHA](https://valkey.io/commands/evalsha/)
+        for more details.
 
         Args:
             script (Script): The Lua script to execute.
@@ -1242,7 +1436,7 @@ class ClusterCommands(CoreCommands):
 
         Examples:
             >>> lua_script = Script("return { KEYS[1], ARGV[1] }")
-            >>> await 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)
@@ -1260,20 +1454,21 @@ class ClusterCommands(CoreCommands):
         If the script has not already been loaded, it will be loaded automatically using the `SCRIPT LOAD` command.
         After that, it will be invoked using the `EVALSHA` command.
 
-        See https://valkey.io/commands/script-load/ and https://valkey.io/commands/evalsha/ for more details.
+        See [SCRIPT LOAD](https://valkey.io/commands/script-load/) and [EVALSHA](https://valkey.io/commands/evalsha/)
+        for more details.
 
         Args:
             script (Script): The Lua script to execute.
             args (Optional[List[TEncodable]]): The non-key arguments for the script.
-            route (Optional[Route]): The command will be routed automatically to a random node, 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 automatically to a random node, unless `route` is provided, in
+                which case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Returns:
             TResult: a value that depends on the script that was executed.
 
         Examples:
             >>> lua_script = Script("return { ARGV[1] }")
-            >>> await invoke_script(lua_script, args=["bar"], route=AllPrimaries());
+            >>> await client.invoke_script(lua_script, args=["bar"], route=AllPrimaries());
                 [b"bar"]
         """
         return await self._execute_script(