valkey-glide 2.0.0rc3__cp310-cp310-macosx_11_0_arm64.whl → 2.2.1rc3__cp310-cp310-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_shared/commands/core_options.py

@@ -0,0 +1,407 @@
+# Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import List, Optional, Type, Union, get_args
+
+from glide_shared.commands.command_args import Limit, OrderBy
+from glide_shared.constants import TEncodable
+
+
+@dataclass
+class PubSubMsg:
+    """
+    Describes the incoming pubsub message
+
+    Attributes:
+        message (TEncodable): Incoming message.
+        channel (TEncodable): Name of an channel that triggered the message.
+        pattern (Optional[TEncodable]): Pattern that triggered the message.
+    """
+
+    message: TEncodable
+    channel: TEncodable
+    pattern: Optional[TEncodable]
+
+
+class ConditionalChange(Enum):
+    """
+    A condition to the `SET`, `ZADD` and `GEOADD` commands.
+    """
+
+    ONLY_IF_EXISTS = "XX"
+    """ Only update key / elements that already exist. Equivalent to `XX` in the Valkey API. """
+
+    ONLY_IF_DOES_NOT_EXIST = "NX"
+    """ Only set key / add elements that does not already exist. Equivalent to `NX` in the Valkey API. """
+
+
+class HashFieldConditionalChange(Enum):
+    """
+    Field conditional change options for HSETEX command.
+    """
+
+    ONLY_IF_ALL_EXIST = "FXX"
+    """ Only set fields if all of them already exist. Equivalent to `FXX` in the Valkey API. """
+
+    ONLY_IF_NONE_EXIST = "FNX"
+    """ Only set fields if none of them already exist. Equivalent to `FNX` in the Valkey API. """
+
+
+@dataclass
+class OnlyIfEqual:
+    """
+    Change condition to the `SET` command,
+    For additional conditonal options see ConditionalChange
+
+    - comparison_value - value to compare to the current value of a key.
+
+    If comparison_value is equal to the key, it will overwrite the value of key to the new provided value
+    Equivalent to the IFEQ comparison-value in the Valkey API
+    """
+
+    comparison_value: TEncodable
+
+
+class ExpiryType(Enum):
+    """
+    SET option: The type of the expiry.
+    """
+
+    SEC = 0, Union[int, timedelta]
+    """
+    Set the specified expire time, in seconds. Equivalent to `EX` in the Valkey API.
+    """
+
+    MILLSEC = 1, Union[int, timedelta]
+    """
+    Set the specified expire time, in milliseconds. Equivalent to `PX` in the Valkey API.
+    """
+
+    UNIX_SEC = 2, Union[int, datetime]
+    """
+    Set the specified Unix time at which the key will expire, in seconds. Equivalent to `EXAT` in the Valkey API.
+    """
+
+    UNIX_MILLSEC = 3, Union[int, datetime]
+    """
+    Set the specified Unix time at which the key will expire, in milliseconds. Equivalent to `PXAT` in the Valkey API.
+    """
+
+    KEEP_TTL = 4, Type[None]
+    """
+    Retain the time to live associated with the key. Equivalent to `KEEPTTL` in the Valkey API.
+    """
+
+
+class ExpiryTypeGetEx(Enum):
+    """
+    GetEx option: The type of the expiry.
+    """
+
+    SEC = 0, Union[int, timedelta]
+    """ Set the specified expire time, in seconds. Equivalent to `EX` in the Valkey API. """
+
+    MILLSEC = 1, Union[int, timedelta]
+    """ Set the specified expire time, in milliseconds. Equivalent to `PX` in the Valkey API. """
+
+    UNIX_SEC = 2, Union[int, datetime]
+    """ Set the specified Unix time at which the key will expire, in seconds. Equivalent to `EXAT` in the Valkey API. """
+
+    UNIX_MILLSEC = 3, Union[int, datetime]
+    """ Set the specified Unix time at which the key will expire, in milliseconds. Equivalent to `PXAT` in the Valkey API. """
+
+    PERSIST = 4, Type[None]
+    """ Remove the time to live associated with the key. Equivalent to `PERSIST` in the Valkey API. """
+
+
+class InfoSection(Enum):
+    """
+    INFO option: a specific section of information:
+
+    When no parameter is provided, the default option is assumed.
+    """
+
+    SERVER = "server"
+    """ General information about the server """
+
+    CLIENTS = "clients"
+    """ Client connections section """
+
+    MEMORY = "memory"
+    """ Memory consumption related information """
+
+    PERSISTENCE = "persistence"
+    """ RDB and AOF related information """
+
+    STATS = "stats"
+    """ General statistics """
+
+    REPLICATION = "replication"
+    """ Master/replica replication information """
+
+    CPU = "cpu"
+    """ CPU consumption statistics """
+
+    COMMAND_STATS = "commandstats"
+    """ Valkey command statistics """
+
+    LATENCY_STATS = "latencystats"
+    """ Valkey command latency percentile distribution statistics """
+
+    SENTINEL = "sentinel"
+    """ Valkey Sentinel section (only applicable to Sentinel instances) """
+
+    CLUSTER = "cluster"
+    """ Valkey Cluster section """
+
+    MODULES = "modules"
+    """ Modules section """
+
+    KEYSPACE = "keyspace"
+    """ Database related statistics """
+
+    ERROR_STATS = "errorstats"
+    """ Valkey error statistics """
+
+    ALL = "all"
+    """ Return all sections (excluding module generated ones) """
+
+    DEFAULT = "default"
+    """ Return only the default set of sections """
+
+    EVERYTHING = "everything"
+    """ Includes all and modules """
+
+
+class ExpireOptions(Enum):
+    """
+    EXPIRE option: options for setting key expiry.
+    """
+
+    HasNoExpiry = "NX"
+    """ Set expiry only when the key has no expiry (Equivalent to "NX" in Valkey). """
+
+    HasExistingExpiry = "XX"
+    """ Set expiry only when the key has an existing expiry (Equivalent to "XX" in Valkey). """
+
+    NewExpiryGreaterThanCurrent = "GT"
+    """
+    Set expiry only when the new expiry is greater than the current one (Equivalent to "GT" in Valkey).
+    """
+
+    NewExpiryLessThanCurrent = "LT"
+    """
+    Set expiry only when the new expiry is less than the current one (Equivalent to "LT" in Valkey).
+    """
+
+
+class UpdateOptions(Enum):
+    """
+    Options for updating elements of a sorted set key.
+    """
+
+    LESS_THAN = "LT"
+    """ Only update existing elements if the new score is less than the current score. """
+
+    GREATER_THAN = "GT"
+    """ Only update existing elements if the new score is greater than the current score. """
+
+
+class ExpirySet:
+    """
+    SET option: Represents the expiry type and value to be executed with "SET" command.
+
+    Attributes:
+        cmd_arg (str): The expiry type.
+        value (str): The value for the expiry type.
+    """
+
+    def __init__(
+        self,
+        expiry_type: ExpiryType,
+        value: Optional[Union[int, datetime, timedelta]],
+    ) -> None:
+        self.set_expiry_type_and_value(expiry_type, value)
+
+    def __eq__(self, other: "object") -> bool:
+        if not isinstance(other, ExpirySet):
+            return NotImplemented
+        return self.expiry_type == other.expiry_type and self.value == other.value
+
+    def set_expiry_type_and_value(
+        self, expiry_type: ExpiryType, value: Optional[Union[int, datetime, timedelta]]
+    ):
+        """
+        Args:
+            expiry_type (ExpiryType): The expiry type.
+            value (Optional[Union[int, datetime, timedelta]]): The value of the expiration type. The type of expiration
+                determines the type of expiration value:
+
+                    - SEC: Union[int, timedelta]
+                    - MILLSEC: Union[int, timedelta]
+                    - UNIX_SEC: Union[int, datetime]
+                    - UNIX_MILLSEC: Union[int, datetime]
+                    - KEEP_TTL: Type[None]
+        """
+        if not isinstance(value, get_args(expiry_type.value[1])):
+            raise ValueError(
+                f"The value of {expiry_type} should be of type {expiry_type.value[1]}"
+            )
+        self.expiry_type = expiry_type
+        if self.expiry_type == ExpiryType.SEC:
+            self.cmd_arg = "EX"
+            if isinstance(value, timedelta):
+                value = int(value.total_seconds())
+        elif self.expiry_type == ExpiryType.MILLSEC:
+            self.cmd_arg = "PX"
+            if isinstance(value, timedelta):
+                value = int(value.total_seconds() * 1000)
+        elif self.expiry_type == ExpiryType.UNIX_SEC:
+            self.cmd_arg = "EXAT"
+            if isinstance(value, datetime):
+                value = int(value.timestamp())
+        elif self.expiry_type == ExpiryType.UNIX_MILLSEC:
+            self.cmd_arg = "PXAT"
+            if isinstance(value, datetime):
+                value = int(value.timestamp() * 1000)
+        elif self.expiry_type == ExpiryType.KEEP_TTL:
+            self.cmd_arg = "KEEPTTL"
+        self.value = str(value) if value else None
+
+    def get_cmd_args(self) -> List[str]:
+        return [self.cmd_arg] if self.value is None else [self.cmd_arg, self.value]
+
+
+class ExpiryGetEx:
+    """
+    GetEx option: Represents the expiry type and value to be executed with "GetEx" command.
+
+    Attributes:
+        cmd_arg (str): The expiry type.
+        value (str): The value for the expiry type.
+    """
+
+    def __init__(
+        self,
+        expiry_type: ExpiryTypeGetEx,
+        value: Optional[Union[int, datetime, timedelta]],
+    ) -> None:
+        self.set_expiry_type_and_value(expiry_type, value)
+
+    def set_expiry_type_and_value(
+        self,
+        expiry_type: ExpiryTypeGetEx,
+        value: Optional[Union[int, datetime, timedelta]],
+    ):
+        """
+        Args:
+            expiry_type (ExpiryType): The expiry type.
+            value (Optional[Union[int, datetime, timedelta]]): The value of the expiration type. The type of expiration
+                determines the type of expiration value:
+
+                    - SEC: Union[int, timedelta]
+                    - MILLSEC: Union[int, timedelta]
+                    - UNIX_SEC: Union[int, datetime]
+                    - UNIX_MILLSEC: Union[int, datetime]
+                    - PERSIST: Type[None]
+        """
+        if not isinstance(value, get_args(expiry_type.value[1])):
+            raise ValueError(
+                f"The value of {expiry_type} should be of type {expiry_type.value[1]}"
+            )
+        self.expiry_type = expiry_type
+        if self.expiry_type == ExpiryTypeGetEx.SEC:
+            self.cmd_arg = "EX"
+            if isinstance(value, timedelta):
+                value = int(value.total_seconds())
+        elif self.expiry_type == ExpiryTypeGetEx.MILLSEC:
+            self.cmd_arg = "PX"
+            if isinstance(value, timedelta):
+                value = int(value.total_seconds() * 1000)
+        elif self.expiry_type == ExpiryTypeGetEx.UNIX_SEC:
+            self.cmd_arg = "EXAT"
+            if isinstance(value, datetime):
+                value = int(value.timestamp())
+        elif self.expiry_type == ExpiryTypeGetEx.UNIX_MILLSEC:
+            self.cmd_arg = "PXAT"
+            if isinstance(value, datetime):
+                value = int(value.timestamp() * 1000)
+        elif self.expiry_type == ExpiryTypeGetEx.PERSIST:
+            self.cmd_arg = "PERSIST"
+        self.value = str(value) if value else None
+
+    def get_cmd_args(self) -> List[str]:
+        return [self.cmd_arg] if self.value is None else [self.cmd_arg, self.value]
+
+
+class InsertPosition(Enum):
+    BEFORE = "BEFORE"
+    AFTER = "AFTER"
+
+
+class FlushMode(Enum):
+    """
+    Defines flushing mode for:
+
+    `FLUSHALL` command and `FUNCTION FLUSH` command.
+
+    See [FLUSHAL](https://valkey.io/commands/flushall/) and [FUNCTION-FLUSH](https://valkey.io/commands/function-flush/)
+    for details
+
+    SYNC was introduced in version 6.2.0.
+    """
+
+    ASYNC = "ASYNC"
+    SYNC = "SYNC"
+
+
+class FunctionRestorePolicy(Enum):
+    """
+    Options for the FUNCTION RESTORE command.
+    """
+
+    APPEND = "APPEND"
+    """ Appends the restored libraries to the existing libraries and aborts on collision. This is the default policy. """
+
+    FLUSH = "FLUSH"
+    """ Deletes all existing libraries before restoring the payload. """
+
+    REPLACE = "REPLACE"
+    """
+    Appends the restored libraries to the existing libraries, replacing any existing ones in case
+    of name collisions. Note that this policy doesn't prevent function name collisions, only libraries.
+    """
+
+
+def _build_sort_args(
+    key: TEncodable,
+    by_pattern: Optional[TEncodable] = None,
+    limit: Optional[Limit] = None,
+    get_patterns: Optional[List[TEncodable]] = None,
+    order: Optional[OrderBy] = None,
+    alpha: Optional[bool] = None,
+    store: Optional[TEncodable] = None,
+) -> List[TEncodable]:
+    args = [key]
+
+    if by_pattern:
+        args.extend(["BY", by_pattern])
+
+    if limit:
+        args.extend(["LIMIT", str(limit.offset), str(limit.count)])
+
+    if get_patterns:
+        for pattern in get_patterns:
+            args.extend(["GET", pattern])
+
+    if order:
+        args.append(order.value)
+
+    if alpha:
+        args.append("ALPHA")
+
+    if store:
+        args.extend(["STORE", store])
+
+    return args

{glide/async_commands → glide_shared/commands}/server_modules/ft_options/ft_aggregate_options.py

@@ -2,11 +2,11 @@
 from abc import ABC, abstractmethod
 from typing import List, Mapping, Optional
 
-from glide.async_commands.command_args import OrderBy
-from glide.async_commands.server_modules.ft_options.ft_constants import (
+from glide_shared.commands.command_args import OrderBy
+from glide_shared.commands.server_modules.ft_options.ft_constants import (
     FtAggregateKeywords,
 )
-from glide.constants import TEncodable
+from glide_shared.constants import TEncodable
 
 
 class FtAggregateClause(ABC):

{glide/async_commands → glide_shared/commands}/server_modules/ft_options/ft_create_options.py

@@ -3,8 +3,10 @@ from abc import ABC, abstractmethod
 from enum import Enum
 from typing import List, Optional
 
-from glide.async_commands.server_modules.ft_options.ft_constants import FtCreateKeywords
-from glide.constants import TEncodable
+from glide_shared.commands.server_modules.ft_options.ft_constants import (
+    FtCreateKeywords,
+)
+from glide_shared.constants import TEncodable
 
 
 class FieldType(Enum):