valkey-glide 2.2.1rc1__cp313-cp313-macosx_10_7_x86_64.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_shared/commands/bitmap.py

@@ -0,0 +1,320 @@
+# Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import List, Optional
+
+
+class BitmapIndexType(Enum):
+    """
+    Enumeration specifying if index arguments are BYTE indexes or BIT indexes. Can be specified in `OffsetOptions`,
+    which is an optional argument to the `BITCOUNT` command.
+
+    Since: Valkey version 7.0.0.
+    """
+
+    BYTE = "BYTE"
+    """
+    Specifies that indexes provided to `OffsetOptions` are byte indexes.
+    """
+    BIT = "BIT"
+    """
+    Specifies that indexes provided to `OffsetOptions` are bit indexes.
+    """
+
+
+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,
+    ):
+        self.start = start
+        self.end = end
+        self.index_type = index_type
+
+    def to_args(self) -> List[str]:
+        args = [str(self.start)]
+        if self.end:
+            args.append(str(self.end))
+        if self.index_type is not None:
+            args.append(self.index_type.value)
+
+        return args
+
+
+class BitwiseOperation(Enum):
+    """
+    Enumeration defining the bitwise operation to use in the `BITOP` command. Specifies the bitwise operation to
+    perform between the passed in keys.
+    """
+
+    AND = "AND"
+    OR = "OR"
+    XOR = "XOR"
+    NOT = "NOT"
+
+
+class BitEncoding(ABC):
+    """
+    Abstract Base Class used to specify a signed or unsigned argument encoding for the `BITFIELD` or `BITFIELD_RO`
+    commands.
+    """
+
+    @abstractmethod
+    def to_arg(self) -> str:
+        """
+        Returns the encoding as a string argument to be used in the `BITFIELD` or `BITFIELD_RO`
+        commands.
+        """
+        pass
+
+
+class SignedEncoding(BitEncoding):
+    """
+    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):
+        self._encoding = f"{self.SIGNED_ENCODING_PREFIX}{str(encoding_length)}"
+
+    def to_arg(self) -> str:
+        return self._encoding
+
+
+class UnsignedEncoding(BitEncoding):
+    """
+    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):
+        self._encoding = f"{self.UNSIGNED_ENCODING_PREFIX}{str(encoding_length)}"
+
+    def to_arg(self) -> str:
+        return self._encoding
+
+
+class BitFieldOffset(ABC):
+    """Abstract Base Class representing an offset for an array of bits for the `BITFIELD` or `BITFIELD_RO` commands."""
+
+    @abstractmethod
+    def to_arg(self) -> str:
+        """
+        Returns the offset as a string argument to be used in the `BITFIELD` or `BITFIELD_RO`
+        commands.
+        """
+        pass
+
+
+class BitOffset(BitFieldOffset):
+    """
+    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`.
+
+    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:
+        return self._offset
+
+
+class BitOffsetMultiplier(BitFieldOffset):
+    """
+    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)`.
+
+    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:
+        return self._offset
+
+
+class BitFieldSubCommands(ABC):
+    """Abstract Base Class representing subcommands for the `BITFIELD` or `BITFIELD_RO` commands."""
+
+    @abstractmethod
+    def to_args(self) -> List[str]:
+        """
+        Returns the subcommand as a list of string arguments to be used in the `BITFIELD` or `BITFIELD_RO` commands.
+        """
+        pass
+
+
+class BitFieldGet(BitFieldSubCommands):
+    """
+    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):
+        self._encoding = encoding
+        self._offset = offset
+
+    def to_args(self) -> List[str]:
+        return [self.GET_COMMAND_STRING, self._encoding.to_arg(), self._offset.to_arg()]
+
+
+class BitFieldSet(BitFieldSubCommands):
+    """
+    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):
+        self._encoding = encoding
+        self._offset = offset
+        self._value = value
+
+    def to_args(self) -> List[str]:
+        return [
+            self.SET_COMMAND_STRING,
+            self._encoding.to_arg(),
+            self._offset.to_arg(),
+            str(self._value),
+        ]
+
+
+class BitFieldIncrBy(BitFieldSubCommands):
+    """
+    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):
+        self._encoding = encoding
+        self._offset = offset
+        self._increment = increment
+
+    def to_args(self) -> List[str]:
+        return [
+            self.INCRBY_COMMAND_STRING,
+            self._encoding.to_arg(),
+            self._offset.to_arg(),
+            str(self._increment),
+        ]
+
+
+class BitOverflowControl(Enum):
+    """
+    Enumeration specifying bit overflow controls for the `BITFIELD` command.
+    """
+
+    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
+    positive value.
+    """
+    SAT = "SAT"
+    """
+    Underflows remain set to the minimum value, and overflows remain set to the maximum value.
+    """
+    FAIL = "FAIL"
+    """
+    Returns `None` when overflows occur.
+    """
+
+
+class BitFieldOverflow(BitFieldSubCommands):
+    """
+    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):
+        self._overflow_control = overflow_control
+
+    def to_args(self) -> List[str]:
+        return [self.OVERFLOW_COMMAND_STRING, self._overflow_control.value]
+
+
+def _create_bitfield_args(subcommands: List[BitFieldSubCommands]) -> List[str]:
+    args = []
+    for subcommand in subcommands:
+        args.extend(subcommand.to_args())
+
+    return args
+
+
+def _create_bitfield_read_only_args(
+    subcommands: List[BitFieldGet],
+) -> List[str]:
+    args = []
+    for subcommand in subcommands:
+        args.extend(subcommand.to_args())
+
+    return args

glide_shared/commands/command_args.py

@@ -0,0 +1,103 @@
+# Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+
+from enum import Enum
+
+
+class Limit:
+    """
+    Represents a limit argument for range queries in various commands.
+
+    The `LIMIT` argument is commonly used to specify a subset of results from the matching elements,
+    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.
+
+    Args:
+        offset (int): The starting position of the range, zero based.
+        count (int): The maximum number of elements to include in the range.
+            A negative count returns all elements from the offset.
+
+    Examples:
+        >>> limit = Limit(0, 10)  # Fetch the first 10 elements
+        >>> limit = Limit(5, -1)  # Fetch all elements starting from the 5th element
+    """
+
+    def __init__(self, offset: int, count: int):
+        self.offset = offset
+        self.count = count
+
+
+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.
+
+    """
+
+    ASC = "ASC"
+    """
+    ASC: Sort in ascending order.
+    """
+
+    DESC = "DESC"
+    """
+    DESC: Sort in descending order.
+    """
+
+
+class ListDirection(Enum):
+    """
+    Enumeration representing element popping or adding direction for List commands.
+    """
+
+    LEFT = "LEFT"
+    """
+    LEFT: Represents the option that elements should be popped from or added to the left side of a list.
+    """
+
+    RIGHT = "RIGHT"
+    """
+    RIGHT: Represents the option that elements should be popped from or added to the right side of a list.
+    """
+
+
+class ObjectType(Enum):
+    """
+    Enumeration representing the data types supported by the database.
+    """
+
+    STRING = "String"
+    """
+    Represents a string data type.
+    """
+
+    LIST = "List"
+    """
+    Represents a list data type.
+    """
+
+    SET = "Set"
+    """
+    Represents a set data type.
+    """
+
+    ZSET = "ZSet"
+    """
+    Represents a sorted set data type.
+    """
+
+    HASH = "Hash"
+    """
+    Represents a hash data type.
+    """
+
+    STREAM = "Stream"
+    """
+    Represents a stream data type.
+    """