valkey-glide 1.3.5rc3__cp313-cp313-macosx_11_0_arm64.whl → 2.0.0rc6__cp313-cp313-macosx_11_0_arm64.whl

glide/config.py

@@ -15,14 +15,15 @@ from glide.protobuf.connection_request_pb2 import TlsMode
 
 
 class NodeAddress:
-    def __init__(self, host: str = "localhost", port: int = 6379):
-        """
-        Represents the address and port of a node in the cluster.
+    """
+    Represents the address and port of a node in the cluster.
 
-        Args:
-            host (str, optional): The server host. Defaults to "localhost".
-            port (int, optional): The server port. Defaults to 6379.
-        """
+    Attributes:
+        host (str, optional): The server host. Defaults to "localhost".
+        port (int, optional): The server port. Defaults to 6379.
+    """
+
+    def __init__(self, host: str = "localhost", port: int = 6379):
         self.host = host
         self.port = port
 
@@ -69,52 +70,64 @@ class ProtocolVersion(Enum):
 
 
 class BackoffStrategy:
-    def __init__(self, num_of_retries: int, factor: int, exponent_base: int):
-        """
-        Represents the strategy used to determine how and when to reconnect, in case of connection failures.
-        The time between attempts grows exponentially, to the formula rand(0 .. factor * (exponentBase ^ N)), where N
-        is the number of failed attempts.
-        Once the maximum value is reached, that will remain the time between retry attempts until a reconnect attempt is succesful.
-        The client will attempt to reconnect indefinitely.
+    """
+    Represents the strategy used to determine how and when to reconnect, in case of connection failures.
+    The time between attempts grows exponentially, to the formula rand(0 .. factor * (exponentBase ^ N)), where N
+    is the number of failed attempts.
+    Once the maximum value is reached, that will remain the time between retry attempts until a reconnect attempt is
+    successful.
+    The client will attempt to reconnect indefinitely.
 
-        Args:
-            num_of_retries (int): Number of retry attempts that the client should perform when disconnected from the server,
-                where the time between retries increases. Once the retries have reached the maximum value, the time between
-                retries will remain constant until a reconnect attempt is succesful.
-            factor (int): The multiplier that will be applied to the waiting time between each retry.
-            exponent_base (int): The exponent base configured for the strategy.
-        """
+    Attributes:
+        num_of_retries (int): Number of retry attempts that the client should perform when disconnected from the server,
+            where the time between retries increases. Once the retries have reached the maximum value, the time between
+            retries will remain constant until a reconnect attempt is succesful.
+        factor (int): The multiplier that will be applied to the waiting time between each retry.
+        exponent_base (int): The exponent base configured for the strategy.
+        jitter_percent (Optional[int]): The Jitter percent on the calculated duration. If not set, a default value will be used.
+    """
+
+    def __init__(
+        self,
+        num_of_retries: int,
+        factor: int,
+        exponent_base: int,
+        jitter_percent: Optional[int] = None,
+    ):
         self.num_of_retries = num_of_retries
         self.factor = factor
         self.exponent_base = exponent_base
+        self.jitter_percent = jitter_percent
 
 
 class ServerCredentials:
+    """
+    Represents the credentials for connecting to a server.
+
+    Attributes:
+        password (str): The password that will be used for authenticating connections to the servers.
+        username (Optional[str]): The username that will be used for authenticating connections to the servers.
+            If not supplied, "default" will be used.
+    """
+
     def __init__(
         self,
         password: str,
         username: Optional[str] = None,
     ):
-        """
-        Represents the credentials for connecting to a server.
-
-        Args:
-            password (str): The password that will be used for authenticating connections to the servers.
-            username (Optional[str]): The username that will be used for authenticating connections to the servers.
-                If not supplied, "default" will be used.
-        """
         self.password = password
         self.username = username
 
 
 class PeriodicChecksManualInterval:
-    def __init__(self, duration_in_sec: int) -> None:
-        """
-        Represents a manually configured interval for periodic checks.
+    """
+    Represents a manually configured interval for periodic checks.
 
-        Args:
-            duration_in_sec (int): The duration in seconds for the interval between periodic checks.
-        """
+    Attributes:
+        duration_in_sec (int): The duration in seconds for the interval between periodic checks.
+    """
+
+    def __init__(self, duration_in_sec: int) -> None:
         self.duration_in_sec = duration_in_sec
 
 
@@ -138,7 +151,7 @@ class AdvancedBaseClientConfiguration:
     """
     Represents the advanced configuration settings for a base Glide client.
 
-    Args:
+    Attributes:
         connection_timeout (Optional[int]): The duration in milliseconds to wait for a TCP/TLS connection to complete.
             This applies both during initial client creation and any reconnections that may occur during request processing.
             **Note**: A high connection timeout may lead to prolonged blocking of the entire command pipeline.
@@ -157,6 +170,52 @@ class AdvancedBaseClientConfiguration:
 
 
 class BaseClientConfiguration:
+    """
+    Represents the configuration settings for a Glide client.
+
+    Attributes:
+        addresses (List[NodeAddress]): DNS Addresses and ports of known nodes in the cluster.
+            If the server is in cluster mode the list can be partial, as the client will attempt to map out
+            the cluster and find all nodes.
+            If the server is in standalone mode, only nodes whose addresses were provided will be used by the
+            client.
+            For example::
+
+                [
+                    {address:sample-address-0001.use1.cache.amazonaws.com, port:6379},
+                    {address: sample-address-0002.use2.cache.amazonaws.com, port:6379}
+                ].
+
+        use_tls (bool): True if communication with the cluster should use Transport Level Security.
+            Should match the TLS configuration of the server/cluster, otherwise the connection attempt will fail
+        credentials (ServerCredentials): Credentials for authentication process.
+            If none are set, the client will not authenticate itself with the server.
+        read_from (ReadFrom): If not set, `PRIMARY` will be used.
+        request_timeout (Optional[int]): The duration in milliseconds that the client should wait for a request to
+            complete.
+            This duration encompasses sending the request, awaiting for 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, a default value of 250 milliseconds will be used.
+        reconnect_strategy (Optional[BackoffStrategy]): Strategy used to determine how and when to reconnect, in case of
+            connection failures.
+            If not set, a default backoff strategy will be used.
+        client_name (Optional[str]): Client name to be used for the client. Will be used with CLIENT SETNAME command
+            during connection establishment.
+        protocol (ProtocolVersion): Serialization protocol to be used. If not set, `RESP3` will be used.
+        inflight_requests_limit (Optional[int]): The maximum number of concurrent requests allowed to be in-flight
+            (sent but not yet completed).
+            This limit is used to control the memory usage and prevent the client from overwhelming the server or getting
+            stuck in case of a queue backlog.
+            If not set, a default value will be used.
+        client_az (Optional[str]): Availability Zone of the client.
+            If ReadFrom strategy is AZAffinity, this setting ensures that readonly commands are directed to replicas
+            within the specified AZ if exits.
+            If ReadFrom strategy is AZAffinityReplicasAndPrimary, this setting ensures that readonly commands are directed
+            to nodes (first replicas then primary) within the specified AZ if they exist.
+        advanced_config (Optional[AdvancedBaseClientConfiguration]): Advanced configuration settings for the client.
+    """
+
     def __init__(
         self,
         addresses: List[NodeAddress],
@@ -164,49 +223,19 @@ class BaseClientConfiguration:
         credentials: Optional[ServerCredentials] = None,
         read_from: ReadFrom = ReadFrom.PRIMARY,
         request_timeout: Optional[int] = None,
+        reconnect_strategy: Optional[BackoffStrategy] = None,
         client_name: Optional[str] = None,
         protocol: ProtocolVersion = ProtocolVersion.RESP3,
         inflight_requests_limit: Optional[int] = None,
         client_az: Optional[str] = None,
         advanced_config: Optional[AdvancedBaseClientConfiguration] = None,
     ):
-        """
-        Represents the configuration settings for a Glide client.
-
-        Args:
-            addresses (List[NodeAddress]): DNS Addresses and ports of known nodes in the cluster.
-                    If the server is in cluster mode the list can be partial, as the client will attempt to map out
-                    the cluster and find all nodes.
-                    If the server is in standalone mode, only nodes whose addresses were provided will be used by the
-                    client.
-                    For example:
-                    [
-                        {address:sample-address-0001.use1.cache.amazonaws.com, port:6379},
-                        {address: sample-address-0002.use2.cache.amazonaws.com, port:6379}
-                    ].
-            use_tls (bool): True if communication with the cluster should use Transport Level Security.
-                Should match the TLS configuration of the server/cluster, otherwise the connection attempt will fail
-            credentials (ServerCredentials): Credentials for authentication process.
-                    If none are set, the client will not authenticate itself with the server.
-            read_from (ReadFrom): If not set, `PRIMARY` will be used.
-            request_timeout (Optional[int]): The duration in milliseconds that the client should wait for a request to complete.
-                This duration encompasses sending the request, awaiting for 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, a default value of 250 milliseconds will be used.
-            client_name (Optional[str]): Client name to be used for the client. Will be used with CLIENT SETNAME command during connection establishment.
-            protocol (ProtocolVersion): Serialization protocol to be used. If not set, `RESP3` will be used.
-            inflight_requests_limit (Optional[int]): The maximum number of concurrent requests allowed to be in-flight (sent but not yet completed).
-                This limit is used to control the memory usage and prevent the client from overwhelming the server or getting stuck in case of a queue backlog.
-                If not set, a default value will be used.
-            client_az (Optional[str]): Availability Zone of the client.
-                If ReadFrom strategy is AZAffinity, this setting ensures that readonly commands are directed to replicas within the specified AZ if exits.
-                If ReadFrom strategy is AZAffinityReplicasAndPrimary, this setting ensures that readonly commands are directed to nodes (first replicas then primary) within the specified AZ if they exist.
-            advanced_config (Optional[AdvancedBaseClientConfiguration]): Advanced configuration settings for the client.
-        """
         self.addresses = addresses
         self.use_tls = use_tls
         self.credentials = credentials
         self.read_from = read_from
         self.request_timeout = request_timeout
+        self.reconnect_strategy = reconnect_strategy
         self.client_name = client_name
         self.protocol = protocol
         self.inflight_requests_limit = inflight_requests_limit
@@ -244,6 +273,19 @@ class BaseClientConfiguration:
         request.read_from = self.read_from.value
         if self.request_timeout:
             request.request_timeout = self.request_timeout
+        if self.reconnect_strategy:
+            request.connection_retry_strategy.number_of_retries = (
+                self.reconnect_strategy.num_of_retries
+            )
+            request.connection_retry_strategy.factor = self.reconnect_strategy.factor
+            request.connection_retry_strategy.exponent_base = (
+                self.reconnect_strategy.exponent_base
+            )
+            if self.reconnect_strategy.jitter_percent is not None:
+                request.connection_retry_strategy.jitter_percent = (
+                    self.reconnect_strategy.jitter_percent
+                )
+
         request.cluster_mode_enabled = True if cluster_mode else False
         if self.credentials:
             if self.credentials.username:
@@ -284,43 +326,53 @@ class GlideClientConfiguration(BaseClientConfiguration):
     """
     Represents the configuration settings for a Standalone Glide client.
 
-    Args:
+    Attributes:
         addresses (List[NodeAddress]): DNS Addresses and ports of known nodes in the cluster.
-                Only nodes whose addresses were provided will be used by the client.
-                For example:
+        Only nodes whose addresses were provided will be used by the client.
+            For example::
+
                 [
                     {address:sample-address-0001.use1.cache.amazonaws.com, port:6379},
                     {address: sample-address-0002.use2.cache.amazonaws.com, port:6379}
-                ].
+                ]
+
         use_tls (bool): True if communication with the cluster should use Transport Level Security.
         credentials (ServerCredentials): Credentials for authentication process.
                 If none are set, the client will not authenticate itself with the server.
         read_from (ReadFrom): If not set, `PRIMARY` will be used.
         request_timeout (Optional[int]):  The duration in milliseconds that the client should wait for a request to complete.
-                This duration encompasses sending the request, awaiting for a response from the server, and any required reconnections or retries.
+                This duration encompasses sending the request, awaiting for 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, a default value of 250 milliseconds will be used.
         reconnect_strategy (Optional[BackoffStrategy]): Strategy used to determine how and when to reconnect, in case of
             connection failures.
             If not set, a default backoff strategy will be used.
         database_id (Optional[int]): index of the logical database to connect to.
-        client_name (Optional[str]): Client name to be used for the client. Will be used with CLIENT SETNAME command during connection establishment.
+        client_name (Optional[str]): Client name to be used for the client. Will be used with CLIENT SETNAME command during
+            connection establishment.
         protocol (ProtocolVersion): The version of the RESP protocol to communicate with the server.
-        pubsub_subscriptions (Optional[GlideClientConfiguration.PubSubSubscriptions]): Pubsub subscriptions to be used for the client.
+        pubsub_subscriptions (Optional[GlideClientConfiguration.PubSubSubscriptions]): Pubsub subscriptions to be used for the
+                client.
                 Will be applied via SUBSCRIBE/PSUBSCRIBE commands during connection establishment.
-        inflight_requests_limit (Optional[int]): The maximum number of concurrent requests allowed to be in-flight (sent but not yet completed).
-            This limit is used to control the memory usage and prevent the client from overwhelming the server or getting stuck in case of a queue backlog.
+        inflight_requests_limit (Optional[int]): The maximum number of concurrent requests allowed to be in-flight
+            (sent but not yet completed).
+            This limit is used to control the memory usage and prevent the client from overwhelming the server or getting
+            stuck in case of a queue backlog.
             If not set, a default value will be used.
         client_az (Optional[str]): Availability Zone of the client.
-            If ReadFrom strategy is AZAffinity, this setting ensures that readonly commands are directed to replicas within the specified AZ if exits.
-            If ReadFrom strategy is AZAffinityReplicasAndPrimary, this setting ensures that readonly commands are directed to nodes (first replicas then primary) within the specified AZ if they exist.
-        advanced_config (Optional[AdvancedGlideClientConfiguration]): Advanced configuration settings for the client, see `AdvancedGlideClientConfiguration`.
+            If ReadFrom strategy is AZAffinity, this setting ensures that readonly commands are directed to replicas within
+            the specified AZ if exits.
+            If ReadFrom strategy is AZAffinityReplicasAndPrimary, this setting ensures that readonly commands are directed to
+            nodes (first replicas then primary) within the specified AZ if they exist.
+        advanced_config (Optional[AdvancedGlideClientConfiguration]): Advanced configuration settings for the client,
+            see `AdvancedGlideClientConfiguration`.
     """
 
     class PubSubChannelModes(IntEnum):
         """
         Describes pubsub subsciption modes.
-        See https://valkey.io/docs/topics/pubsub/ for more details
+        See [valkey.io](https://valkey.io/docs/topics/pubsub/) for more details
         """
 
         Exact = 0
@@ -369,13 +421,13 @@ class GlideClientConfiguration(BaseClientConfiguration):
             credentials=credentials,
             read_from=read_from,
             request_timeout=request_timeout,
+            reconnect_strategy=reconnect_strategy,
             client_name=client_name,
             protocol=protocol,
             inflight_requests_limit=inflight_requests_limit,
             client_az=client_az,
             advanced_config=advanced_config,
         )
-        self.reconnect_strategy = reconnect_strategy
         self.database_id = database_id
         self.pubsub_subscriptions = pubsub_subscriptions
 
@@ -384,14 +436,6 @@ class GlideClientConfiguration(BaseClientConfiguration):
     ) -> ConnectionRequest:
         assert cluster_mode is False
         request = super()._create_a_protobuf_conn_request(cluster_mode)
-        if self.reconnect_strategy:
-            request.connection_retry_strategy.number_of_retries = (
-                self.reconnect_strategy.num_of_retries
-            )
-            request.connection_retry_strategy.factor = self.reconnect_strategy.factor
-            request.connection_retry_strategy.exponent_base = (
-                self.reconnect_strategy.exponent_base
-            )
         if self.database_id:
             request.database_id = self.database_id
 
@@ -443,38 +487,52 @@ class GlideClusterClientConfiguration(BaseClientConfiguration):
     """
     Represents the configuration settings for a Cluster Glide client.
 
-    Args:
+    Attributes:
         addresses (List[NodeAddress]): DNS Addresses and ports of known nodes in the cluster.
-                The list can be partial, as the client will attempt to map out the cluster and find all nodes.
-                For example:
+            The list can be partial, as the client will attempt to map out the cluster and find all nodes.
+            For example::
+
                 [
                     {address:configuration-endpoint.use1.cache.amazonaws.com, port:6379}
-                ].
+                ]
+
         use_tls (bool): True if communication with the cluster should use Transport Level Security.
         credentials (ServerCredentials): Credentials for authentication process.
                 If none are set, the client will not authenticate itself with the server.
         read_from (ReadFrom): If not set, `PRIMARY` will be used.
         request_timeout (Optional[int]):  The duration in milliseconds that the client should wait for a request to complete.
-            This duration encompasses sending the request, awaiting for 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, a default value of 250 milliseconds will be used.
-        client_name (Optional[str]): Client name to be used for the client. Will be used with CLIENT SETNAME command during connection establishment.
+            This duration encompasses sending the request, awaiting for 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, a default value of 250 milliseconds will be used.
+        reconnect_strategy (Optional[BackoffStrategy]): Strategy used to determine how and when to reconnect, in case of
+            connection failures.
+            If not set, a default backoff strategy will be used.
+        client_name (Optional[str]): Client name to be used for the client. Will be used with CLIENT SETNAME command during
+            connection establishment.
         protocol (ProtocolVersion): The version of the RESP protocol to communicate with the server.
         periodic_checks (Union[PeriodicChecksStatus, PeriodicChecksManualInterval]): Configure the periodic topology checks.
             These checks evaluate changes in the cluster's topology, triggering a slot refresh when detected.
             Periodic checks ensure a quick and efficient process by querying a limited number of nodes.
             Defaults to PeriodicChecksStatus.ENABLED_DEFAULT_CONFIGS.
-        pubsub_subscriptions (Optional[GlideClusterClientConfiguration.PubSubSubscriptions]): Pubsub subscriptions to be used for the client.
+        pubsub_subscriptions (Optional[GlideClusterClientConfiguration.PubSubSubscriptions]): Pubsub subscriptions to be used
+            for the client.
             Will be applied via SUBSCRIBE/PSUBSCRIBE/SSUBSCRIBE commands during connection establishment.
-        inflight_requests_limit (Optional[int]): The maximum number of concurrent requests allowed to be in-flight (sent but not yet completed).
-            This limit is used to control the memory usage and prevent the client from overwhelming the server or getting stuck in case of a queue backlog.
+        inflight_requests_limit (Optional[int]): The maximum number of concurrent requests allowed to be in-flight
+            (sent but not yet completed).
+            This limit is used to control the memory usage and prevent the client from overwhelming the server or getting
+            stuck in case of a queue backlog.
             If not set, a default value will be used.
         client_az (Optional[str]): Availability Zone of the client.
-            If ReadFrom strategy is AZAffinity, this setting ensures that readonly commands are directed to replicas within the specified AZ if exits.
-            If ReadFrom strategy is AZAffinityReplicasAndPrimary, this setting ensures that readonly commands are directed to nodes (first replicas then primary) within the specified AZ if they exist.
-        advanced_config (Optional[AdvancedGlideClusterClientConfiguration]) : Advanced configuration settings for the client, see `AdvancedGlideClusterClientConfiguration`.
+            If ReadFrom strategy is AZAffinity, this setting ensures that readonly commands are directed to replicas within
+            the specified AZ if exits.
+            If ReadFrom strategy is AZAffinityReplicasAndPrimary, this setting ensures that readonly commands are directed to
+            nodes (first replicas then primary) within the specified AZ if they exist.
+        advanced_config (Optional[AdvancedGlideClusterClientConfiguration]) : Advanced configuration settings for the client,
+            see `AdvancedGlideClusterClientConfiguration`.
 
 
-    Notes:
+    Note:
         Currently, the reconnection strategy in cluster mode is not configurable, and exponential backoff
         with fixed values is used.
     """
@@ -482,7 +540,7 @@ class GlideClusterClientConfiguration(BaseClientConfiguration):
     class PubSubChannelModes(IntEnum):
         """
         Describes pubsub subsciption modes.
-        See https://valkey.io/docs/topics/pubsub/ for more details
+        See [valkey.io](https://valkey.io/docs/topics/pubsub/) for more details
         """
 
         Exact = 0
@@ -518,6 +576,7 @@ class GlideClusterClientConfiguration(BaseClientConfiguration):
         credentials: Optional[ServerCredentials] = None,
         read_from: ReadFrom = ReadFrom.PRIMARY,
         request_timeout: Optional[int] = None,
+        reconnect_strategy: Optional[BackoffStrategy] = None,
         client_name: Optional[str] = None,
         protocol: ProtocolVersion = ProtocolVersion.RESP3,
         periodic_checks: Union[
@@ -534,6 +593,7 @@ class GlideClusterClientConfiguration(BaseClientConfiguration):
             credentials=credentials,
             read_from=read_from,
             request_timeout=request_timeout,
+            reconnect_strategy=reconnect_strategy,
             client_name=client_name,
             protocol=protocol,
             inflight_requests_limit=inflight_requests_limit,

glide/constants.py

@@ -34,7 +34,8 @@ TSingleNodeRoute = Union[RandomNode, SlotKeyRoute, SlotIdRoute, ByAddressRoute]
 # When specifying legacy path (path doesn't start with `$`), response will be T
 # Otherwise, (when specifying JSONPath), response will be List[Optional[T]].
 #
-# TJsonResponse is designed to handle scenarios where some paths may not contain valid values, especially with JSONPath targeting multiple paths.
+# TJsonResponse is designed to handle scenarios where some paths may not contain valid values, especially with JSONPath
+# targeting multiple paths.
 # In such cases, the response may include None values, represented as `Optional[T]` in the list.
 # This type provides flexibility for commands where a subset of the paths may return None.
 #
@@ -44,13 +45,15 @@ TJsonResponse = Union[T, List[Optional[T]]]
 # When specifying legacy path (path doesn't start with `$`), response will be T
 # Otherwise, (when specifying JSONPath), response will be List[T].
 # This type represents the response format for commands that apply to every path and every type in a JSON document.
-# It covers both singular and multiple paths, ensuring that the command returns valid results for each matched path without None values.
+# It covers both singular and multiple paths, ensuring that the command returns valid results for each matched path
+# without None values.
 #
 # TJsonUniversalResponse is considered "universal" because it applies to every matched path and
 # guarantees valid, non-null results across all paths, covering both singular and multiple paths.
 # This type is used for commands that return results from all matched paths, ensuring that each
 # path contains meaningful values without None entries (unless it's part of the commands response).
-# It is typically used in scenarios where each target is expected to yield a valid response. For commands that are valid for all target types.
+# It is typically used in scenarios where each target is expected to yield a valid response. For commands that are valid
+# for all target types.
 #
 # For more information, see: https://redis.io/docs/data-types/json/path/ .
 TJsonUniversalResponse = Union[T, List[T]]
@@ -62,7 +65,8 @@ TFunctionListResponse = List[
     ]
 ]
 # Response for function stats command on a single node.
-# The response holds a map with 2 keys: Current running function / script and information about it, and the engines and the information about it.
+# The response holds a map with 2 keys: Current running function / script and information about it, and the engines and
+# the information about it.
 TFunctionStatsSingleNodeResponse = Mapping[
     bytes,
     Union[