add lock blocking control to redis/valkey; SSL arguments

Fixes: #271
Fixes: #276
Closes: #272
Pull-request: #272
Pull-request-sha: 0b44a26

Change-Id: I680602a3abe8c9f185017c6d00b7b3c3420b3ec7

Author: jvanasco

docs/build/Makefile

@@ -4,6 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
+AUTOBUILD     = sphinx-autobuild  --port 8080  --watch ../../dogpile
 PAPER         =
 BUILDDIR      = output
 
@@ -12,11 +13,12 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+.PHONY: help clean html autobuild dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
+	@echo "  autobuild  autobuild and run a webserver"
 	@echo "  dist-html same as html, but places files in /doc"
 	@echo "  dirhtml   to make HTML files named index.html in directories"
 	@echo "  pickle    to make pickle files"
@@ -36,6 +38,9 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+autobuild:
+	$(AUTOBUILD) $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
 dist-html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	cp -R $(BUILDDIR)/html/* ../

docs/build/unreleased/271.rst

@@ -0,0 +1,10 @@
+.. change::
+    :tags: usecase, redis
+    :tickets: 271
+
+    Added new parameters :paramref:`.RedisBackend.lock_blocking_timeout` and
+    :paramref:`.RedisBackend.lock_blocking` to the Redis backend; and
+    :paramref:`.ValkeyBackend.lock_blocking_timeout` and
+    :paramref:`.ValkeyBackend.lock_blocking` to the Valkey backends.  These
+    parameters are then passed onto the redis/valkey client Lock creation
+    methods and use the same defaults.

docs/build/unreleased/276.rst

@@ -0,0 +1,15 @@
+.. change::
+    :tags: usecase, redis
+    :tickets: 276
+
+    Added new parameters for the Redis/Valkey backends. These params are passed
+    directly to the constructors:
+
+    * :paramref:`.RedisBackend.ssl`
+    * :paramref:`.ValkeyBackend.ssl`
+
+    These params default to ``None``, and are only passed to the constructor if
+    set. The docstrings instruct users to submit all additional ``ssl_``
+    prefixed params via the optional
+    :paramref:`.RedisBackend.connection_kwargs` or
+    :paramref:`.ValkeyBackend.connection_kwargs` parameter.

dogpile/cache/backends/redis.py

@@ -2,7 +2,7 @@
 Redis Backends
 ------------------
 
-Provides backends for talking to `Redis <http://redis.io>`_.
+Provides backends for talking to `Redis <http://redis.io>`__.
 
 """
 
@@ -22,8 +22,8 @@
 
 
 class RedisBackend(BytesBackend):
-    r"""A `Redis <http://redis.io/>`_ backend, using the
-    `redis-py <http://pypi.python.org/pypi/redis/>`_ driver.
+    r"""A `Redis <http://redis.io/>`__ backend, using the
+    `redis-py <http://pypi.python.org/pypi/redis/>`__ driver.
 
     Example configuration::
 
@@ -73,6 +73,20 @@ class RedisBackend(BytesBackend):
      Redis should expire it.  This argument is only valid when
      ``distributed_lock`` is ``True``.
 
+    :param lock_sleep: integer, number of seconds to sleep when failed to
+     acquire a lock.  This argument is only valid when
+     ``distributed_lock`` is ``True``.
+
+    :param lock_blocking: bool, default ``True``. Passed to the Redis client's
+     lock constructor when ``distributed_lock`` is ``True``.
+
+     .. versionadded:: 1.4.1
+
+    :param lock_blocking_timeout: int or float, default ``None``. Passed to the
+     Redis client's lock constructor when ``distributed_lock`` is ``True``.
+
+     .. versionadded:: 1.4.1
+
     :param socket_timeout: float, seconds for socket timeout.
      Default is None (no timeout).
 
@@ -91,10 +105,6 @@ class RedisBackend(BytesBackend):
 
      .. versionadded:: 1.3.2
 
-    :param lock_sleep: integer, number of seconds to sleep when failed to
-     acquire a lock.  This argument is only valid when
-     ``distributed_lock`` is ``True``.
-
     :param connection_pool: ``redis.ConnectionPool`` object.  If provided,
      this object supersedes other connection arguments passed to the
      ``redis.StrictRedis`` instance, including url and/or host as well as
@@ -106,17 +116,20 @@ class RedisBackend(BytesBackend):
      asynchronous runners, as they run in a different thread than the one
      used to create the lock.
 
+    :param ssl: boolean, default ``None``. If set, this is passed to the
+     ``redis.StrictRedis`` constructor as ``ssl``. All additional ``ssl_``
+     prefixed args should be submitted via the
+     :paramref:`.RedisBackend.connection_kwargs` dict.
+
+     .. versionadded:: 1.4.1
+
     :param connection_kwargs: dict, additional keyword arguments are passed
      along to the
      ``StrictRedis.from_url()`` method or ``StrictRedis()`` constructor
      directly, including parameters like ``ssl``, ``ssl_certfile``,
      ``charset``, etc.
 
      .. versionadded:: 1.1.6
-
-
-
-
     """
 
     def __init__(self, arguments):
@@ -128,7 +141,6 @@ def __init__(self, arguments):
         self.password = arguments.pop("password", None)
         self.port = arguments.pop("port", 6379)
         self.db = arguments.pop("db", 0)
-        self.distributed_lock = arguments.pop("distributed_lock", False)
         self.socket_timeout = arguments.pop("socket_timeout", None)
         self.socket_connect_timeout = arguments.pop(
             "socket_connect_timeout", None
@@ -137,8 +149,19 @@ def __init__(self, arguments):
         self.socket_keepalive_options = arguments.pop(
             "socket_keepalive_options", None
         )
+
+        # additional ssl params should be submitted in `connection_kwargs`
+        self.ssl = arguments.pop("ssl", None)
+
+        # used by `get_mutex`
+        self.distributed_lock = arguments.pop("distributed_lock", False)
         self.lock_timeout = arguments.pop("lock_timeout", None)
         self.lock_sleep = arguments.pop("lock_sleep", 0.1)
+        self.lock_blocking = arguments.pop("lock_blocking", True)
+        self.lock_blocking_timeout = arguments.pop(
+            "lock_blocking_timeout", None
+        )
+
         self.thread_local_lock = arguments.pop("thread_local_lock", True)
         self.connection_kwargs = arguments.pop("connection_kwargs", {})
 
@@ -150,6 +173,7 @@ def __init__(self, arguments):
 
         self.redis_expiration_time = arguments.pop("redis_expiration_time", 0)
         self.connection_pool = arguments.pop("connection_pool", None)
+
         self._create_client()
 
     def _imports(self):
@@ -179,6 +203,8 @@ def _create_client(self):
                     args["socket_keepalive_options"] = (
                         self.socket_keepalive_options
                     )
+            if self.ssl is not None:
+                args["ssl"] = self.ssl
 
             if self.url is not None:
                 args.update(url=self.url)
@@ -203,6 +229,8 @@ def get_mutex(self, key):
                     timeout=self.lock_timeout,
                     sleep=self.lock_sleep,
                     thread_local=self.thread_local_lock,
+                    blocking=self.lock_blocking,
+                    blocking_timeout=self.lock_blocking_timeout,
                 )
             )
         else:
@@ -259,10 +287,10 @@ def locked(self) -> bool:
 
 
 class RedisSentinelBackend(RedisBackend):
-    """A `Redis <http://redis.io/>`_ backend, using the
-    `redis-py <http://pypi.python.org/pypi/redis/>`_ driver.
+    """A `Redis <http://redis.io/>`__ backend, using the
+    `redis-py <http://pypi.python.org/pypi/redis/>`__ driver.
     This backend is to be used when using
-    `Redis Sentinel <https://redis.io/docs/management/sentinel/>`_.
+    `Redis Sentinel <https://redis.io/docs/management/sentinel/>`__.
 
     .. versionadded:: 1.0.0
 
@@ -413,17 +441,17 @@ def _create_client(self):
 
 
 class RedisClusterBackend(RedisBackend):
-    r"""A `Redis <http://redis.io/>`_ backend, using the
-    `redis-py <http://pypi.python.org/pypi/redis/>`_ driver.
+    r"""A `Redis <http://redis.io/>`__ backend, using the
+    `redis-py <http://pypi.python.org/pypi/redis/>`__ driver.
     This backend is to be used when connecting to a
-    `Redis Cluster <https://redis.io/docs/management/scaling/>`_ which
+    `Redis Cluster <https://redis.io/docs/management/scaling/>`__ which
     will use the
     `RedisCluster Client
-    <https://redis.readthedocs.io/en/stable/connections.html#cluster-client>`_.
+    <https://redis.readthedocs.io/en/stable/connections.html#cluster-client>`__.
 
     .. seealso::
 
-        `Clustering <https://redis.readthedocs.io/en/stable/clustering.html>`_
+        `Clustering <https://redis.readthedocs.io/en/stable/clustering.html>`__
         in the redis-py documentation.
 
     Requires redis-py version >=4.1.0.

dogpile/cache/backends/valkey.py

@@ -2,7 +2,7 @@
 Valkey Backends
 ------------------
 
-Provides backends for talking to `Valkey <http://valkey.io>`_.
+Provides backends for talking to `Valkey <http://valkey.io>`__.
 
 """
 
@@ -22,8 +22,8 @@
 
 
 class ValkeyBackend(BytesBackend):
-    r"""A `Valkey <http://valkey.io/>`_ backend, using the
-    `valkey-py <http://pypi.python.org/pypi/valkey/>`_ driver.
+    r"""A `Valkey <http://valkey.io/>`__ backend, using the
+    `valkey-py <http://pypi.python.org/pypi/valkey/>`__ driver.
 
     .. versionadded:: 1.3.4
 
@@ -73,6 +73,21 @@ class ValkeyBackend(BytesBackend):
      Valkey should expire it.  This argument is only valid when
      ``distributed_lock`` is ``True``.
 
+    :param lock_sleep: integer, number of seconds to sleep when failed to
+     acquire a lock.  This argument is only valid when
+     ``distributed_lock`` is ``True``.
+
+    :param lock_blocking: bool, default ``True``. Passed to the Valkey client's
+     lock constructor when ``distributed_lock`` is ``True``.
+
+     .. versionadded:: 1.4.1
+
+    :param lock_blocking_timeout: int or float, default ``None``.  Passed to
+     the Valkey client's lock constructor, when ``distributed_lock`` is
+     ``True``.
+
+     .. versionadded:: 1.4.1
+
     :param socket_timeout: float, seconds for socket timeout.
      Default is None (no timeout).
 
@@ -85,10 +100,6 @@ class ValkeyBackend(BytesBackend):
     :param socket_keepalive_options: dict, socket keepalive options.
      Default is None (no options).
 
-    :param lock_sleep: integer, number of seconds to sleep when failed to
-     acquire a lock.  This argument is only valid when
-     ``distributed_lock`` is ``True``.
-
     :param connection_pool: ``valkey.ConnectionPool`` object.  If provided,
      this object supersedes other connection arguments passed to the
      ``valkey.StrictValkey`` instance, including url and/or host as well as
@@ -100,13 +111,18 @@ class ValkeyBackend(BytesBackend):
      asynchronous runners, as they run in a different thread than the one
      used to create the lock.
 
+    :param ssl: boolean, default ``None``. If set, this is passed to the
+      ``valkey.StrictValkey`` constructor as ``ssl``. All additional ``ssl_``
+      prefixed args should be submitted via the
+      :paramref:`.ValkeyBackend.connection_kwargs` dict.
+
+      .. versionadded:: 1.4.1
+
     :param connection_kwargs: dict, additional keyword arguments are passed
      along to the
      ``StrictValkey.from_url()`` method or ``StrictValkey()`` constructor
      directly, including parameters like ``ssl``, ``ssl_certfile``,
      ``charset``, etc.
-
-
     """
 
     def __init__(self, arguments):
@@ -118,7 +134,6 @@ def __init__(self, arguments):
         self.password = arguments.pop("password", None)
         self.port = arguments.pop("port", 6379)
         self.db = arguments.pop("db", 0)
-        self.distributed_lock = arguments.pop("distributed_lock", False)
         self.socket_timeout = arguments.pop("socket_timeout", None)
         self.socket_connect_timeout = arguments.pop(
             "socket_connect_timeout", None
@@ -127,8 +142,19 @@ def __init__(self, arguments):
         self.socket_keepalive_options = arguments.pop(
             "socket_keepalive_options", None
         )
+
+        # additional ssl params should be submitted in `connection_kwargs`
+        self.ssl = arguments.pop("ssl", None)
+
+        # used by `get_mutex`
+        self.distributed_lock = arguments.pop("distributed_lock", False)
         self.lock_timeout = arguments.pop("lock_timeout", None)
         self.lock_sleep = arguments.pop("lock_sleep", 0.1)
+        self.lock_blocking = arguments.pop("lock_blocking", True)
+        self.lock_blocking_timeout = arguments.pop(
+            "lock_blocking_timeout", None
+        )
+
         self.thread_local_lock = arguments.pop("thread_local_lock", True)
         self.connection_kwargs = arguments.pop("connection_kwargs", {})
 
@@ -171,6 +197,8 @@ def _create_client(self):
                     args["socket_keepalive_options"] = (
                         self.socket_keepalive_options
                     )
+            if self.ssl is not None:
+                args["ssl"] = self.ssl
 
             if self.url is not None:
                 args.update(url=self.url)
@@ -195,6 +223,8 @@ def get_mutex(self, key):
                     timeout=self.lock_timeout,
                     sleep=self.lock_sleep,
                     thread_local=self.thread_local_lock,
+                    blocking=self.lock_blocking,
+                    blocking_timeout=self.lock_blocking_timeout,
                 )
             )
         else:
@@ -251,10 +281,10 @@ def locked(self) -> bool:
 
 
 class ValkeySentinelBackend(ValkeyBackend):
-    """A `Valkey <http://valkey.io/>`_ backend, using the
-    `valkey-py <http://pypi.python.org/pypi/valkey/>`_ driver.
+    """A `Valkey <http://valkey.io/>`__ backend, using the
+    `valkey-py <http://pypi.python.org/pypi/valkey/>`__ driver.
     This backend is to be used when using
-    `Valkey Sentinel <https://valkey.io/docs/management/sentinel/>`_.
+    `Valkey Sentinel <https://valkey.io/docs/management/sentinel/>`__.
 
     .. versionadded:: 1.0.0
 
@@ -405,17 +435,17 @@ def _create_client(self):
 
 
 class ValkeyClusterBackend(ValkeyBackend):
-    r"""A `Valkey <http://valkey.io/>`_ backend, using the
-    `valkey-py <http://pypi.python.org/pypi/valkey/>`_ driver.
+    r"""A `Valkey <http://valkey.io/>`__ backend, using the
+    `valkey-py <http://pypi.python.org/pypi/valkey/>`__ driver.
     This backend is to be used when connecting to a
-    `Valkey Cluster <https://valkey.io/docs/management/scaling/>`_ which
+    `Valkey Cluster <https://valkey.io/docs/management/scaling/>`__ which
     will use the
     `ValkeyCluster Client
-    <https://valkey.readthedocs.io/en/stable/connections.html#cluster-client>`_.
+    <https://valkey.readthedocs.io/en/stable/connections.html#cluster-client>`__.
 
     .. seealso::
 
-        `Clustering <https://valkey.readthedocs.io/en/stable/clustering.html>`_
+        `Clustering <https://valkey.readthedocs.io/en/stable/clustering.html>`__
         in the valkey-py documentation.
 
     Requires valkey-py version >=4.1.0.