add a 'tag' parameter to the 'cache' decorator for future functionality (#16)

Author: seapagan

TODO.md

@@ -13,7 +13,7 @@ These below are from Issues or PRs in the original repository.
 - add an option to have a separate logging file for cache hits and misses?
 - remove creating a test Redis from `redis.py`. This should not be done in the
   production logic, but set up in the test logic.
-- add a `cache_key` or `tag` parameter to the `cache` decorator to allow for
-  custom cache keys
 - remove the FakeRedis from the `_connect_` function. This should be set up in
   the test logic not production code.
+- catch invalid cache type exceptions and raise a more informative error
+  message.

fastapi_redis_cache/cache.py

@@ -1,5 +1,7 @@
 """The main cache decorator code and helpers."""
 
+from __future__ import annotations
+
 import asyncio
 from datetime import timedelta
 from functools import partial, update_wrapper, wraps
@@ -23,14 +25,19 @@
 
 
 def cache(
-    *, expire: Union[int, timedelta] = ONE_YEAR_IN_SECONDS
+    *,
+    expire: Union[int, timedelta] = ONE_YEAR_IN_SECONDS,
+    tag: str | None = None,
 ) -> Callable[..., Any]:
     """Enable caching behavior for the decorated function.
 
     Args:
         expire (Union[int, timedelta], optional): The number of seconds
             from now when the cached response should expire. Defaults to
             31,536,000 seconds (i.e., the number of seconds in one year).
+        tag (str, optional): A tag to associate with the cached response. This
+            can later be used to invalidate all cached responses with the same
+            tag, or for further fine-grained cache expiry. Defaults to None.
     """
 
     def outer_wrapper(func: Callable[..., Any]) -> Callable[..., Any]:
@@ -61,7 +68,7 @@ async def inner_wrapper(
                 # if the redis client is not connected or request is not
                 # cacheable, no caching behavior is performed.
                 return await get_api_response_async(func, *args, **kwargs)
-            key = redis_cache.get_cache_key(func, *args, **kwargs)
+            key = redis_cache.get_cache_key(tag, func, *args, **kwargs)
             ttl, in_cache = redis_cache.check_cache(key)
             if in_cache:
                 redis_cache.set_response_headers(
@@ -93,6 +100,10 @@ async def inner_wrapper(
             response_data = await get_api_response_async(func, *args, **kwargs)
             ttl = calculate_ttl(expire)
             cached = redis_cache.add_to_cache(key, response_data, ttl)
+            if tag:
+                # if tag is provided, add the key to the tag set. This should
+                # help us search quicker for keys to invalidate.
+                redis_cache.add_key_to_tag_set(tag, key)
             if cached:
                 redis_cache.set_response_headers(
                     response,

fastapi_redis_cache/client.py

@@ -135,13 +135,33 @@ def request_is_not_cacheable(self, request: Request) -> bool:
         )
 
     def get_cache_key(
-        self, func: Callable[..., Any], *args: Any, **kwargs: Any
+        self,
+        tag: str | None,
+        func: Callable[..., Any],
+        *args: Any,
+        **kwargs: Any,
     ) -> str:
         """Return a key to use for caching the response of a function."""
         return get_cache_key(
-            self.prefix, self.ignore_arg_types, func, *args, **kwargs
+            self.prefix, tag, self.ignore_arg_types, func, *args, **kwargs
         )
 
+    def add_key_to_tag_set(self, tag: str, key: str) -> None:
+        """Add a key to a set of keys associated with a tag.
+
+        Searching for keys to invalidate is faster when they are grouped by tag
+        as it reduces the number of keys to search through.
+
+        However, keys are not removed from the tag set when they expire so will
+        need to handle possibly stale keys when invalidating.
+        """
+        if self.redis:
+            self.redis.sadd(tag, key)
+
+    def get_tagged_keys(self, tag: str) -> set[str]:
+        """Return a set of keys associated with a tag."""
+        return self.redis.smembers(tag) if self.redis else set()
+
     def check_cache(self, key: str) -> tuple[int, str]:
         """Check if `key` is in the cache and return its TTL and value."""
         if not self.redis:

fastapi_redis_cache/key_gen.py

@@ -1,20 +1,23 @@
 """Helper functions for generating cache keys."""
 
+from __future__ import annotations
+
 from inspect import Signature, signature
 from typing import TYPE_CHECKING, Any, Callable
 
 from fastapi import Request, Response
 
-from fastapi_redis_cache.types import ArgType, SigParameters
-
 if TYPE_CHECKING:  # pragma: no cover
     from collections import OrderedDict
 
+    from fastapi_redis_cache.types import ArgType, SigParameters
+
 ALWAYS_IGNORE_ARG_TYPES = [Response, Request]
 
 
 def get_cache_key(  # noqa: D417
     prefix: str,
+    tag: str | None,
     ignore_arg_types: list[ArgType],
     func: Callable[..., Any],
     *args: list[Any],
@@ -25,6 +28,9 @@ def get_cache_key(  # noqa: D417
     Args:
         prefix (`str`): Customizable namespace value that will prefix all cache
             keys.
+        tag (`str`): Customizable tag value that will be inserted into the
+            cache key. This can be used to group related keys together or to
+            help expire a key in other routes.
         ignore_arg_types (`list[ArgType]`): Each argument to the API endpoint
             function is used to compose the cache key by calling `str(arg)`. If
             there are any keys that should not be used in this way (i.e.,
@@ -42,17 +48,18 @@ def get_cache_key(  # noqa: D417
     ignore_arg_types.extend(ALWAYS_IGNORE_ARG_TYPES)
     ignore_arg_types = list(set(ignore_arg_types))
     prefix = f"{prefix}:" if prefix else ""
+    tag_string = f"::{tag}" if tag else ""
 
     sig = signature(func)
     sig_params = sig.parameters
     func_args = get_func_args(sig, *args, **kwargs)
     args_str = get_args_str(sig_params, func_args, ignore_arg_types)
-    return f"{prefix}{func.__module__}.{func.__name__}({args_str})"
+    return f"{prefix}{func.__module__}.{func.__name__}({args_str}){tag_string}"
 
 
 def get_func_args(
     sig: Signature, *args: list[Any], **kwargs: dict[Any, Any]
-) -> "OrderedDict[str, Any]":
+) -> OrderedDict[str, Any]:
     """Return a dict object containing name and value of function arguments."""
     func_args = sig.bind(*args, **kwargs)
     func_args.apply_defaults()
@@ -61,7 +68,7 @@ def get_func_args(
 
 def get_args_str(
     sig_params: SigParameters,
-    func_args: "OrderedDict[str, Any]",
+    func_args: OrderedDict[str, Any],
     ignore_arg_types: list[ArgType],
 ) -> str:
     """Return a string with name and value of all args.

fastapi_redis_cache/util.py

@@ -1,5 +1,7 @@
 """Define utility functions for the fastapi_redis_cache package."""
 
+from __future__ import annotations
+
 import json
 from datetime import date, datetime
 from decimal import Decimal
@@ -78,3 +80,8 @@ def serialize_json(json_dict: dict[str, Any]) -> str:
 def deserialize_json(json_str: str) -> Any:  # noqa: ANN401
     """Deserialize a JSON string to a dictionary."""
     return json.loads(json_str, object_hook=object_hook)
+
+
+def get_tag_from_key(key: str) -> str | None:
+    """Return the tag from the key or None if not found."""
+    return key.split("::")[-1] if "::" in key else None

requirements-dev.txt

@@ -59,7 +59,7 @@ pynacl==1.5.0 ; python_version >= "3.9" and python_version < "4.0"
 pytest-asyncio==0.21.1 ; python_version >= "3.9" and python_version < "4.0"
 pytest-cov==4.1.0 ; python_version >= "3.9" and python_version < "4.0"
 pytest-env==1.1.3 ; python_version >= "3.9" and python_version < "4.0"
-pytest-mock==3.12.0 ; python_version >= "3.9" and python_version < "4.0"
+pytest-mock==3.14.0 ; python_version >= "3.9" and python_version < "4.0"
 pytest-order==1.2.0 ; python_version >= "3.9" and python_version < "4.0"
 pytest-randomly==3.15.0 ; python_version >= "3.9" and python_version < "4.0"
 pytest-reverse==1.7.0 ; python_version >= "3.9" and python_version < "4.0"
@@ -74,7 +74,7 @@ redis==5.0.3 ; python_version >= "3.9" and python_version < "4.0"
 requests==2.31.0 ; python_version >= "3.9" and python_version < "4.0"
 rich==13.7.1 ; python_version >= "3.9" and python_version < "4.0"
 rtoml==0.9.0 ; python_version >= "3.9" and python_version < "4.0"
-ruff==0.3.3 ; python_version >= "3.9" and python_version < "4.0"
+ruff==0.3.4 ; python_version >= "3.9" and python_version < "4.0"
 setuptools==69.2.0 ; python_version >= "3.9" and python_version < "4.0"
 simple-toml-settings==0.6.0 ; python_version >= "3.9" and python_version < "4.0"
 six==1.16.0 ; python_version >= "3.9" and python_version < "4.0"

tests/live_test.py

@@ -50,7 +50,7 @@ def cache_never_expire(
 
 
 @app.get("/cache_expires")
-@cache(expire=timedelta(seconds=5))
+@cache(expire=timedelta(seconds=5), tag="test_tag_1")
 async def cache_expires() -> dict[str, Union[bool, str]]:
     """Route where the cache expires after 5 seconds."""
     return {
@@ -60,7 +60,7 @@ async def cache_expires() -> dict[str, Union[bool, str]]:
 
 
 @app.get("/cache_json_encoder")
-@cache()
+@cache(tag="test_tag_1")
 def cache_json_encoder() -> (
     dict[str, Union[bool, str, datetime, date, Decimal]]
 ):
@@ -77,7 +77,7 @@ def cache_json_encoder() -> (
 
 
 @app.get("/cache_one_hour")
-@cache_one_hour()
+@cache_one_hour(tag="test_tag_2")
 def partial_cache_one_hour(response: Response) -> dict[str, Union[bool, str]]:
     """Route where the cache expires after one hour."""
     return {