fix shoham comments 2

Signed-off-by: BoazBD <boaz@bardavid.com>

Author: BoazBD

.github/workflows/python.yml

@@ -241,7 +241,6 @@ jobs:
               run: |
                   python -m pip install --upgrade pip
                   pip install sphinx sphinx-rtd-theme
-                  pip install -r dev_requirements.txt
 
             - name: Build docs
               working-directory: ./python/docs

python/python/glide/async_commands/batch.py

@@ -1,7 +1,6 @@
 # Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
 
 import threading
-from abc import ABC
 from typing import List, Mapping, Optional, Tuple, TypeVar, Union
 
 from deprecated import deprecated
@@ -61,26 +60,33 @@
 TBatch = TypeVar("TBatch", bound="BaseBatch")
 
 
-class BaseBatch(ABC):
+class BaseBatch:
     """
-    Base class encompassing shared commands for both standalone and cluster mode implementations in batch.
-
-    See [Transactions](https://valkey.io/topics/transactions/) and
-      [Pipelines](https://valkey.io/topics/pipelines/) for details.
+    Base class encompassing shared commands for both standalone and cluster server installations.
+    Batches allow the execution of a group of commands in a single step.
 
     Batch Response:
-        The response for each command depends on the executed command. Specific response types
-        are documented alongside each method.
+        An ``array`` of command responses is returned by the client ``exec`` command, in the order they were given.
+        Each element in the array represents a command given to the batch.
+        The response for each command depends on the executed Valkey command.
+        Specific response types are documented alongside each method.
 
     Args:
         is_atomic (bool): Determines whether the batch is atomic or non-atomic.
-            If `True`, the batch will be executed as an atomic transaction.
-            If `False`, the batch will be executed as a non-atomic pipeline.
-            See [Valkey Transactions](https://valkey.io/topics/transactions/) and
-            [Valkey Pipelines](https://valkey.io/topics/pipelines/) for more details.
+            If ``True``, the batch will be executed as an atomic transaction.
+            If ``False``, the batch will be executed as a non-atomic pipeline.
+
+    See [Transactions](https://valkey.io/topics/transactions/) and [Pipelines](https://valkey.io/topics/pipelines/) for details.
+
     """
 
     def __init__(self, is_atomic: bool) -> None:
+        """
+        Args:
+            is_atomic (bool): Determines whether the batch is atomic or non-atomic.
+                If `True`, the batch will be executed as an atomic transaction.
+                If `False`, the batch will be executed as a non-atomic pipeline.
+        """
         self.commands: List[Tuple[RequestType.ValueType, List[TEncodable]]] = []
         self.lock = threading.Lock()
         self.is_atomic = is_atomic
@@ -278,7 +284,7 @@ def custom_command(self: TBatch, command_args: List[TEncodable]) -> TBatch:
         Example:
             Append a command to list of all pub/sub clients:
 
-            >>> transaction.customCommand(["CLIENT", "LIST","TYPE", "PUBSUB"])
+            >>> batch.customCommand(["CLIENT", "LIST","TYPE", "PUBSUB"])
         """
         return self.append_command(RequestType.CustomCommand, command_args)
 
@@ -366,7 +372,7 @@ def config_set(
         Command response:
             OK: Returns OK if all configurations have been successfully set.
 
-            Otherwise, the transaction fails with an error.
+            Otherwise, the command fails with an error.
         """
         parameters: List[TEncodable] = []
         for pair in parameters_map.items():
@@ -401,8 +407,10 @@ def mset(self: TBatch, key_value_map: Mapping[TEncodable, TEncodable]) -> TBatch
                 and the keys in `key_value_map` map to different hash slots,
                 the command will be split across these slots and executed separately for each.
                 This means the command is atomic only at the slot level.
-
-        See [valkey.io](https://valkey.io/commands/mset/) for more details.
+                If one or more slot-specific requests fail, the entire call will return the first encountered error, even
+                though some requests may have succeeded while others did not.
+                If this behavior impacts your application logic, consider splitting the
+                request into sub-requests per slot to ensure atomicity.
         """
         parameters: List[TEncodable] = []
         for pair in key_value_map.items():
@@ -448,6 +456,10 @@ def mget(self: TBatch, keys: List[TEncodable]) -> TBatch:
             In cluster mode, if this command is used in a non-atomic batch (pipeline)
             and the keys map to different hash slots, the command will be split across these slots
             and executed separately for each. This means the command is atomic only at the slot level.
+            If one or more slot-specific requests fail, the entire call will return the first encountered error, even
+            though some requests may have succeeded while others did not.
+            If this behavior impacts your application logic, consider splitting the
+            request into sub-requests per slot to ensure atomicity.
         """
         return self.append_command(RequestType.MGet, keys)
 
@@ -473,7 +485,7 @@ def config_rewrite(self: TBatch) -> TBatch:
 
         Command response:
             OK: OK is returned when the configuration was rewritten properly.
-            Otherwise, the transaction fails with an error.
+            Otherwise, the command fails with an error.
         """
         return self.append_command(RequestType.ConfigRewrite, [])
 
@@ -752,7 +764,7 @@ def hlen(self: TBatch, key: TEncodable) -> TBatch:
         Command response:
             int: The number of fields in the hash, or 0 when the key does not exist.
 
-            If `key` holds a value that is not a hash, the batch fails with an error.
+            If `key` holds a value that is not a hash, the command fails with an error.
         """
         return self.append_command(RequestType.HLen, [key])
 
@@ -5294,30 +5306,40 @@ def sort_store(
 
 class Batch(BaseBatch):
     """
-    Extends BaseBatch class for standalone commands that are not supported in cluster mode.
+    Batch implementation for standalone GlideClient. Batches allow the execution of a group
+    of commands in a single step.
 
-    Command Response:
-        The response for each command depends on the executed command. Specific response types
-        are documented alongside each method.
+    Batch Response:
+        An ``array`` of command responses is returned by the client ``exec`` command,
+        in the order they were given. Each element in the array represents a command given to the Batch.
+        The response for each command depends on the executed Valkey command.
+        Specific response types are documented alongside each method.
+
+    Args:
+        is_atomic (bool): Determines whether the batch is atomic or non-atomic. If ``True``,
+            the batch will be executed as an atomic transaction. If ``False``,
+            the batch will be executed as a non-atomic pipeline.
+
+    See [Transactions](https://valkey.io/topics/transactions/) and [Pipelines](https://valkey.io/topics/pipelining/) for details.
 
     Note for Standalone Mode (Cluster Mode Disabled):
         Standalone Batches are executed on the primary node.
 
-    Transaction Example:
-        >>> transaction = Batch(is_atomic=True)
+    Example (Atomic Batch - Transaction):
+        >>> transaction = Batch(is_atomic=True)  # Atomic (Transaction)
         >>> transaction.set("key", "value")
-        >>> transaction.select(1)  # Standalone command
         >>> transaction.get("key")
-        >>> await client.exec(transaction)
-        [OK , OK , None]
-
-    Pipeline Example:
-        >>> pipeline = Batch(is_atomic=True)
-        >>> pipeline.set("key", "value")
-        >>> pipeline.select(1)  # Standalone command
-        >>> pipeline.get("key")
-        >>> await client.exec(pipeline)
-        [OK , OK , None]
+        >>> result = await client.exec(transaction)
+        >>> assert result == [OK, b"value"]
+
+    Example (Non-Atomic Batch - Pipeline):
+        >>> pipeline = Batch(is_atomic=False)  # Non-Atomic (Pipeline)
+        >>> pipeline.set("key1", "value1")
+        >>> pipeline.set("key2", "value2")
+        >>> pipeline.get("key1")
+        >>> pipeline.get("key2")
+        >>> result = await client.exec(pipeline)
+        >>> assert result == [OK, OK, b"value1", b"value2"]
     """
 
     # TODO: add SLAVEOF and all SENTINEL commands
@@ -5408,14 +5430,38 @@ def publish(self, message: TEncodable, channel: TEncodable) -> "Batch":
 
 class ClusterBatch(BaseBatch):
     """
-    Extends BaseBatch class for cluster mode commands that are not supported in standalone.
+    Batch implementation for cluster GlideClusterClient. Batches allow the execution of a group
+    of commands in a single step.
 
-    Command Response:
-        The response for each command depends on the executed command. Specific response types
-        are documented alongside each method.
+    Batch Response:
+        An ``array`` of command responses is returned by the client ``exec`` command,
+        in the order they were given. Each element in the array represents a command given to the ClusterBatch.
+        The response for each command depends on the executed Valkey command.
+        Specific response types are documented alongside each method.
+
+    Args:
+        is_atomic (bool): Determines whether the batch is atomic or non-atomic. If ``True``,
+            the batch will be executed as an atomic transaction. If ``False``,
+            the batch will be executed as a non-atomic pipeline.
+
+    See [Transactions](https://valkey.io/topics/transactions/) and [Pipelines](https://valkey.io/topics/pipelining/) for details.
+
+    Example (Atomic Batch - Transaction) in a Cluster:
+        >>> transaction = ClusterBatch(is_atomic=True)  # Atomic (Transaction)
+        >>> transaction.set("key", "value")
+        >>> transaction.get("key")
+        >>> result = await client.exec(transaction)
+        >>> assert result == [OK, b"value"]
+
+    Example (Non-Atomic Batch - Pipeline) in a Cluster:
+        >>> pipeline = ClusterBatch(is_atomic=False)  # Non-Atomic (Pipeline)
+        >>> pipeline.set("key1", "value1")
+        >>> pipeline.set("key2", "value2")
+        >>> pipeline.get("key1")
+        >>> pipeline.get("key2")
+        >>> result = await client.exec(pipeline)
+        >>> assert result == [OK, OK, b"value1", b"value2"]
 
-    When the client is configured to read from replicas, read commands
-    in a non-atomic batches will be distributed in a round-robin manner across the replicas.
     """
 
     def copy(

python/python/glide/async_commands/cluster_commands.py

@@ -192,7 +192,7 @@ async def exec(
             ...     raise_on_error=False  # Do not raise an error on failure
             ... )
             >>> print(f"Atomic Batch Result: {atomic_result}")
-            # Output: [OK, 2, 2]
+            # Output: Atomic Batch Result: [OK, 2, 2]
 
             # Example 4: Non-atomic batch with retry options
             >>> non_atomic_batch = ClusterBatch(is_atomic=False)
@@ -206,7 +206,7 @@ async def exec(
             ...     retry_connection_error=False
             ... )
             >>> print(f"Non-Atomic Batch Result: {non_atomic_result}")
-            # Output: [OK, OK, value1, value2]
+            # Output: Non-Atomic Batch Result: [OK, OK, value1, value2]
         """
         commands = batch.commands[:]
         return await self._execute_batch(

python/python/glide/async_commands/core.py

@@ -6980,9 +6980,9 @@ async def fcall_ro(
 
     async def watch(self, keys: List[TEncodable]) -> TOK:
         """
-        Marks the given keys to be watched for conditional execution of a batch. Batches
-        will only execute commands if the watched keys are not modified before execution of the
-        batch.
+        Marks the given keys to be watched for conditional execution of an atomic batch (Transaction).
+        Transactions will only execute commands if the watched keys are not modified before execution of the
+        transaction.
 
         See [valkey.io](https://valkey.io/commands/watch) for more details.
 
@@ -7004,17 +7004,17 @@ async def watch(self, keys: List[TEncodable]) -> TOK:
         Examples:
             >>> await client.watch("sampleKey")
                 'OK'
-            >>> batch.set("sampleKey", "foobar")
-            >>> await client.exec(batch)
+            >>> transaction.set("sampleKey", "foobar")
+            >>> await client.exec(transaction)
                 'OK' # Executes successfully and keys are unwatched.
 
             >>> await client.watch("sampleKey")
                 'OK'
-            >>> batch.set("sampleKey", "foobar")
+            >>> transaction.set("sampleKey", "foobar")
             >>> await client.set("sampleKey", "hello world")
                 'OK'
-            >>> await client.exec(batch)
-                None  # None is returned when the watched key is modified before batch execution.
+            >>> await client.exec(transaction)
+                None  # None is returned when the watched key is modified before transaction execution.
         """
 
         return cast(

python/python/glide/async_commands/server_modules/json_batch.py

@@ -4,7 +4,7 @@
 Examples:
     >>> import json
     >>> from glide import json_batch
-    >>> batch = ClusterBatch()
+    >>> batch = ClusterBatch(is_atomic=True)
     >>> value = {'a': 1.0, 'b': 2}
     >>> json_str = json.dumps(value) # Convert Python dictionary to JSON string using json.dumps()
     >>> json_batch.set(batch, "doc", "$", json_str)
@@ -118,10 +118,15 @@ def mget(
     Retrieves the JSON values at the specified `path` stored at multiple `keys`.
 
     Note:
-        If the batch is a transaction (is_atomic=True), then all keys must map to the same slot.
-        In cluster mode, if this command is used in a non-atomic batch (pipeline)
-        and the keys map to different hash slots, the command will be split across these slots
-        and executed separately for each. This means the command is atomic only at the slot level.
+        When in cluster mode:
+        - If the batch is an atomic batch (transaction), then all keys must map to the same slot.
+        - If the batch is a non-atomic batch (pipeline), and the keys map to different hash slots,
+            the command will be split across these slots and executed separately for each.
+            This means the command is atomic only at the slot level. If one or more slot-specific
+            requests fail, the entire call will return the first encountered error, even
+            though some requests may have succeeded while others did not.
+            If this behavior impacts your application logic, consider splitting the
+            request into sub-requests per slot to ensure atomicity.
 
     Args:
         batch (TBatch): The batch to execute the command.