valkey-glide 2.2.0rc1__cp312-cp312-macosx_10_7_x86_64.whl

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_shared/commands/server_modules/ft_options/ft_aggregate_options.py

@@ -0,0 +1,300 @@
+# Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+from abc import ABC, abstractmethod
+from typing import List, Mapping, Optional
+
+from glide_shared.commands.command_args import OrderBy
+from glide_shared.commands.server_modules.ft_options.ft_constants import (
+    FtAggregateKeywords,
+)
+from glide_shared.constants import TEncodable
+
+
+class FtAggregateClause(ABC):
+    """
+    Abstract base class for the FT.AGGREGATE command clauses.
+    """
+
+    @abstractmethod
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the clause of the FT.AGGREGATE command.
+
+        Returns:
+            List[TEncodable]: A list of arguments for the clause of the FT.AGGREGATE command.
+        """
+        args: List[TEncodable] = []
+        return args
+
+
+class FtAggregateLimit(FtAggregateClause):
+    """
+    A clause for limiting the number of retained records.
+    """
+
+    def __init__(self, offset: int, count: int):
+        """
+        Initialize a new FtAggregateLimit instance.
+
+        Args:
+            offset (int): Starting point from which the records have to be retained.
+            count (int): The total number of records to be retained.
+        """
+        self.offset = offset
+        self.count = count
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the Limit clause.
+
+        Returns:
+            List[TEncodable]: A list of Limit clause arguments.
+        """
+        return [FtAggregateKeywords.LIMIT, str(self.offset), str(self.count)]
+
+
+class FtAggregateFilter(FtAggregateClause):
+    """
+    A clause for filtering the results using predicate expression relating to values in each result. It is applied post query
+    and relate to the current state of the pipeline.
+    """
+
+    def __init__(self, expression: TEncodable):
+        """
+        Initialize a new FtAggregateFilter instance.
+
+        Args:
+            expression (TEncodable): The expression to filter the results.
+        """
+        self.expression = expression
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the Filter clause.
+
+        Returns:
+            List[TEncodable]: A list arguments for the filter clause.
+        """
+        return [FtAggregateKeywords.FILTER, self.expression]
+
+
+class FtAggregateReducer:
+    """
+    A clause for reducing the matching results in each group using a reduction function. The matching results are reduced into
+    a single record.
+    """
+
+    def __init__(
+        self,
+        function: TEncodable,
+        args: List[TEncodable],
+        name: Optional[TEncodable] = None,
+    ):
+        """
+        Initialize a new FtAggregateReducer instance.
+
+        Args:
+            function (TEncodable): The reduction function names for the respective group.
+            args (List[TEncodable]): The list of arguments for the reducer.
+            name (Optional[TEncodable]): User defined property name for the reducer.
+        """
+        self.function = function
+        self.args = args
+        self.name = name
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the Reducer.
+
+        Returns:
+            List[TEncodable]: A list of arguments for the reducer.
+        """
+        args: List[TEncodable] = [
+            FtAggregateKeywords.REDUCE,
+            self.function,
+            str(len(self.args)),
+        ] + self.args
+        if self.name:
+            args.extend([FtAggregateKeywords.AS, self.name])
+        return args
+
+
+class FtAggregateGroupBy(FtAggregateClause):
+    """
+    A clause for grouping the results in the pipeline based on one or more properties.
+    """
+
+    def __init__(
+        self, properties: List[TEncodable], reducers: List[FtAggregateReducer]
+    ):
+        """
+        Initialize a new FtAggregateGroupBy instance.
+
+        Args:
+            properties (List[TEncodable]): The list of properties to be used for grouping the results in the pipeline.
+            reducers (List[Reducer]): The list of functions that handles the group entries by performing multiple
+                aggregate operations.
+        """
+        self.properties = properties
+        self.reducers = reducers
+
+    def to_args(self) -> List[TEncodable]:
+        args = [
+            FtAggregateKeywords.GROUPBY,
+            str(len(self.properties)),
+        ] + self.properties
+        if self.reducers:
+            for reducer in self.reducers:
+                args.extend(reducer.to_args())
+        return args
+
+
+class FtAggregateSortProperty:
+    """
+    This class represents the a single property for the SortBy clause.
+    """
+
+    def __init__(self, property: TEncodable, order: OrderBy):
+        """
+        Initialize a new FtAggregateSortProperty instance.
+
+        Args:
+            property (TEncodable): The sorting parameter.
+            order (OrderBy): The order for the sorting. This option can be added for each property.
+        """
+        self.property = property
+        self.order = order
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the SortBy clause property.
+
+        Returns:
+            List[TEncodable]: A list of arguments for the SortBy clause property.
+        """
+        return [self.property, self.order.value]
+
+
+class FtAggregateSortBy(FtAggregateClause):
+    """
+    A clause for sorting the pipeline up until the point of SORTBY, using a list of properties.
+    """
+
+    def __init__(
+        self, properties: List[FtAggregateSortProperty], max: Optional[int] = None
+    ):
+        """
+        Initialize a new FtAggregateSortBy instance.
+
+        Args:
+            properties (List[FtAggregateSortProperty]): A list of sorting parameters for the sort operation.
+            max: (Optional[int]): The MAX value for optimizing the sorting, by sorting only for the n-largest elements.
+        """
+        self.properties = properties
+        self.max = max
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the SortBy clause.
+
+        Returns:
+            List[TEncodable]: A list of arguments for the SortBy clause.
+        """
+        args: List[TEncodable] = [
+            FtAggregateKeywords.SORTBY,
+            str(len(self.properties) * 2),
+        ]
+        for property in self.properties:
+            args.extend(property.to_args())
+        if self.max:
+            args.extend([FtAggregateKeywords.MAX, str(self.max)])
+        return args
+
+
+class FtAggregateApply(FtAggregateClause):
+    """
+    A clause for applying a 1-to-1 transformation on one or more properties and stores the result as a new property down the
+    pipeline or replaces any property using this transformation.
+    """
+
+    def __init__(self, expression: TEncodable, name: TEncodable):
+        """
+        Initialize a new FtAggregateApply instance.
+
+        Args:
+            expression (TEncodable): The expression to be transformed.
+            name (TEncodable): The new property name to store the result of apply. This name can be referenced by further
+                APPLY/SORTBY/GROUPBY/REDUCE operations down the pipeline.
+        """
+        self.expression = expression
+        self.name = name
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the Apply clause.
+
+        Returns:
+            List[TEncodable]: A list of arguments for the Apply clause.
+        """
+        return [
+            FtAggregateKeywords.APPLY,
+            self.expression,
+            FtAggregateKeywords.AS,
+            self.name,
+        ]
+
+
+class FtAggregateOptions:
+    """
+    This class represents the optional arguments for the FT.AGGREGATE command.
+    """
+
+    def __init__(
+        self,
+        loadAll: Optional[bool] = False,
+        loadFields: Optional[List[TEncodable]] = [],
+        timeout: Optional[int] = None,
+        params: Optional[Mapping[TEncodable, TEncodable]] = {},
+        clauses: Optional[List[FtAggregateClause]] = [],
+    ):
+        """
+        Initialize a new FtAggregateOptions instance.
+
+        Args:
+            loadAll (Optional[bool]): An option to load all fields declared in the index.
+            loadFields (Optional[List[TEncodable]]): An option to load only the fields passed in this list.
+            timeout (Optional[int]): Overrides the timeout parameter of the module.
+            params (Optional[Mapping[TEncodable, TEncodable]]): The key/value pairs can be referenced from within the
+                query expression.
+            clauses (Optional[List[FtAggregateClause]]): FILTER, LIMIT, GROUPBY, SORTBY and APPLY clauses, that can be
+                repeated multiple times in any order and be freely intermixed. They are applied in the order specified, with
+                the output of one clause feeding the input of the next clause.
+        """
+        self.loadAll = loadAll
+        self.loadFields = loadFields
+        self.timeout = timeout
+        self.params = params
+        self.clauses = clauses
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the optional arguments for the FT.AGGREGATE command.
+
+        Returns:
+            List[TEncodable]: A list of optional arguments for the FT.AGGREGATE command.
+        """
+        args: List[TEncodable] = []
+        if self.loadAll:
+            args.extend([FtAggregateKeywords.LOAD, "*"])
+        elif self.loadFields:
+            args.extend([FtAggregateKeywords.LOAD, str(len(self.loadFields))])
+            args.extend(self.loadFields)
+        if self.timeout:
+            args.extend([FtAggregateKeywords.TIMEOUT, str(self.timeout)])
+        if self.params:
+            args.extend([FtAggregateKeywords.PARAMS, str(len(self.params) * 2)])
+            for [name, value] in self.params.items():
+                args.extend([name, value])
+        if self.clauses:
+            for clause in self.clauses:
+                args.extend(clause.to_args())
+        return args