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

glide_shared/commands/batch_options.py

@@ -0,0 +1,261 @@
+# Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+
+from typing import Optional
+
+from glide_shared.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 → glide_shared/commands}/bitmap.py

@@ -23,25 +23,27 @@ class BitmapIndexType(Enum):
 
 
 class OffsetOptions:
+    """
+    Represents offsets specifying a string interval to analyze in the `BITCOUNT` command. The offsets are
+    zero-based indexes, with `0` being the first index of the string, `1` being the next index and so on.
+    The offsets can also be negative numbers indicating offsets starting at the end of the string, with `-1` being
+    the last index of the string, `-2` being the penultimate, and so on.
+
+    Attributes:
+        start (int): The starting offset index.
+        end (Optional[int]): The ending offset index. Optional since Valkey version 8.0.0 and above for the BITCOUNT
+            command. If not provided, it will default to the end of the string.
+        index_type (Optional[BitmapIndexType]): The index offset type. This option can only be specified if you are
+            using Valkey version 7.0.0 or above. Could be either `BitmapIndexType.BYTE` or `BitmapIndexType.BIT`.
+            If no index type is provided, the indexes will be assumed to be byte indexes.
+    """
+
     def __init__(
         self,
         start: int,
         end: Optional[int] = None,
         index_type: Optional[BitmapIndexType] = None,
     ):
-        """
-        Represents offsets specifying a string interval to analyze in the `BITCOUNT` command. The offsets are
-        zero-based indexes, with `0` being the first index of the string, `1` being the next index and so on.
-        The offsets can also be negative numbers indicating offsets starting at the end of the string, with `-1` being
-        the last index of the string, `-2` being the penultimate, and so on.
-
-        Args:
-            start (int): The starting offset index.
-            end (int): The ending offset index. Optional since Valkey version 8.0.0 and above. If not provided, it will default to the end of the string.
-            index_type (Optional[BitmapIndexType]): The index offset type. This option can only be specified if you are
-                using Valkey version 7.0.0 or above. Could be either `BitmapIndexType.BYTE` or `BitmapIndexType.BIT`.
-                If no index type is provided, the indexes will be assumed to be byte indexes.
-        """
         self.start = start
         self.end = end
         self.index_type = index_type
@@ -84,16 +86,17 @@ class BitEncoding(ABC):
 
 
 class SignedEncoding(BitEncoding):
-    # Prefix specifying that the encoding is signed.
+    """
+    Represents a signed argument encoding. Must be less than 65 bits long.
+
+    Attributes:
+        encoding_length (int): The bit size of the encoding.
+    """
+
+    #: Prefix specifying that the encoding is signed.
     SIGNED_ENCODING_PREFIX = "i"
 
     def __init__(self, encoding_length: int):
-        """
-        Represents a signed argument encoding. Must be less than 65 bits long.
-
-        Args:
-            encoding_length (int): The bit size of the encoding.
-        """
         self._encoding = f"{self.SIGNED_ENCODING_PREFIX}{str(encoding_length)}"
 
     def to_arg(self) -> str:
@@ -101,16 +104,17 @@ class SignedEncoding(BitEncoding):
 
 
 class UnsignedEncoding(BitEncoding):
-    # Prefix specifying that the encoding is unsigned.
+    """
+    Represents an unsigned argument encoding. Must be less than 64 bits long.
+
+    Attributes:
+        encoding_length (int): The bit size of the encoding.
+    """
+
+    #: Prefix specifying that the encoding is unsigned.
     UNSIGNED_ENCODING_PREFIX = "u"
 
     def __init__(self, encoding_length: int):
-        """
-        Represents an unsigned argument encoding. Must be less than 64 bits long.
-
-        Args:
-            encoding_length (int): The bit size of the encoding.
-        """
         self._encoding = f"{self.UNSIGNED_ENCODING_PREFIX}{str(encoding_length)}"
 
     def to_arg(self) -> str:
@@ -130,17 +134,18 @@ class BitFieldOffset(ABC):
 
 
 class BitOffset(BitFieldOffset):
-    def __init__(self, offset: int):
-        """
-        Represents an offset in an array of bits for the `BITFIELD` or `BITFIELD_RO` commands. Must be greater than or
-        equal to 0.
+    """
+    Represents an offset in an array of bits for the `BITFIELD` or `BITFIELD_RO` commands. Must be greater than or
+    equal to 0.
 
-        For example, if we have the binary `01101001` with offset of 1 for an unsigned encoding of size 4, then the value
-        is 13 from `0(1101)001`.
+    For example, if we have the binary `01101001` with offset of 1 for an unsigned encoding of size 4, then the value
+    is 13 from `0(1101)001`.
 
-        Args:
-            offset (int): The bit index offset in the array of bits.
-        """
+    Attributes:
+        offset (int): The bit index offset in the array of bits.
+    """
+
+    def __init__(self, offset: int):
         self._offset = str(offset)
 
     def to_arg(self) -> str:
@@ -148,22 +153,23 @@ class BitOffset(BitFieldOffset):
 
 
 class BitOffsetMultiplier(BitFieldOffset):
-    # Prefix specifying that the offset uses an encoding multiplier.
-    OFFSET_MULTIPLIER_PREFIX = "#"
-
-    def __init__(self, offset: int):
-        """
-        Represents an offset in an array of bits for the `BITFIELD` or `BITFIELD_RO` commands. The bit offset index is
-        calculated as the numerical value of the offset multiplied by the encoding value. Must be greater than or equal
-        to 0.
+    """
+    Represents an offset in an array of bits for the `BITFIELD` or `BITFIELD_RO` commands. The bit offset index is
+    calculated as the numerical value of the offset multiplied by the encoding value. Must be greater than or equal
+    to 0.
 
-        For example, if we have the binary 01101001 with offset multiplier of 1 for an unsigned encoding of size 4, then
-        the value is 9 from `0110(1001)`.
+    For example, if we have the binary 01101001 with offset multiplier of 1 for an unsigned encoding of size 4, then
+    the value is 9 from `0110(1001)`.
 
-        Args:
-            offset (int): The offset in the array of bits, which will be multiplied by the encoding value to get the
+    Attributes:
+        offset (int): The offset in the array of bits, which will be multiplied by the encoding value to get the
             final bit index offset.
-        """
+    """
+
+    #: Prefix specifying that the offset uses an encoding multiplier.
+    OFFSET_MULTIPLIER_PREFIX = "#"
+
+    def __init__(self, offset: int):
         self._offset = f"{self.OFFSET_MULTIPLIER_PREFIX}{str(offset)}"
 
     def to_arg(self) -> str:
@@ -182,17 +188,18 @@ class BitFieldSubCommands(ABC):
 
 
 class BitFieldGet(BitFieldSubCommands):
-    # "GET" subcommand string for use in the `BITFIELD` or `BITFIELD_RO` commands.
+    """
+    Represents the "GET" subcommand for getting a value in the binary representation of the string stored in `key`.
+
+    Attributes:
+        encoding (BitEncoding): The bit encoding for the subcommand.
+        offset (BitFieldOffset): The offset in the array of bits from which to get the value.
+    """
+
+    #: "GET" subcommand string for use in the `BITFIELD` or `BITFIELD_RO` commands.
     GET_COMMAND_STRING = "GET"
 
     def __init__(self, encoding: BitEncoding, offset: BitFieldOffset):
-        """
-        Represents the "GET" subcommand for getting a value in the binary representation of the string stored in `key`.
-
-        Args:
-            encoding (BitEncoding): The bit encoding for the subcommand.
-            offset (BitFieldOffset): The offset in the array of bits from which to get the value.
-        """
         self._encoding = encoding
         self._offset = offset
 
@@ -201,18 +208,19 @@ class BitFieldGet(BitFieldSubCommands):
 
 
 class BitFieldSet(BitFieldSubCommands):
-    # "SET" subcommand string for use in the `BITFIELD` command.
+    """
+    Represents the "SET" subcommand for setting bits in the binary representation of the string stored in `key`.
+
+    Args:
+        encoding (BitEncoding): The bit encoding for the subcommand.
+        offset (BitOffset): The offset in the array of bits where the value will be set.
+        value (int): The value to set the bits in the binary value to.
+    """
+
+    #: "SET" subcommand string for use in the `BITFIELD` command.
     SET_COMMAND_STRING = "SET"
 
     def __init__(self, encoding: BitEncoding, offset: BitFieldOffset, value: int):
-        """
-        Represents the "SET" subcommand for setting bits in the binary representation of the string stored in `key`.
-
-        Args:
-            encoding (BitEncoding): The bit encoding for the subcommand.
-            offset (BitOffset): The offset in the array of bits where the value will be set.
-            value (int): The value to set the bits in the binary value to.
-        """
         self._encoding = encoding
         self._offset = offset
         self._value = value
@@ -227,19 +235,20 @@ class BitFieldSet(BitFieldSubCommands):
 
 
 class BitFieldIncrBy(BitFieldSubCommands):
-    # "INCRBY" subcommand string for use in the `BITFIELD` command.
+    """
+    Represents the "INCRBY" subcommand for increasing or decreasing bits in the binary representation of the
+    string stored in `key`.
+
+    Attributes:
+        encoding (BitEncoding): The bit encoding for the subcommand.
+        offset (BitOffset): The offset in the array of bits where the value will be incremented.
+        increment (int): The value to increment the bits in the binary value by.
+    """
+
+    #: "INCRBY" subcommand string for use in the `BITFIELD` command.
     INCRBY_COMMAND_STRING = "INCRBY"
 
     def __init__(self, encoding: BitEncoding, offset: BitFieldOffset, increment: int):
-        """
-        Represents the "INCRBY" subcommand for increasing or decreasing bits in the binary representation of the
-        string stored in `key`.
-
-        Args:
-            encoding (BitEncoding): The bit encoding for the subcommand.
-            offset (BitOffset): The offset in the array of bits where the value will be incremented.
-            increment (int): The value to increment the bits in the binary value by.
-        """
         self._encoding = encoding
         self._offset = offset
         self._increment = increment
@@ -260,8 +269,8 @@ class BitOverflowControl(Enum):
 
     WRAP = "WRAP"
     """
-    Performs modulo when overflows occur with unsigned encoding. When overflows occur with signed encoding, the value 
-    restarts at the most negative value. When underflows occur with signed encoding, the value restarts at the most 
+    Performs modulo when overflows occur with unsigned encoding. When overflows occur with signed encoding, the value
+    restarts at the most negative value. When underflows occur with signed encoding, the value restarts at the most
     positive value.
     """
     SAT = "SAT"
@@ -275,17 +284,18 @@ class BitOverflowControl(Enum):
 
 
 class BitFieldOverflow(BitFieldSubCommands):
-    # "OVERFLOW" subcommand string for use in the `BITFIELD` command.
+    """
+    Represents the "OVERFLOW" subcommand that determines the result of the "SET" or "INCRBY" `BITFIELD` subcommands
+    when an underflow or overflow occurs.
+
+    Attributes:
+        overflow_control (BitOverflowControl): The desired overflow behavior.
+    """
+
+    #: "OVERFLOW" subcommand string for use in the `BITFIELD` command.
     OVERFLOW_COMMAND_STRING = "OVERFLOW"
 
     def __init__(self, overflow_control: BitOverflowControl):
-        """
-        Represents the "OVERFLOW" subcommand that determines the result of the "SET" or "INCRBY" `BITFIELD` subcommands
-        when an underflow or overflow occurs.
-
-        Args:
-            overflow_control (BitOverflowControl): The desired overflow behavior.
-        """
         self._overflow_control = overflow_control
 
     def to_args(self) -> List[str]:

{glide/async_commands → glide_shared/commands}/command_args.py

@@ -1,7 +1,6 @@
 # Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
 
 from enum import Enum
-from typing import List, Optional, Union
 
 
 class Limit:
@@ -12,7 +11,7 @@ class Limit:
     similar to the `LIMIT` clause in SQL (e.g., `SELECT LIMIT offset, count`).
 
     This class can be utilized in multiple commands that support limit options,
-    such as [ZRANGE](https://valkey.io/commands/zrange), [SORT](https://valkey.io/commands/sort/), and others.
+    such as [ZRANGE](https://valkey.io/commands/zrange), [SORT](https://valkey.io/commands/sort/) and others.
 
     Args:
         offset (int): The starting position of the range, zero based.
@@ -34,9 +33,11 @@ class OrderBy(Enum):
     Enumeration representing sorting order options.
 
     This enum is used for the following commands:
-    - `SORT`: General sorting in ascending or descending order.
-    - `GEOSEARCH`: Sorting items based on their proximity to a center point.
-    - `FT.AGGREGATE`: Used in the SortBy clause of the FT.AGGREGATE command.
+
+        - `SORT`: General sorting in ascending or descending order.
+        - `GEOSEARCH`: Sorting items based on their proximity to a center point.
+        - `FT.AGGREGATE`: Used in the SortBy clause of the FT.AGGREGATE command.
+
     """
 
     ASC = "ASC"
@@ -93,7 +94,7 @@ class ObjectType(Enum):
 
     HASH = "Hash"
     """
-    Represents a hash data type.    
+    Represents a hash data type.
     """
 
     STREAM = "Stream"