feat(cache): add per-invocation TTL support and improve documentation

- Add per-invocation TTL feature for cached items
- Update README with detailed explanations of TTL and per-invocation TTL
- Refactor cache.py to support new TTL functionality
- Update CHANGELOG with new features and breaking changes

Author: tanbro

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - ✨ **New Features:**
   - Added arguments excluding support for the `RedisFuncCache` class, which makes it possible to cache functions with arguments that cannot be serialized.
+  - Added support for per-invocation TTL.
 
 - 💔 **Breaking Changes:**
   - Rename `redis_func_cache.mixins.policies` to `redis_func_cache.mixins.scripts`.

README.md

@@ -368,20 +368,52 @@ Policies that support both clusters and store cache in multiple [Redis][] key pa
 
 The [`RedisFuncCache`][] instance has two arguments to control the maximum size and expiration time of the cache:
 
-- `maxsize`: the maximum number of items that the cache can hold.
+- `maxsize`: The maximum number of items the cache can hold.
 
     When the cache reaches its `maxsize`, adding a new item will cause an existing cached item to be removed according to the eviction policy.
 
     > ℹ️ **Note:**\
     > For "multiple" policies, each decorated function has its own standalone data structure, so the value represents the maximum size of each individual data structure.
 
+    This argument can be set when creating a cache instance:
+
+    ```python
+    cache = RedisFuncCache("my-cache-5", LruTPolicy, redis_client, maxsize=100)
+    ```
+
 - `ttl`: The expiration time (in seconds) for the cache data structure.
 
-    The cache's [Redis][] data structure will expire and be released after the specified time.
-    Each time the cache is accessed, the expiration time will be reset.
+    The entire [Redis][] data structure for the cache will expire and be removed after the specified time.
+    Each time the cache is accessed, its expiration time is refreshed. Thus, the cache will only be removed if it is not accessed within the specified period.
 
     > ℹ️ **Note:**\
-    > For "multiple" policies, each decorated function has its own standalone data structure, so the `ttl` value represents the expiration time of each individual data structure. The expiration time will be reset each time the cache is accessed individually.
+    > For "multiple" policies, each decorated function has its own separate data structure, so the `ttl` value applies to each individual structure. The expiration time is refreshed independently whenever each cache is accessed.
+
+    You can set this argument when creating a cache instance:
+
+    ```python
+    cache = RedisFuncCache("my-cache-5", LruTPolicy, redis_client, ttl=300)
+    ```
+
+- per-invocation TTL: The expiration time (in seconds) for each cached item, not the entire cache.
+
+  You can set this argument when decorating a function:
+
+  ```python
+  @cache(ttl=300)
+  def my_func(x):
+      ...
+  ```
+
+  This means that each cached return value for a specific invocation of `my_func` will expire after 300 seconds.
+  The argument's default value is `None`, which means that the cache item will never expire.
+
+  > ⁉️ **Caution:**\
+  > This expiration relies on [Redis Hashes Field expiration](https://redis.io/docs/latest/develop/data-types/hashes/#field-expiration). Expiration only applies to the hash field (the cached return value), and does **not** reduce the total number of items in the cache when a field expires.
+  > Typically, the cached return value in the HASH portion is automatically released after expiration. However, the corresponding hash key in the ZSET portion is **not** removed automatically. Instead, it is only "lazily" cleaned up when accessed, or removed by the eviction policy when a new value is added. During this period, the ZSET portion continues to occupy memory, and the reported number of cache items does not decrease.
+
+  > ⚠️ **Warning:**\
+  > This feature requires [Redis][] Open Source version 7.4 or later.
 
 ### Complex return types
 

src/redis_func_cache/cache.py

@@ -444,8 +444,9 @@ async def aput(
         ext_args = ext_args or ()
         await script(keys=key_pair, args=chain((maxsize, ttl, hash_, value, field_ttl, encoded_options), ext_args))
 
-    def _make_bound(
-        self,
+    @classmethod
+    def make_bound(
+        cls,
         user_func: Callable,
         user_args: Tuple[Any, ...],
         user_kwds: Dict[str, Any],
@@ -464,13 +465,13 @@ def _make_bound(
             bound.arguments = OrderedDict((k, v) for k, v in bound.arguments.items() if k not in excludes)
         return bound
 
-    def _before_get(
+    def prepare(
         self,
         user_function: Callable,
         user_args: Tuple[Any, ...],
         user_kwds: Dict[str, Any],
         bound: Optional[BoundArguments] = None,
-    ):
+    ) -> Tuple[Tuple[KeyT, KeyT], KeyT, Iterable[EncodableT]]:
         if bound is None:
             args, kwds = user_args, user_kwds
         else:
@@ -488,9 +489,9 @@ def exec(
         serialize_func: Optional[SerializerT] = None,
         deserialize_func: Optional[DeserializerT] = None,
         bound: Optional[BoundArguments] = None,
-        field_ttl: Optional[int] = None,
+        field_ttl: int = 0,
         **options,
-    ):
+    ) -> Any:
         """Execute the given user function with the provided arguments.
 
         Args:
@@ -517,7 +518,7 @@ def exec(
         script_0, script_1 = self.policy.lua_scripts
         if not (isinstance(script_0, redis.commands.core.Script) and isinstance(script_1, redis.commands.core.Script)):
             raise TypeError("Can not eval redis lua script in asynchronous mode on a synchronous redis client")
-        keys, hash_value, ext_args = self._before_get(user_function, user_args, user_kwds, bound)
+        keys, hash_value, ext_args = self.prepare(user_function, user_args, user_kwds, bound)
         cached_return_value = self.get(script_0, keys, hash_value, self.ttl, options, ext_args)
         if cached_return_value is not None:
             return self.deserialize(cached_return_value, deserialize_func)
@@ -544,17 +545,17 @@ async def aexec(
         serialize_func: Optional[SerializerT] = None,
         deserialize_func: Optional[DeserializerT] = None,
         bound: Optional[BoundArguments] = None,
-        field_ttl: Optional[int] = None,
+        field_ttl: int = 0,
         **options,
-    ):
+    ) -> Any:
         """Asynchronous version of :meth:`.exec`"""
         script_0, script_1 = self.policy.lua_scripts
         if not (
             isinstance(script_0, redis.commands.core.AsyncScript)
             and isinstance(script_1, redis.commands.core.AsyncScript)
         ):
             raise TypeError("Can not eval redis lua script in synchronous mode on an asynchronous redis client")
-        keys, hash_value, ext_args = self._before_get(user_function, user_args, user_kwds, bound)
+        keys, hash_value, ext_args = self.prepare(user_function, user_args, user_kwds, bound)
         cached = await self.aget(script_0, keys, hash_value, self.ttl, options, ext_args)
         if cached is not None:
             return self.deserialize(cached, deserialize_func)
@@ -675,33 +676,34 @@ def my_func(a, b):
             serialize_func, deserialize_func = self.__serializers__[serializer]
         elif serializer is not None:
             serialize_func, deserialize_func = serializer
+        field_ttl = 0 if ttl is None else int(ttl)
 
         def decorator(user_func: CallableTV) -> CallableTV:
             @wraps(user_func)
             def wrapper(*user_args, **user_kwargs):
-                bound = self._make_bound(user_func, user_args, user_kwargs, excludes, excludes_positional)
+                bound = self.make_bound(user_func, user_args, user_kwargs, excludes, excludes_positional)
                 return self.exec(
                     user_func,
                     user_args,
                     user_kwargs,
                     serialize_func,
                     deserialize_func,
                     bound,
-                    ttl,
+                    field_ttl,
                     **options,
                 )
 
             @wraps(user_func)
             async def awrapper(*user_args, **user_kwargs):
-                bound = self._make_bound(user_func, user_args, user_kwargs, excludes, excludes_positional)
+                bound = self.make_bound(user_func, user_args, user_kwargs, excludes, excludes_positional)
                 return await self.aexec(
                     user_func,
                     user_args,
                     user_kwargs,
                     serialize_func,
                     deserialize_func,
                     bound,
-                    ttl,
+                    field_ttl,
                     **options,
                 )