redis 5.3.0b5__py3-none-any.whl → 6.0.0b2__py3-none-any.whl

redis/connection.py

@@ -1,14 +1,13 @@
 import copy
 import os
 import socket
-import ssl
 import sys
 import threading
+import time
 import weakref
 from abc import abstractmethod
 from itertools import chain
 from queue import Empty, Full, LifoQueue
-from time import time
 from typing import Any, Callable, Dict, List, Optional, Type, TypeVar, Union
 from urllib.parse import parse_qs, unquote, urlparse
 
@@ -42,12 +41,18 @@ from .utils import (
     HIREDIS_AVAILABLE,
     SSL_AVAILABLE,
     compare_versions,
+    deprecated_args,
     ensure_string,
     format_error_message,
     get_lib_version,
     str_if_bytes,
 )
 
+if SSL_AVAILABLE:
+    import ssl
+else:
+    ssl = None
+
 if HIREDIS_AVAILABLE:
     import hiredis
 
@@ -371,6 +376,9 @@ class AbstractConnection(ConnectionInterface):
 
     def connect(self):
         "Connects to the Redis server if not already connected"
+        self.connect_check_health(check_health=True)
+
+    def connect_check_health(self, check_health: bool = True):
         if self._sock:
             return
         try:
@@ -386,7 +394,7 @@ class AbstractConnection(ConnectionInterface):
         try:
             if self.redis_connect_func is None:
                 # Use the default on_connect function
-                self.on_connect()
+                self.on_connect_check_health(check_health=check_health)
             else:
                 # Use the passed function redis_connect_func
                 self.redis_connect_func(self)
@@ -416,6 +424,9 @@ class AbstractConnection(ConnectionInterface):
         return format_error_message(self._host_error(), exception)
 
     def on_connect(self):
+        self.on_connect_check_health(check_health=True)
+
+    def on_connect_check_health(self, check_health: bool = True):
         "Initialize the connection, authenticate and select a database"
         self._parser.on_connect(self)
         parser = self._parser
@@ -439,7 +450,11 @@ class AbstractConnection(ConnectionInterface):
                 self._parser.on_connect(self)
             if len(auth_args) == 1:
                 auth_args = ["default", auth_args[0]]
-            self.send_command("HELLO", self.protocol, "AUTH", *auth_args)
+            # avoid checking health here -- PING will fail if we try
+            # to check the health prior to the AUTH
+            self.send_command(
+                "HELLO", self.protocol, "AUTH", *auth_args, check_health=False
+            )
             self.handshake_metadata = self.read_response()
             # if response.get(b"proto") != self.protocol and response.get(
             #     "proto"
@@ -470,7 +485,7 @@ class AbstractConnection(ConnectionInterface):
                 # update cluster exception classes
                 self._parser.EXCEPTION_CLASSES = parser.EXCEPTION_CLASSES
                 self._parser.on_connect(self)
-            self.send_command("HELLO", self.protocol)
+            self.send_command("HELLO", self.protocol, check_health=check_health)
             self.handshake_metadata = self.read_response()
             if (
                 self.handshake_metadata.get(b"proto") != self.protocol
@@ -480,28 +495,45 @@ class AbstractConnection(ConnectionInterface):
 
         # if a client_name is given, set it
         if self.client_name:
-            self.send_command("CLIENT", "SETNAME", self.client_name)
+            self.send_command(
+                "CLIENT",
+                "SETNAME",
+                self.client_name,
+                check_health=check_health,
+            )
             if str_if_bytes(self.read_response()) != "OK":
                 raise ConnectionError("Error setting client name")
 
         try:
             # set the library name and version
             if self.lib_name:
-                self.send_command("CLIENT", "SETINFO", "LIB-NAME", self.lib_name)
+                self.send_command(
+                    "CLIENT",
+                    "SETINFO",
+                    "LIB-NAME",
+                    self.lib_name,
+                    check_health=check_health,
+                )
                 self.read_response()
         except ResponseError:
             pass
 
         try:
             if self.lib_version:
-                self.send_command("CLIENT", "SETINFO", "LIB-VER", self.lib_version)
+                self.send_command(
+                    "CLIENT",
+                    "SETINFO",
+                    "LIB-VER",
+                    self.lib_version,
+                    check_health=check_health,
+                )
                 self.read_response()
         except ResponseError:
             pass
 
         # if a database is specified, switch to it
         if self.db:
-            self.send_command("SELECT", self.db)
+            self.send_command("SELECT", self.db, check_health=check_health)
             if str_if_bytes(self.read_response()) != "OK":
                 raise ConnectionError("Invalid Database")
 
@@ -537,13 +569,13 @@ class AbstractConnection(ConnectionInterface):
 
     def check_health(self):
         """Check the health of the connection with a PING/PONG"""
-        if self.health_check_interval and time() > self.next_health_check:
+        if self.health_check_interval and time.monotonic() > self.next_health_check:
             self.retry.call_with_retry(self._send_ping, self._ping_failed)
 
     def send_packed_command(self, command, check_health=True):
         """Send an already packed command to the Redis server"""
         if not self._sock:
-            self.connect()
+            self.connect_check_health(check_health=False)
         # guard against health check recursion
         if check_health:
             self.check_health()
@@ -617,9 +649,7 @@ class AbstractConnection(ConnectionInterface):
         except OSError as e:
             if disconnect_on_error:
                 self.disconnect()
-            raise ConnectionError(
-                f"Error while reading from {host_error}" f" : {e.args}"
-            )
+            raise ConnectionError(f"Error while reading from {host_error} : {e.args}")
         except BaseException:
             # Also by default close in case of BaseException.  A lot of code
             # relies on this behaviour when doing Command/Response pairs.
@@ -629,7 +659,7 @@ class AbstractConnection(ConnectionInterface):
             raise
 
         if self.health_check_interval:
-            self.next_health_check = time() + self.health_check_interval
+            self.next_health_check = time.monotonic() + self.health_check_interval
 
         if isinstance(response, ResponseError):
             try:
@@ -672,7 +702,7 @@ class AbstractConnection(ConnectionInterface):
             output.append(SYM_EMPTY.join(pieces))
         return output
 
-    def get_protocol(self) -> int or str:
+    def get_protocol(self) -> Union[int, str]:
         return self.protocol
 
     @property
@@ -757,6 +787,10 @@ class Connection(AbstractConnection):
             except OSError as _:
                 err = _
                 if sock is not None:
+                    try:
+                        sock.shutdown(socket.SHUT_RDWR)  # ensure a clean close
+                    except OSError:
+                        pass
                     sock.close()
 
         if err is not None:
@@ -1010,7 +1044,7 @@ class SSLConnection(Connection):
         Args:
             ssl_keyfile: Path to an ssl private key. Defaults to None.
             ssl_certfile: Path to an ssl certificate. Defaults to None.
-            ssl_cert_reqs: The string value for the SSLContext.verify_mode (none, optional, required). Defaults to "required".
+            ssl_cert_reqs: The string value for the SSLContext.verify_mode (none, optional, required), or an ssl.VerifyMode. Defaults to "required".
             ssl_ca_certs: The path to a file of concatenated CA certificates in PEM format. Defaults to None.
             ssl_ca_data: Either an ASCII string of one or more PEM-encoded certificates or a bytes-like object of DER-encoded certificates.
             ssl_check_hostname: If set, match the hostname during the SSL handshake. Defaults to False.
@@ -1035,7 +1069,7 @@ class SSLConnection(Connection):
         if ssl_cert_reqs is None:
             ssl_cert_reqs = ssl.CERT_NONE
         elif isinstance(ssl_cert_reqs, str):
-            CERT_REQS = {
+            CERT_REQS = {  # noqa: N806
                 "none": ssl.CERT_NONE,
                 "optional": ssl.CERT_OPTIONAL,
                 "required": ssl.CERT_REQUIRED,
@@ -1172,6 +1206,10 @@ class UnixDomainSocketConnection(AbstractConnection):
             sock.connect(self.path)
         except OSError:
             # Prevent ResourceWarnings for unclosed sockets.
+            try:
+                sock.shutdown(socket.SHUT_RDWR)  # ensure a clean close
+            except OSError:
+                pass
             sock.close()
             raise
         sock.settimeout(self.socket_timeout)
@@ -1461,8 +1499,14 @@ class ConnectionPool:
             finally:
                 self._fork_lock.release()
 
-    def get_connection(self, command_name: str, *keys, **options) -> "Connection":
+    @deprecated_args(
+        args_to_warn=["*"],
+        reason="Use get_connection() without args instead",
+        version="5.0.3",
+    )
+    def get_connection(self, command_name=None, *keys, **options) -> "Connection":
         "Get a connection from the pool"
+
         self._checkpid()
         with self._lock:
             try:
@@ -1481,7 +1525,7 @@ class ConnectionPool:
             try:
                 if connection.can_read() and self.cache is None:
                     raise ConnectionError("Connection has data")
-            except (ConnectionError, OSError):
+            except (ConnectionError, TimeoutError, OSError):
                 connection.disconnect()
                 connection.connect()
                 if connection.can_read():
@@ -1525,7 +1569,7 @@ class ConnectionPool:
             except KeyError:
                 # Gracefully fail when a connection is returned to this pool
                 # that the pool doesn't actually own
-                pass
+                return
 
             if self.owns_connection(connection):
                 self._available_connections.append(connection)
@@ -1533,10 +1577,10 @@ class ConnectionPool:
                     AfterConnectionReleasedEvent(connection)
                 )
             else:
-                # pool doesn't own this connection. do not add it back
-                # to the pool and decrement the count so that another
-                # connection can take its place if needed
-                self._created_connections -= 1
+                # Pool doesn't own this connection, do not add it back
+                # to the pool.
+                # The created connections count should not be changed,
+                # because the connection was not created by the pool.
                 connection.disconnect()
                 return
 
@@ -1683,7 +1727,12 @@ class BlockingConnectionPool(ConnectionPool):
         self._connections.append(connection)
         return connection
 
-    def get_connection(self, command_name, *keys, **options):
+    @deprecated_args(
+        args_to_warn=["*"],
+        reason="Use get_connection() without args instead",
+        version="5.0.3",
+    )
+    def get_connection(self, command_name=None, *keys, **options):
         """
         Get a connection, blocking for ``self.timeout`` until a connection
         is available from the pool.
@@ -1723,7 +1772,7 @@ class BlockingConnectionPool(ConnectionPool):
             try:
                 if connection.can_read():
                     raise ConnectionError("Connection has data")
-            except (ConnectionError, OSError):
+            except (ConnectionError, TimeoutError, OSError):
                 connection.disconnect()
                 connection.connect()
                 if connection.can_read():

redis/exceptions.py

@@ -79,6 +79,7 @@ class ModuleError(ResponseError):
 
 class LockError(RedisError, ValueError):
     "Errors acquiring or releasing a lock"
+
     # NOTE: For backwards compatibility, this class derives from ValueError.
     # This was originally chosen to behave like threading.Lock.
 
@@ -88,12 +89,14 @@ class LockError(RedisError, ValueError):
 
 
 class LockNotOwnedError(LockError):
-    "Error trying to extend or release a lock that is (no longer) owned"
+    "Error trying to extend or release a lock that is not owned (anymore)"
+
     pass
 
 
 class ChildDeadlockedError(Exception):
     "Error indicating that a child process is deadlocked after a fork()"
+
     pass
 
 

redis/lock.py

@@ -1,3 +1,4 @@
+import logging
 import threading
 import time as mod_time
 import uuid
@@ -7,6 +8,8 @@ from typing import Optional, Type
 from redis.exceptions import LockError, LockNotOwnedError
 from redis.typing import Number
 
+logger = logging.getLogger(__name__)
+
 
 class Lock:
     """
@@ -82,6 +85,7 @@ class Lock:
         blocking: bool = True,
         blocking_timeout: Optional[Number] = None,
         thread_local: bool = True,
+        raise_on_release_error: bool = True,
     ):
         """
         Create a new Lock instance named ``name`` using the Redis client
@@ -125,6 +129,11 @@ class Lock:
                      thread-1 would see the token value as "xyz" and would be
                      able to successfully release the thread-2's lock.
 
+        ``raise_on_release_error`` indicates whether to raise an exception when
+        the lock is no longer owned when exiting the context manager. By default,
+        this is True, meaning an exception will be raised. If False, the warning
+        will be logged and the exception will be suppressed.
+
         In some use cases it's necessary to disable thread local storage. For
         example, if you have code where one thread acquires a lock and passes
         that lock instance to a worker thread to release later. If thread
@@ -140,6 +149,7 @@ class Lock:
         self.blocking = blocking
         self.blocking_timeout = blocking_timeout
         self.thread_local = bool(thread_local)
+        self.raise_on_release_error = raise_on_release_error
         self.local = threading.local() if self.thread_local else SimpleNamespace()
         self.local.token = None
         self.register_scripts()
@@ -168,7 +178,14 @@ class Lock:
         exc_value: Optional[BaseException],
         traceback: Optional[TracebackType],
     ) -> None:
-        self.release()
+        try:
+            self.release()
+        except LockError:
+            if self.raise_on_release_error:
+                raise
+            logger.warning(
+                "Lock was unlocked or no longer owned when exiting context manager."
+            )
 
     def acquire(
         self,
@@ -251,7 +268,10 @@ class Lock:
         """
         expected_token = self.local.token
         if expected_token is None:
-            raise LockError("Cannot release an unlocked lock", lock_name=self.name)
+            raise LockError(
+                "Cannot release a lock that's not owned or is already unlocked.",
+                lock_name=self.name,
+            )
         self.local.token = None
         self.do_release(expected_token)
 
@@ -264,7 +284,7 @@ class Lock:
                 lock_name=self.name,
             )
 
-    def extend(self, additional_time: int, replace_ttl: bool = False) -> bool:
+    def extend(self, additional_time: Number, replace_ttl: bool = False) -> bool:
         """
         Adds more time to an already acquired lock.
 
@@ -281,7 +301,7 @@ class Lock:
             raise LockError("Cannot extend a lock with no timeout", lock_name=self.name)
         return self.do_extend(additional_time, replace_ttl)
 
-    def do_extend(self, additional_time: int, replace_ttl: bool) -> bool:
+    def do_extend(self, additional_time: Number, replace_ttl: bool) -> bool:
         additional_time = int(additional_time * 1000)
         if not bool(
             self.lua_extend(

redis/ocsp.py

@@ -15,6 +15,7 @@ from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicKey
 from cryptography.hazmat.primitives.hashes import SHA1, Hash
 from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
 from cryptography.x509 import ocsp
+
 from redis.exceptions import AuthorizationError, ConnectionError
 
 
@@ -56,7 +57,7 @@ def _check_certificate(issuer_cert, ocsp_bytes, validate=True):
     if ocsp_response.response_status == ocsp.OCSPResponseStatus.SUCCESSFUL:
         if ocsp_response.certificate_status != ocsp.OCSPCertStatus.GOOD:
             raise ConnectionError(
-                f'Received an {str(ocsp_response.certificate_status).split(".")[1]} '
+                f"Received an {str(ocsp_response.certificate_status).split('.')[1]} "
                 "ocsp certificate status"
             )
     else:

redis/sentinel.py

@@ -273,7 +273,7 @@ class Sentinel(SentinelCommands):
             )
         return (
             f"<{type(self).__module__}.{type(self).__name__}"
-            f'(sentinels=[{",".join(sentinel_addresses)}])>'
+            f"(sentinels=[{','.join(sentinel_addresses)}])>"
         )
 
     def check_master_state(self, state, service_name):
@@ -349,6 +349,8 @@ class Sentinel(SentinelCommands):
     ):
         """
         Returns a redis client instance for the ``service_name`` master.
+        Sentinel client will detect failover and reconnect Redis clients
+        automatically.
 
         A :py:class:`~redis.sentinel.SentinelConnectionPool` class is
         used to retrieve the master's address before establishing a new

redis/utils.py

@@ -1,7 +1,12 @@
+import datetime
 import logging
+import textwrap
 from contextlib import contextmanager
 from functools import wraps
-from typing import Any, Dict, Mapping, Union
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+from redis.exceptions import DataError
+from redis.typing import AbsExpiryT, EncodableT, ExpiryT
 
 try:
     import hiredis  # noqa
@@ -122,6 +127,71 @@ def deprecated_function(reason="", version="", name=None):
     return decorator
 
 
+def warn_deprecated_arg_usage(
+    arg_name: Union[list, str],
+    function_name: str,
+    reason: str = "",
+    version: str = "",
+    stacklevel: int = 2,
+):
+    import warnings
+
+    msg = (
+        f"Call to '{function_name}' function with deprecated"
+        f" usage of input argument/s '{arg_name}'."
+    )
+    if reason:
+        msg += f" ({reason})"
+    if version:
+        msg += f" -- Deprecated since version {version}."
+    warnings.warn(msg, category=DeprecationWarning, stacklevel=stacklevel)
+
+
+def deprecated_args(
+    args_to_warn: list = ["*"],
+    allowed_args: list = [],
+    reason: str = "",
+    version: str = "",
+):
+    """
+    Decorator to mark specified args of a function as deprecated.
+    If '*' is in args_to_warn, all arguments will be marked as deprecated.
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Get function argument names
+            arg_names = func.__code__.co_varnames[: func.__code__.co_argcount]
+
+            provided_args = dict(zip(arg_names, args))
+            provided_args.update(kwargs)
+
+            provided_args.pop("self", None)
+            for allowed_arg in allowed_args:
+                provided_args.pop(allowed_arg, None)
+
+            for arg in args_to_warn:
+                if arg == "*" and len(provided_args) > 0:
+                    warn_deprecated_arg_usage(
+                        list(provided_args.keys()),
+                        func.__name__,
+                        reason,
+                        version,
+                        stacklevel=3,
+                    )
+                elif arg in provided_args:
+                    warn_deprecated_arg_usage(
+                        arg, func.__name__, reason, version, stacklevel=3
+                    )
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
 def _set_info_logger():
     """
     Set up a logger that log info logs to stdout.
@@ -192,3 +262,46 @@ def ensure_string(key):
         return key
     else:
         raise TypeError("Key must be either a string or bytes")
+
+
+def extract_expire_flags(
+    ex: Optional[ExpiryT] = None,
+    px: Optional[ExpiryT] = None,
+    exat: Optional[AbsExpiryT] = None,
+    pxat: Optional[AbsExpiryT] = None,
+) -> List[EncodableT]:
+    exp_options: list[EncodableT] = []
+    if ex is not None:
+        exp_options.append("EX")
+        if isinstance(ex, datetime.timedelta):
+            exp_options.append(int(ex.total_seconds()))
+        elif isinstance(ex, int):
+            exp_options.append(ex)
+        elif isinstance(ex, str) and ex.isdigit():
+            exp_options.append(int(ex))
+        else:
+            raise DataError("ex must be datetime.timedelta or int")
+    elif px is not None:
+        exp_options.append("PX")
+        if isinstance(px, datetime.timedelta):
+            exp_options.append(int(px.total_seconds() * 1000))
+        elif isinstance(px, int):
+            exp_options.append(px)
+        else:
+            raise DataError("px must be datetime.timedelta or int")
+    elif exat is not None:
+        if isinstance(exat, datetime.datetime):
+            exat = int(exat.timestamp())
+        exp_options.extend(["EXAT", exat])
+    elif pxat is not None:
+        if isinstance(pxat, datetime.datetime):
+            pxat = int(pxat.timestamp() * 1000)
+        exp_options.extend(["PXAT", pxat])
+
+    return exp_options
+
+
+def truncate_text(txt, max_length=100):
+    return textwrap.shorten(
+        text=txt, width=max_length, placeholder="...", break_long_words=True
+    )