add method to get the CachedValue / cached time directly

Added new method :meth:`.CacheRegion.get_value_metadata` which can be used
to get a value from the cache along with its metadata, including timestamp
of when the value was cached.  The :class:`.CachedValue` object is returned
which features new accessors to retrieve cached time and current age. Pull
request courtesy Grégoire Deveaux.

Fixes: #37
Closes: #247
Pull-request: #247
Pull-request-sha: e21961d

Change-Id: I192b6768f1c6c1b4c75c122eb372cf89121e78ba

Author: Grégoire Deveaux

docs/build/unreleased/37.rst

@@ -0,0 +1,11 @@
+.. change::
+    :tags: feature, region
+    :tickets: 37
+
+    Added new method :meth:`.CacheRegion.get_value_metadata` which can be used
+    to get a value from the cache along with its metadata, including timestamp
+    of when the value was cached.  The :class:`.CachedValue` object is returned
+    which features new accessors to retrieve cached time and current age. Pull
+    request courtesy Grégoire Deveaux.
+
+

dogpile/cache/api.py

@@ -2,6 +2,7 @@
 
 import abc
 import pickle
+import time
 from typing import Any
 from typing import Callable
 from typing import cast
@@ -125,8 +126,38 @@ class CachedValue(NamedTuple):
     """
 
     payload: ValuePayload
+    """the actual cached value."""
 
     metadata: MetaDataType
+    """Metadata dictionary for the cached value.
+
+    Prefer using accessors such as :attr:`.CachedValue.cached_time` rather
+    than accessing this mapping directly.
+
+    """
+
+    @property
+    def cached_time(self) -> float:
+        """The epoch (floating point time value) stored when this payload was
+        cached.
+
+        .. versionadded:: 1.3
+
+        """
+        return cast(float, self.metadata["ct"])
+
+    @property
+    def age(self) -> float:
+        """Returns the elapsed time in seconds as a `float` since the insertion
+        of the value in the cache.
+
+        This value is computed **dynamically** by subtracting the cached
+        floating point epoch value from the value of ``time.time()``.
+
+        .. versionadded:: 1.3
+
+        """
+        return time.time() - self.cached_time
 
 
 CacheReturnType = Union[CachedValue, NoValue]

dogpile/cache/region.py

@@ -17,6 +17,7 @@
 from typing import Sequence
 from typing import Tuple
 from typing import Type
+from typing import TYPE_CHECKING
 from typing import Union
 
 from decorator import decorate
@@ -700,7 +701,12 @@ def is_configured(self):
         """
         return "backend" in self.__dict__
 
-    def get(self, key, expiration_time=None, ignore_expiration=False):
+    def get(
+        self,
+        key: KeyType,
+        expiration_time: Optional[float] = None,
+        ignore_expiration: bool = False,
+    ) -> CacheReturnType:
         """Return a value from the cache, based on the given key.
 
         If the value is not present, the method returns the token
@@ -771,15 +777,49 @@ def get(self, key, expiration_time=None, ignore_expiration=False):
 
 
         """
+        value = self._get_cache_value(key, expiration_time, ignore_expiration)
+        return value.payload
+
+    def get_value_metadata(
+        self,
+        key: KeyType,
+        expiration_time: Optional[float] = None,
+        ignore_expiration: bool = False,
+    ) -> Optional[CachedValue]:
+        """Return the :class:`.CachedValue` object directly from the cache.
+
+        This is the enclosing datastructure that includes the value as well as
+        the metadata, including the timestamp when the value was cached.
+        Convenience accessors on :class:`.CachedValue` also provide for common
+        data such as :attr:`.CachedValue.cached_time` and
+        :attr:`.CachedValue.age`.
+
 
+        .. versionadded:: 1.3. Added :meth:`.CacheRegion.get_value_metadata`
+        """
+        cache_value = self._get_cache_value(
+            key, expiration_time, ignore_expiration
+        )
+        if cache_value is NO_VALUE:
+            return None
+        else:
+            if TYPE_CHECKING:
+                assert isinstance(cache_value, CachedValue)
+            return cache_value
+
+    def _get_cache_value(
+        self,
+        key: KeyType,
+        expiration_time: Optional[float] = None,
+        ignore_expiration: bool = False,
+    ) -> CacheReturnType:
         if self.key_mangler:
             key = self.key_mangler(key)
         value = self._get_from_backend(key)
         value = self._unexpired_value_fn(expiration_time, ignore_expiration)(
             value
         )
-
-        return value.payload
+        return value
 
     def _unexpired_value_fn(self, expiration_time, ignore_expiration):
         if ignore_expiration:

tests/cache/test_region.py

@@ -533,6 +533,40 @@ def test_should_delete_multiple_values(self):
         eq_(NO_VALUE, reg.get("key2"))
         eq_(values["key3"], reg.get("key3"))
 
+    def test_get_value_metadata(self):
+        reg = self._region()
+        with mock.patch("time.time", return_value=100):
+            reg.set("some key", "some value")
+        with mock.patch("time.time", return_value=105):
+            value_metadata = reg.get_value_metadata("some key")
+            eq_(value_metadata.payload, "some value")
+            eq_(value_metadata.cached_time, 100)
+            eq_(value_metadata.age, 5)
+
+    def test_get_value_metadata_no_value(self):
+        reg = self._region()
+        is_(reg.get_value_metadata("some key"), None)
+
+    def test_get_value_metadata_expired(self):
+        reg = self._region()
+        with mock.patch("time.time", return_value=100):
+            reg.set("some key", "some value")
+        with mock.patch("time.time", return_value=105):
+            value_metadata = reg.get_value_metadata("some key", 4)
+            is_(value_metadata, None)
+
+    def test_get_value_metadata_expiration_ignored(self):
+        reg = self._region()
+        with mock.patch("time.time", return_value=100):
+            reg.set("some key", "some value")
+        with mock.patch("time.time", return_value=105):
+            value_metadata = reg.get_value_metadata(
+                "some key", expiration_time=4, ignore_expiration=True
+            )
+            eq_(value_metadata.payload, "some value")
+            eq_(value_metadata.cached_time, 100)
+            eq_(value_metadata.age, 5)
+
 
 class ProxyRegionTest(RegionTest):