feat: Allow cache OPTIONS to specify USERNAME (#657)

---------

Co-authored-by: Joachim Burket <joachim.burket@hopitalvs.ch>
Co-authored-by: Terence D. Honles <terence@honles.com>

Author: 3 people

README.rst

@@ -106,56 +106,50 @@ There are several ways to specify a database number:
 - If using the ``redis://`` scheme, the path argument of the URL, e.g.
   ``redis://localhost/0``
 
-When using `Redis' ACLs <https://redis.io/topics/acl>`_, you will need to add the
-username to the URL (and provide the password with the Cache ``OPTIONS``).
+When using `Redis' ACLs <https://redis.io/topics/acl>`_, you will need to add
+the username and the password in the connection string or in ``OPTIONS`` with
+the keys ``USERNAME`` and ``PASSWORD``. *NOTE: Values in the connection string
+have precedence!*
+
 The login for the user ``django`` would look like this:
 
 .. code-block:: python
 
     CACHES = {
         "default": {
             "BACKEND": "django_redis.cache.RedisCache",
-            "LOCATION": "redis://django@localhost:6379/0",
-            "OPTIONS": {
-                "CLIENT_CLASS": "django_redis.client.DefaultClient",
-                "PASSWORD": "mysecret"
-            }
+            "LOCATION": "redis://django:mysecret@localhost:6379/0",
         }
     }
 
-An alternative would be write both username and password into the URL:
+Instead you may specify both of these values in ``OPTIONS``:
 
 .. code-block:: python
 
     CACHES = {
         "default": {
             "BACKEND": "django_redis.cache.RedisCache",
-            "LOCATION": "redis://django:mysecret@localhost:6379/0",
+            "LOCATION": "redis://localhost:6379/0",
             "OPTIONS": {
-                "CLIENT_CLASS": "django_redis.client.DefaultClient",
+                "USERNAME": "django",
+                "PASSWORD": "mysecret",
             }
         }
     }
 
-In some circumstances the password you should use to connect Redis
-is not URL-safe, in this case you can escape it or just use the
-convenience option in ``OPTIONS`` dict:
+And, finally you may mix the two as follows (be sure not to include a password,
+even if blank in the connection string):
 
 .. code-block:: python
 
     CACHES = {
         "default": {
             "BACKEND": "django_redis.cache.RedisCache",
-            "LOCATION": "redis://127.0.0.1:6379/1",
-            "OPTIONS": {
-                "CLIENT_CLASS": "django_redis.client.DefaultClient",
-                "PASSWORD": "mysecret"
-            }
+            "LOCATION": "redis://django@localhost:6379/0",
+            "OPTIONS": {"PASSWORD": "mysecret"}
         }
     }
 
-Take care, that this option does not overwrites the password in the uri, so if
-you have set the password in the uri, this settings will be ignored.
 
 Configure as session backend
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -708,8 +702,11 @@ In order to enable this functionality you should add the following:
                 # Sentinels which are passed directly to redis Sentinel.
                 "SENTINELS": SENTINELS,
 
-                # kwargs for redis Sentinel (optional).
-                "SENTINEL_KWARGS": {},
+                # kwargs for redis Sentinel (optional). Example with auth on sentinels
+                "SENTINEL_KWARGS": {
+                    "username": "sentinel-user",
+                    "password": "sentinel-pass",
+                },
 
                 # You can still override the connection pool (optional).
                 "CONNECTION_POOL_CLASS": "redis.sentinel.SentinelConnectionPool",

changelog.d/657.feature

@@ -0,0 +1 @@
+Added the ability to pass redis username in the cache options

django_redis/pool.py

@@ -95,6 +95,10 @@ def make_connection_params(self, url: str) -> dict[str, Any]:
             "parser_class": self.get_parser_cls(),
         }
 
+        username = self.options.get("USERNAME", None)
+        if username:
+            kwargs["username"] = username
+
         password = self.options.get("PASSWORD", None)
         if password:
             kwargs["password"] = password

tests/test_connection_params.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import pytest
+
+from django_redis import pool
+
+
+@pytest.mark.parametrize(
+    "connection_string",
+    [
+        "unix://tmp/foo.bar?db=1",
+        "redis://localhost/2",
+        "redis://redis-master/0?is_master=0",
+        "redis://redis-master/2?is_master=False",
+        "rediss://localhost:3333?db=2",
+    ],
+)
+def test_connection_strings(connection_string: str):
+    res = pool.ConnectionFactory({}).make_connection_params(connection_string)
+    assert res["url"] == connection_string
+
+
+def test_connection_options():
+    params = pool.ConnectionFactory(
+        {
+            "USERNAME": "django",
+            "PASSWORD": "mysecret",
+            "SOCKET_TIMEOUT": 5,
+        },
+    ).make_connection_params("")
+    assert (
+        params.items()
+        >= {
+            "username": "django",
+            "password": "mysecret",
+            "socket_timeout": 5,
+        }.items()
+    )
+
+
+@pytest.mark.parametrize(
+    "config, expected",
+    [
+        # username and password tests
+        (
+            {
+                "LOCATION": "redis://django:mysecret@localhost:6379/0",
+            },
+            {
+                "username": "django",
+                "password": "mysecret",
+                "host": "localhost",
+                "port": 6379,
+            },
+        ),
+        (
+            {
+                "LOCATION": "redis://localhost:6379/0",
+                "OPTIONS": {
+                    "USERNAME": "django",
+                    "PASSWORD": "mysecret",
+                },
+            },
+            {
+                "username": "django",
+                "password": "mysecret",
+            },
+        ),
+        (
+            {
+                "LOCATION": "redis://django@localhost:6379/0",
+                "OPTIONS": {"PASSWORD": "mysecret"},
+            },
+            {
+                "username": "django",
+                "password": "mysecret",
+            },
+        ),
+        # url has precedence!
+        (
+            {
+                "LOCATION": "redis://django:old-password@localhost:6379/0",
+                "OPTIONS": {"PASSWORD": "mysecret"},
+            },
+            {
+                "username": "django",
+                "password": "old-password",
+            },
+        ),
+    ],
+)
+def test_connection_connection_kwargs(config, expected):
+    factory = pool.ConnectionFactory(config.get("OPTIONS", {}))
+    assert (
+        factory.get_connection_pool(
+            factory.make_connection_params(config["LOCATION"]),
+        ).connection_kwargs.items()
+        >= expected.items()
+    )