Make expire, pexpire, expireat and persist return the redis client value (#565)

* Make expire, pexpire, expireat return the value redis returns for these actions. True/1 if the key was present in redis, False/0 if not present
* Add pexpire_at. Cast values to bool for consistency

Author: puittenbroek

README.rst

@@ -393,22 +393,47 @@ specify a new expiration timeout using the ``persist`` and ``expire`` methods:
     >>> cache.ttl("foo")
     22
     >>> cache.persist("foo")
+    True
     >>> cache.ttl("foo")
     None
 
 .. code-block:: pycon
 
     >>> cache.set("foo", "bar", timeout=22)
     >>> cache.expire("foo", timeout=5)
+    True
     >>> cache.ttl("foo")
     5
 
+The ``expire_at`` method can be used to make the key expire at a specific moment in time.
+
+.. code-block:: pycon
+
+    >>> cache.set("foo", "bar", timeout=22)
+    >>> cache.expire_at("foo", datetime.now() + timedelta(hours=1))
+    True
+    >>> cache.ttl("foo")
+    3600
+
+The ``pexpire_at`` method can be used to make the key expire at a specific moment in time with milliseconds precision:
+
+.. code-block:: pycon
+
+    >>> cache.set("foo", "bar", timeout=22)
+    >>> cache.pexpire_at("foo", datetime.now() + timedelta(milliseconds=900, hours=1))
+    True
+    >>> cache.ttl("foo")
+    3601
+    >>> cache.pttl("foo")
+    3600900
+
 The ``pexpire`` method can be used to provide millisecond precision:
 
 .. code-block:: pycon
 
     >>> cache.set("foo", "bar", timeout=22)
     >>> cache.pexpire("foo", timeout=5500)
+    True
     >>> cache.pttl("foo")
     5500
 

changelog.d/564.bugfix

@@ -0,0 +1 @@
+Make expire, pexpire, expireat and persist return the redis client value

changelog.d/564.feature

@@ -0,0 +1 @@
+Add pexpireat to allow setting 'expire at' with millisecond precision.

django_redis/cache.py

@@ -168,6 +168,10 @@ def expire_at(self, *args, **kwargs):
     def pexpire(self, *args, **kwargs):
         return self.client.pexpire(*args, **kwargs)
 
+    @omit_exception
+    def pexpire_at(self, *args, **kwargs):
+        return self.client.pexpire_at(*args, **kwargs)
+
     @omit_exception
     def lock(self, *args, **kwargs):
         return self.client.lock(*args, **kwargs)

django_redis/client/default.py

@@ -266,46 +266,63 @@ def get(
 
     def persist(
         self, key: Any, version: Optional[int] = None, client: Optional[Redis] = None
-    ) -> None:
+    ) -> bool:
         if client is None:
             client = self.get_client(write=True)
 
         key = self.make_key(key, version=version)
 
-        if client.exists(key):
-            client.persist(key)
+        return client.persist(key)
 
     def expire(
         self,
         key: Any,
         timeout,
         version: Optional[int] = None,
         client: Optional[Redis] = None,
-    ) -> None:
+    ) -> bool:
         if client is None:
             client = self.get_client(write=True)
 
         key = self.make_key(key, version=version)
 
-        if client.exists(key):
-            client.expire(key, timeout)
+        return client.expire(key, timeout)
 
-    def pexpire(self, key, timeout, version=None, client=None):
+    def pexpire(self, key, timeout, version=None, client=None) -> bool:
+        if client is None:
+            client = self.get_client(write=True)
+
+        key = self.make_key(key, version=version)
+
+        # Temporary casting until https://github.com/redis/redis-py/issues/1664
+        # is fixed.
+        return bool(client.pexpire(key, timeout))
+
+    def pexpire_at(
+        self,
+        key: Any,
+        when: Union[datetime, int],
+        version: Optional[int] = None,
+        client: Optional[Redis] = None,
+    ) -> bool:
+        """
+        Set an expire flag on a ``key`` to ``when``, which can be represented
+        as an integer indicating unix time or a Python datetime object.
+        """
         if client is None:
             client = self.get_client(write=True)
 
         key = self.make_key(key, version=version)
 
-        if client.exists(key):
-            client.pexpire(key, timeout)
+        return bool(client.pexpireat(key, when))
 
     def expire_at(
         self,
         key: Any,
         when: Union[datetime, int],
         version: Optional[int] = None,
         client: Optional[Redis] = None,
-    ) -> None:
+    ) -> bool:
         """
         Set an expire flag on a ``key`` to ``when``, which can be represented
         as an integer indicating unix time or a Python datetime object.
@@ -315,8 +332,7 @@ def expire_at(
 
         key = self.make_key(key, version=version)
 
-        if client.exists(key):
-            client.expireat(key, when)
+        return client.expireat(key, when)
 
     def lock(
         self,

django_redis/client/sharded.py

@@ -171,6 +171,18 @@ def pexpire(self, key, timeout, version=None, client=None):
 
         return super().pexpire(key=key, timeout=timeout, version=version, client=client)
 
+    def pexpire_at(self, key, when: Union[datetime, int], version=None, client=None):
+        """
+        Set an expire flag on a ``key`` to ``when`` on a shard client.
+        ``when`` which can be represented as an integer indicating unix
+        time or a Python datetime object.
+        """
+        if client is None:
+            key = self.make_key(key, version=version)
+            client = self.get_server(key)
+
+        return super().pexpire_at(key=key, when=when, version=version, client=client)
+
     def expire_at(self, key, when: Union[datetime, int], version=None, client=None):
         """
         Set an expire flag on a ``key`` to ``when`` on a shard client.

tests/test_backend.py

@@ -577,47 +577,79 @@ def test_pttl(self, cache: RedisCache):
 
     def test_persist(self, cache: RedisCache):
         cache.set("foo", "bar", timeout=20)
-        cache.persist("foo")
+        assert cache.persist("foo") is True
 
         ttl = cache.ttl("foo")
         assert ttl is None
+        assert cache.persist("not-existent-key") is False
 
     def test_expire(self, cache: RedisCache):
         cache.set("foo", "bar", timeout=None)
-        cache.expire("foo", 20)
+        assert cache.expire("foo", 20) is True
         ttl = cache.ttl("foo")
         assert pytest.approx(ttl) == 20
+        assert cache.expire("not-existent-key", 20) is False
 
     def test_pexpire(self, cache: RedisCache):
         cache.set("foo", "bar", timeout=None)
-        cache.pexpire("foo", 20500)
+        assert cache.pexpire("foo", 20500) is True
         ttl = cache.pttl("foo")
         # delta is set to 10 as precision error causes tests to fail
         assert pytest.approx(ttl, 10) == 20500
+        assert cache.pexpire("not-existent-key", 20500) is False
+
+    def test_pexpire_at(self, cache: RedisCache):
+
+        # Test settings expiration time 1 hour ahead by datetime.
+        cache.set("foo", "bar", timeout=None)
+        expiration_time = datetime.datetime.now() + timedelta(hours=1)
+        assert cache.pexpire_at("foo", expiration_time) is True
+        ttl = cache.pttl("foo")
+        assert pytest.approx(ttl, 10) == timedelta(hours=1).total_seconds()
+
+        # Test settings expiration time 1 hour ahead by Unix timestamp.
+        cache.set("foo", "bar", timeout=None)
+        expiration_time = datetime.datetime.now() + timedelta(hours=2)
+        assert cache.pexpire_at("foo", int(expiration_time.timestamp() * 1000)) is True
+        ttl = cache.pttl("foo")
+        assert pytest.approx(ttl, 10) == timedelta(hours=2).total_seconds() * 1000
+
+        # Test settings expiration time 1 hour in past, which effectively
+        # deletes the key.
+        expiration_time = datetime.datetime.now() - timedelta(hours=2)
+        assert cache.pexpire_at("foo", expiration_time) is True
+        value = cache.get("foo")
+        assert value is None
+
+        expiration_time = datetime.datetime.now() + timedelta(hours=2)
+        assert cache.pexpire_at("not-existent-key", expiration_time) is False
 
     def test_expire_at(self, cache: RedisCache):
 
         # Test settings expiration time 1 hour ahead by datetime.
         cache.set("foo", "bar", timeout=None)
         expiration_time = datetime.datetime.now() + timedelta(hours=1)
-        cache.expire_at("foo", expiration_time)
+        assert cache.expire_at("foo", expiration_time) is True
         ttl = cache.ttl("foo")
         assert pytest.approx(ttl, 1) == timedelta(hours=1).total_seconds()
 
         # Test settings expiration time 1 hour ahead by Unix timestamp.
         cache.set("foo", "bar", timeout=None)
         expiration_time = datetime.datetime.now() + timedelta(hours=2)
-        cache.expire_at("foo", int(expiration_time.timestamp()))
+        assert cache.expire_at("foo", int(expiration_time.timestamp())) is True
         ttl = cache.ttl("foo")
         assert pytest.approx(ttl, 1) == timedelta(hours=1).total_seconds() * 2
 
         # Test settings expiration time 1 hour in past, which effectively
         # deletes the key.
         expiration_time = datetime.datetime.now() - timedelta(hours=2)
-        cache.expire_at("foo", expiration_time)
+        assert cache.expire_at("foo", expiration_time) is True
         value = cache.get("foo")
         assert value is None
 
+        expiration_time = datetime.datetime.now() + timedelta(hours=2)
+        assert cache.expire_at("not-existent-key", expiration_time) is False
+
     def test_lock(self, cache: RedisCache):
         lock = cache.lock("foobar")
         lock.acquire(blocking=True)