valkey-glide 2.0.0rc7__cp312-cp312-macosx_10_7_x86_64.whl → 2.1.0rc1__cp312-cp312-macosx_10_7_x86_64.whl

glide/__init__.py

@@ -1,13 +1,24 @@
 # Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
 
-from glide.async_commands.batch import (
-    Batch,
-    ClusterBatch,
-    ClusterTransaction,
-    TBatch,
-    Transaction,
+from glide.glide import (
+    ClusterScanCursor,
+    OpenTelemetryConfig,
+    OpenTelemetryMetricsConfig,
+    OpenTelemetryTracesConfig,
+    Script,
 )
-from glide.async_commands.bitmap import (
+from glide_shared import (
+    OK,
+    TOK,
+    AdvancedGlideClientConfiguration,
+    AdvancedGlideClusterClientConfiguration,
+    AggregationType,
+    AllNodes,
+    AllPrimaries,
+    BackoffStrategy,
+    Batch,
+    BatchOptions,
+    BatchRetryStrategy,
     BitEncoding,
     BitFieldGet,
     BitFieldIncrBy,
@@ -20,28 +31,26 @@ from glide.async_commands.bitmap import (
     BitOffsetMultiplier,
     BitOverflowControl,
     BitwiseOperation,
-    OffsetOptions,
-    SignedEncoding,
-    UnsignedEncoding,
-)
-from glide.async_commands.command_args import Limit, ListDirection, ObjectType, OrderBy
-from glide.async_commands.core import (
+    ByAddressRoute,
+    ClosingError,
+    ClusterBatch,
+    ClusterBatchOptions,
+    ClusterTransaction,
     ConditionalChange,
-    CoreCommands,
+    ConfigurationError,
+    ConnectionError,
+    DataType,
+    DistanceMetricType,
+    ExclusiveIdBound,
+    ExecAbortError,
     ExpireOptions,
     ExpiryGetEx,
     ExpirySet,
     ExpiryType,
     ExpiryTypeGetEx,
+    Field,
+    FieldType,
     FlushMode,
-    FunctionRestorePolicy,
-    InfoSection,
-    InsertPosition,
-    OnlyIfEqual,
-    UpdateOptions,
-)
-from glide.async_commands.server_modules import ft, glide_json, json_batch
-from glide.async_commands.server_modules.ft_options.ft_aggregate_options import (
     FtAggregateApply,
     FtAggregateClause,
     FtAggregateFilter,
@@ -49,59 +58,64 @@ from glide.async_commands.server_modules.ft_options.ft_aggregate_options import
     FtAggregateLimit,
     FtAggregateOptions,
     FtAggregateReducer,
+    FtAggregateResponse,
     FtAggregateSortBy,
     FtAggregateSortProperty,
-)
-from glide.async_commands.server_modules.ft_options.ft_create_options import (
-    DataType,
-    DistanceMetricType,
-    Field,
-    FieldType,
     FtCreateOptions,
-    NumericField,
-    TagField,
-    TextField,
-    VectorAlgorithm,
-    VectorField,
-    VectorFieldAttributes,
-    VectorFieldAttributesFlat,
-    VectorFieldAttributesHnsw,
-    VectorType,
-)
-from glide.async_commands.server_modules.ft_options.ft_profile_options import (
+    FtInfoResponse,
     FtProfileOptions,
-    QueryType,
-)
-from glide.async_commands.server_modules.ft_options.ft_search_options import (
+    FtProfileResponse,
     FtSearchLimit,
     FtSearchOptions,
-    ReturnField,
-)
-from glide.async_commands.server_modules.glide_json import (
-    JsonArrIndexOptions,
-    JsonArrPopOptions,
-    JsonGetOptions,
-)
-from glide.async_commands.sorted_set import (
-    AggregationType,
+    FtSearchResponse,
+    FunctionRestorePolicy,
     GeoSearchByBox,
     GeoSearchByRadius,
     GeoSearchCount,
     GeospatialData,
     GeoUnit,
+    GlideClientConfiguration,
+    GlideClusterClientConfiguration,
+    GlideError,
+    HashFieldConditionalChange,
+    IdBound,
     InfBound,
+    InfoSection,
+    InsertPosition,
+    JsonArrIndexOptions,
+    JsonArrPopOptions,
+    JsonGetOptions,
     LexBoundary,
+    Limit,
+    ListDirection,
+    MaxId,
+    MinId,
+    NodeAddress,
+    NumericField,
+    ObjectType,
+    OffsetOptions,
+    OnlyIfEqual,
+    OrderBy,
+    PeriodicChecksManualInterval,
+    PeriodicChecksStatus,
+    ProtocolVersion,
+    PubSubMsg,
+    QueryType,
+    RandomNode,
     RangeByIndex,
     RangeByLex,
     RangeByScore,
+    ReadFrom,
+    RequestError,
+    ReturnField,
+    Route,
     ScoreBoundary,
     ScoreFilter,
-)
-from glide.async_commands.stream import (
-    ExclusiveIdBound,
-    IdBound,
-    MaxId,
-    MinId,
+    ServerCredentials,
+    SignedEncoding,
+    SlotIdRoute,
+    SlotKeyRoute,
+    SlotType,
     StreamAddOptions,
     StreamClaimOptions,
     StreamGroupOptions,
@@ -110,78 +124,55 @@ from glide.async_commands.stream import (
     StreamReadGroupOptions,
     StreamReadOptions,
     StreamTrimOptions,
-    TrimByMaxLen,
-    TrimByMinId,
-)
-from glide.config import (
-    AdvancedGlideClientConfiguration,
-    AdvancedGlideClusterClientConfiguration,
-    BackoffStrategy,
-    GlideClientConfiguration,
-    GlideClusterClientConfiguration,
-    NodeAddress,
-    PeriodicChecksManualInterval,
-    PeriodicChecksStatus,
-    ProtocolVersion,
-    ReadFrom,
-    ServerCredentials,
-)
-from glide.constants import (
-    OK,
-    TOK,
-    FtAggregateResponse,
-    FtInfoResponse,
-    FtProfileResponse,
-    FtSearchResponse,
+    TagField,
+    TBatch,
     TClusterResponse,
     TEncodable,
+    TextField,
     TFunctionListResponse,
     TFunctionStatsFullResponse,
     TFunctionStatsSingleNodeResponse,
+    TimeoutError,
     TJsonResponse,
     TJsonUniversalResponse,
+    TlsAdvancedConfiguration,
+    Transaction,
     TResult,
+    TrimByMaxLen,
+    TrimByMinId,
     TSingleNodeRoute,
     TXInfoStreamFullResponse,
     TXInfoStreamResponse,
+    UnsignedEncoding,
+    UpdateOptions,
+    VectorAlgorithm,
+    VectorField,
+    VectorFieldAttributes,
+    VectorFieldAttributesFlat,
+    VectorFieldAttributesHnsw,
+    VectorType,
+    json_batch,
 )
-from glide.exceptions import (
-    ClosingError,
-    ConfigurationError,
-    ConnectionError,
-    ExecAbortError,
-    GlideError,
-    RequestError,
-    TimeoutError,
-)
-from glide.glide_client import GlideClient, GlideClusterClient, TGlideClient
-from glide.logger import Level as LogLevel
-from glide.logger import Logger
-from glide.routes import (
-    AllNodes,
-    AllPrimaries,
-    ByAddressRoute,
-    RandomNode,
-    Route,
-    SlotIdRoute,
-    SlotKeyRoute,
-    SlotType,
-)
-
-from .glide import ClusterScanCursor, Script
 
-PubSubMsg = CoreCommands.PubSubMsg
+from .async_commands import ft, glide_json
+from .glide_client import GlideClient, GlideClusterClient, TGlideClient
+from .logger import Level as LogLevel
+from .logger import Logger
 
 __all__ = [
     # Client
+    "TGlideClient",
     "GlideClient",
     "GlideClusterClient",
     "Batch",
     "ClusterBatch",
     "ClusterTransaction",
     "Transaction",
-    "TGlideClient",
     "TBatch",
+    # Batch Options
+    "BatchOptions",
+    "BatchRetryStrategy",
+    "ClusterBatchOptions",
     # Config
     "AdvancedGlideClientConfiguration",
     "AdvancedGlideClusterClientConfiguration",
@@ -191,9 +182,13 @@ __all__ = [
     "ReadFrom",
     "ServerCredentials",
     "NodeAddress",
+    "OpenTelemetryConfig",
+    "OpenTelemetryMetricsConfig",
+    "OpenTelemetryTracesConfig",
     "ProtocolVersion",
     "PeriodicChecksManualInterval",
     "PeriodicChecksStatus",
+    "TlsAdvancedConfiguration",
     # Response
     "OK",
     "TClusterResponse",
@@ -243,11 +238,11 @@ __all__ = [
     "GeoSearchCount",
     "GeoUnit",
     "GeospatialData",
+    "HashFieldConditionalChange",
     "AggregationType",
     "InfBound",
     "InfoSection",
     "InsertPosition",
-    "ft",
     "LexBoundary",
     "Limit",
     "ListDirection",
@@ -303,6 +298,7 @@ __all__ = [
     "RequestError",
     "TimeoutError",
     # Ft
+    "ft",
     "DataType",
     "DistanceMetricType",
     "Field",

glide/async_commands/cluster_commands.py

@@ -4,27 +4,28 @@ from __future__ import annotations
 
 from typing import Dict, List, Mapping, Optional, Union, cast
 
-from glide.async_commands.batch import ClusterBatch
-from glide.async_commands.command_args import ObjectType
-from glide.async_commands.core import (
-    CoreCommands,
+from glide.glide import ClusterScanCursor, Script
+from glide_shared.commands.batch import ClusterBatch
+from glide_shared.commands.batch_options import ClusterBatchOptions
+from glide_shared.commands.command_args import ObjectType
+from glide_shared.commands.core_options import (
     FlushMode,
     FunctionRestorePolicy,
     InfoSection,
 )
-from glide.constants import (
+from glide_shared.constants import (
     TOK,
     TClusterResponse,
     TEncodable,
     TFunctionListResponse,
     TFunctionStatsSingleNodeResponse,
     TResult,
-    TSingleNodeRoute,
 )
-from glide.protobuf.command_request_pb2 import RequestType
-from glide.routes import Route
+from glide_shared.exceptions import RequestError
+from glide_shared.protobuf.command_request_pb2 import RequestType
+from glide_shared.routes import Route
 
-from ..glide import ClusterScanCursor, Script
+from .core import CoreCommands
 
 
 class ClusterCommands(CoreCommands):
@@ -74,8 +75,8 @@ class ClusterCommands(CoreCommands):
         Args:
             sections (Optional[List[InfoSection]]): A list of InfoSection values specifying which sections of
                 information to retrieve. When no parameter is provided, the default option is assumed.
-            route (Optional[Route]): The command will be routed to all primaries, unless `route` is provided, in which
-                case the client will route the command to the nodes defined by `route`. Defaults to None.
+            route (Optional[Route]): The command will be routed to all primaries, unless `route` is provided, in
+                which case the client will route the command to the nodes defined by `route`. Defaults to None.
 
         Returns:
             TClusterResponse[bytes]: If a single node route is requested, returns a bytes string containing the information for
@@ -94,128 +95,109 @@ class ClusterCommands(CoreCommands):
         self,
         batch: ClusterBatch,
         raise_on_error: bool,
-        route: Optional[TSingleNodeRoute] = None,
-        timeout: Optional[int] = None,
-        retry_server_error: bool = False,
-        retry_connection_error: bool = False,
+        options: Optional[ClusterBatchOptions] = None,
     ) -> Optional[List[TResult]]:
         """
         Executes a batch by processing the queued commands.
 
-        See [Valkey Transactions (Atomic Batches)](https://valkey.io/docs/topics/transactions/) for details.
-        See [Valkey Pipelines (Non-Atomic Batches)](https://valkey.io/docs/topics/pipelining/) for details.
-
-        #### Routing Behavior:
-
-        - If a `route` is specified:
-            - The entire batch is sent to the specified node.
+        **Routing Behavior:**
 
+        - If a `route` is specified in `ClusterBatchOptions`, the entire batch is sent
+          to the specified node.
         - If no `route` is specified:
-            - Atomic batches (Transactions): Routed to the slot owner of the first key in the batch.
-              If no key is found, the request is sent to a random node.
-            - Non-atomic batches (Pipelines): Each command is routed to the node owning the corresponding
-              key's slot. If no key is present, routing follows the command's default request policy.
-              Multi-node commands are automatically split and dispatched to the appropriate nodes.
+            - **Atomic batches (Transactions):** Routed to the slot owner of the
+              first key in the batch. If no key is found, the request is sent to a random node.
+            - **Non-atomic batches (Pipelines):** Each command is routed to the node
+              owning the corresponding key's slot. If no key is present, routing follows the
+              command's request policy. Multi-node commands are automatically split and
+              dispatched to the appropriate nodes.
 
-        #### Behavior notes:
+        **Behavior notes:**
 
-        - Atomic Batches (Transactions): All key-based commands must map to the same hash slot.
-          If keys span different slots, the transaction will fail. If the transaction fails due to a
-          `WATCH` command, `exec` will return `None`.
+        - **Atomic Batches (Transactions):** All key-based commands must map to the
+          same hash slot. If keys span different slots, the transaction will fail. If the
+          transaction fails due to a `WATCH` command, `EXEC` will return `None`.
 
-        #### Retry and Redirection:
+        **Retry and Redirection:**
 
         - If a redirection error occurs:
-            - Atomic batches (Transactions): The entire transaction will be redirected.
-            - Non-atomic batches (Pipelines): Only commands that encountered redirection errors will be redirected.
-
-        - Retries for failures will be handled according to the `retry_server_error` and
-          `retry_connection_error` parameters.
+            - **Atomic batches (Transactions):** The entire transaction will be
+              redirected.
+            - **Non-atomic batches:** Only commands that encountered redirection
+              errors will be redirected.
+        - Retries for failures will be handled according to the configured `BatchRetryStrategy`.
 
         Args:
-            batch (ClusterBatch): A `ClusterBatch` object containing a list of commands to be executed.
-            raise_on_error (bool): Determines how errors are handled within the batch response. When set to
-                `True`, the first encountered error in the batch will be raised as a `RequestError`
-                exception after all retries and reconnections have been executed. When set to `False`,
-                errors will be included as part of the batch response array, allowing the caller to process both
-                successful and failed commands together. In this case, error details will be provided as
-                instances of `RequestError`.
-            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.
-            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, a timeout error will be raised. If not explicitly set,
-                the client's default request timeout will be used.
-            retry_server_error (bool): If `True`, retriable server errors (e.g., `TRYAGAIN`) will trigger a retry.
-                Warning: Retrying server errors may cause commands targeting the same slot to execute out of order.
-                Note: Currently supported only for non-atomic batches. Recommended to increase timeout when enabled.
-            retry_connection_error (bool): If `True`, connection failures will trigger a retry. Warning:
-                Retrying connection errors may lead to duplicate executions, as it is unclear which commands have
-                already been processed. Note: Currently supported only for non-atomic batches. Recommended to increase
-                timeout when enabled.
+            batch (ClusterBatch): A `ClusterBatch` containing the commands to execute.
+            raise_on_error (bool): Determines how errors are handled within the batch response.
+                When set to `True`, the first encountered error in the batch will be raised as an
+                exception of type `RequestError` after all retries and reconnections have been
+                executed.
+                When set to `False`, errors will be included as part of the batch response,
+                allowing the caller to process both successful and failed commands together. In this case,
+                error details will be provided as instances of `RequestError`.
+            options (Optional[ClusterBatchOptions]): A `ClusterBatchOptions` object containing execution options.
 
         Returns:
-            Optional[List[TResult]]: A list of results corresponding to the execution of each command in the batch.
-                If a command returns a value, it will be included in the list. If a command doesn't return a value,
-                the list entry will be `None`. If the batch failed due to a `WATCH` command, `exec` will return
-                `None`.
+            Optional[List[TResult]]: An array of results, where each entry
+                corresponds to a command's execution result.
 
-        Examples:
-            # Example 1: Atomic Batch (Transaction)
-            >>> atomic_batch = ClusterBatch(is_atomic=True)  # Atomic (Transaction)
-            >>> atomic_batch.set("key", "1")
-            >>> atomic_batch.incr("key")
-            >>> atomic_batch.get("key")
-            >>> atomic_result = await cluster_client.exec(atomic_batch, false)
-            >>> print(f"Atomic Batch Result: {atomic_result}")
-            # Expected Output: Atomic Batch Result: [OK, 2, 2]
+        See Also:
+            [Valkey Transactions (Atomic Batches)](https://valkey.io/docs/topics/transactions/)
+            [Valkey Pipelines (Non-Atomic Batches)](https://valkey.io/docs/topics/pipelining/)
 
-            # Example 2: Non-Atomic Batch (Pipeline)
-            >>> non_atomic_batch = ClusterBatch(is_atomic=False)  # Non-Atomic (Pipeline)
-            >>> non_atomic_batch.set("key1", "value1")
-            >>> non_atomic_batch.set("key2", "value2")
-            >>> non_atomic_batch.get("key1")
-            >>> non_atomic_batch.get("key2")
-            >>> non_atomic_result = await cluster_client.exec(non_atomic_batch, false)
-            >>> print(f"Non-Atomic Batch Result: {non_atomic_result}")
-            # Expected Output: Non-Atomic Batch Result: [OK, OK, value1, value2]
-
-            # Example 3: Atomic batch with options
+        Examples:
+            # Atomic batch (transaction): all keys must share the same hash slot
+            >>> options = ClusterBatchOptions(timeout=1000)  # Set a timeout of 1000 milliseconds
             >>> atomic_batch = ClusterBatch(is_atomic=True)
             >>> atomic_batch.set("key", "1")
             >>> atomic_batch.incr("key")
             >>> atomic_batch.get("key")
-            >>> atomic_result = await cluster_client.exec(
-            ...     atomic_batch,
-            ...     timeout=1000,  # Set a timeout of 1000 milliseconds
-            ...     raise_on_error=False  # Do not raise an error on failure
-            ... )
+            >>> atomic_result = await cluster_client.exec(atomic_batch, False, options)
             >>> print(f"Atomic Batch Result: {atomic_result}")
             # Output: Atomic Batch Result: [OK, 2, 2]
 
-            # Example 4: Non-atomic batch with retry options
+            # Non-atomic batch (pipeline): keys may span different hash slots
+            >>> retry_strategy = BatchRetryStrategy(retry_server_error=True, retry_connection_error=False)
+            >>> pipeline_options = ClusterBatchOptions(retry_strategy=retry_strategy)
             >>> non_atomic_batch = ClusterBatch(is_atomic=False)
             >>> non_atomic_batch.set("key1", "value1")
             >>> non_atomic_batch.set("key2", "value2")
             >>> non_atomic_batch.get("key1")
             >>> non_atomic_batch.get("key2")
-            >>> non_atomic_result = await cluster_client.exec(
-            ...     non_atomic_batch,
-            ...     raise_on_error=False,
-            ...     retry_server_error=True,
-            ...     retry_connection_error=False
-            ... )
+            >>> non_atomic_result = await cluster_client.exec(non_atomic_batch, False, pipeline_options)
             >>> print(f"Non-Atomic Batch Result: {non_atomic_result}")
             # Output: Non-Atomic Batch Result: [OK, OK, value1, value2]
         """
         commands = batch.commands[:]
+
+        if (
+            batch.is_atomic
+            and options
+            and options.retry_strategy
+            and (
+                options.retry_strategy.retry_server_error
+                or options.retry_strategy.retry_connection_error
+            )
+        ):
+            raise RequestError(
+                "Retry strategies are not supported for atomic batches (transactions). "
+            )
+
+        # Extract values to make the _execute_batch call cleaner
+        retry_server_error = (
+            options.retry_strategy.retry_server_error
+            if options and options.retry_strategy
+            else False
+        )
+        retry_connection_error = (
+            options.retry_strategy.retry_connection_error
+            if options and options.retry_strategy
+            else False
+        )
+        route = options.route if options else None
+        timeout = options.timeout if options else None
+
         return await self._execute_batch(
             commands,
             batch.is_atomic,
@@ -1439,7 +1421,7 @@ class ClusterCommands(CoreCommands):
 
         Examples:
             >>> lua_script = Script("return { KEYS[1], ARGV[1] }")
-            >>> await client.invoke_script(lua_script, keys=["foo"], args=["bar"] );
+            >>> await client.invoke_script(lua_script, keys=["foo"], args=["bar"])
                 [b"foo", b"bar"]
         """
         return await self._execute_script(script.get_hash(), keys, args)