Add support for deleting cached views when is set to query_params=True. Fixes #243

Author: sh4nks

CHANGES.rst

@@ -19,6 +19,9 @@ Unreleased
 - Send Signals for cache hits and misses. :pr:`#237` and :pr:`667`
 - Include ``key_prefix`` when building ``@cached(query_string=True)`` cache
   keys. :issue:`302`
+- Add ``Cache.delete_cached()`` and extend ``make_cache_key()`` with ``path`` and ``query_args``
+  arguments to make deleting views decorated with ``cached(query_string=True)`` possible.
+  :issue:`243`
 - Use ``hashlib.sha256`` instead of ``hashlib.md5`` for hashing the cache keys.
   This changes the generated keys, so entries cached by an earlier version become
   obsolete. If you wish to still use hashlib.md5 set the config

docs/api.rst

@@ -15,8 +15,8 @@ Cache API
 .. module:: flask_caching
 .. autoclass:: Cache
    :members: cache, init_app, get, set, add, delete, get_many, set_many,
-             delete_many, get_dict, unlink, has, clear, cached, memoize,
-             delete_memoized, delete_memoized_verhash
+             delete_many, get_dict, unlink, has, clear, cached, delete_cached,
+             memoize, delete_memoized, delete_memoized_verhash
 
 
 .. autoclass:: CachedResponse

docs/usage.rst

@@ -43,6 +43,52 @@ a subclass of `flask.Response`::
     ``@route`` decorator, and not the result of your view function.
 
 
+Deleting Cached Views
+`````````````````````
+
+When you want to remove the value of a cached view you can use :meth:`~Cache.delete_cached`
+instead of :meth:`~Cache.delete`. :meth:`~Cache.delete_cached`. builds the key of the
+decorated view and deletes the cache in one go::
+
+    @app.route("/user/<name>")
+    @cache.cached(timeout=50)
+    def user(name):
+        return render_template("user.html", name=name)
+
+    cache.delete_cached(user, "/user/Fred")
+
+Outside of a request context the view doesn't know which request was used to build
+the cache key. So to make it work outside of a request context you have to pass the
+``path``. You can also use the view function and the named arguments of the view
+in which case the path is built using ``url_for()``::
+
+    cache.delete_cached(user, name="bob")
+
+When you cache views with ``query_string=True`` you also have to pass the query string/args
+because otherwise the cache key cannot be built::
+
+    @app.route("/works")
+    @cache.cached(timeout=50, query_string=True)
+    def works():
+        return do_search(request.args)
+
+    cache.delete_cached(works, "/works", "limit=15&mock=true")
+
+You can use either pass the query string as a string, a mapping or an iterable of
+``(key, value)`` pairs::
+
+    cache.delete_cached(works, "/works", {"limit": 15, "mock": "true"})
+
+Additionally, ``path`` and ``query_args`` are also supported by the views ``make_cache_key()``::
+
+    key = works.make_cache_key(path="/works", query_args={"limit": 15})
+
+.. note::
+
+    If you view has arguments named ``path`` or ``query_args`` you have to build the key
+    from via the request context!
+
+
 Caching Pluggable View Classes
 ------------------------------
 
@@ -168,7 +214,7 @@ every time this information is needed you might do something like the following:
 
 
 
-Deleting memoize cache
+Deleting Memoize Cache
 ``````````````````````
 
 .. versionadded:: 0.2
@@ -384,6 +430,9 @@ string instead of ``key_prefix``. The arguments are sorted before hashing, so
     def search():
         return do_search(request.args)
 
+Deleting such an entry needs the query string as well, see
+`Deleting cached views`_.
+
 
 response_hit_indication
 ```````````````````````
@@ -468,7 +517,8 @@ Considering we have ``render_form_field`` and ``render_submit`` macros::
 Clearing Cache
 --------------
 
-See :meth:`~Cache.clear`.
+See :meth:`~Cache.clear`. To delete the entry of a single view see
+`Deleting cached views`_.
 
 Here's an example script to empty your application's cache:
 

src/flask_caching/__init__.py

@@ -17,6 +17,7 @@
 import warnings
 from collections import OrderedDict
 from collections.abc import Callable
+from collections.abc import Iterable
 from typing import Any
 from typing import cast
 from typing import Concatenate
@@ -26,7 +27,6 @@
 from typing import TypeAlias
 from typing import TypeVar
 
-from blinker import Namespace
 from cachelib.serializers import BaseSerializer
 from flask import current_app
 from flask import Flask
@@ -36,19 +36,24 @@
 from flask import url_for
 from werkzeug.utils import import_string
 
-from flask_caching.backends.base import BaseCache
-from flask_caching.backends.simplecache import SimpleCache
-from flask_caching.utils import function_namespace
-from flask_caching.utils import get_arg_default
-from flask_caching.utils import get_arg_names
-from flask_caching.utils import get_id
-from flask_caching.utils import join_generator
-from flask_caching.utils import make_template_fragment_key as make_template_fragment_key
-from flask_caching.utils import wants_args
+from .backends.base import BaseCache
+from .backends.simplecache import SimpleCache
+from .signals import cache_memoize_hit as cache_memoize_hit
+from .signals import cache_memoize_miss as cache_memoize_miss
+from .signals import cache_view_hit as cache_view_hit
+from .signals import cache_view_miss as cache_view_miss
+from .utils import _QueryArgs
+from .utils import function_namespace
+from .utils import get_arg_default
+from .utils import get_arg_names
+from .utils import get_id
+from .utils import join_generator
+from .utils import make_template_fragment_key as make_template_fragment_key
+from .utils import query_args_as_pairs
+from .utils import wants_args
 
 logger = logging.getLogger(__name__)
 
-_signals = Namespace()
 
 # The initial version timeout of a memoize version key. Will be overwritten on the first
 # write with the memoize value timeout
@@ -63,6 +68,7 @@
     hashlib.md5,
 ]
 
+
 P = ParamSpec("P")
 # The parameters left over after ``__get__`` binds the instance.
 P2 = ParamSpec("P2")
@@ -73,11 +79,6 @@
 T_co = TypeVar("T_co", covariant=True)
 T_contra = TypeVar("T_contra", contravariant=True)
 
-cache_view_hit = _signals.signal("cache-view-hit")
-cache_view_miss = _signals.signal("cache-view-miss")
-cache_memoize_hit = _signals.signal("cache-memoize-hit")
-cache_memoize_miss = _signals.signal("cache-memoize-miss")
-
 
 class _BoundCachedFunction(Protocol[T_contra, P, T_co]):
     """The type of a :meth:`Cache.cached` method accessed on an instance."""
@@ -160,6 +161,10 @@ def __get__(self, instance: Any, owner: type | None = None, /) -> Any: ...
     "_MemoizedFunction[..., Any] | _BoundMemoizedFunction[Any, ..., Any]"
 )
 
+_AnyCachedFunction: TypeAlias = (
+    "_CachedFunction[..., Any] | _BoundCachedFunction[Any, ..., Any]"
+)
+
 
 class CachedResponse(Response):
     """
@@ -463,6 +468,20 @@ def get_list():
 
                     readable and writable
 
+                    Outside of a request context, pass ``path`` to build the
+                    key for a given ``request.path`` and, for
+                    ``query_string=True``, ``query_args`` to build the key for
+                    a given query string::
+
+                        key = view.make_cache_key(
+                            path="/works", query_args="limit=15&mock=true"
+                        )
+                        cache.delete(key)
+
+                    ``query_args`` accepts a query string, a mapping or an
+                    iterable of ``(key, value)`` pairs. See
+                    :meth:`delete_cached` for the shorthand.
+
         :param timeout: Default None. If set to an integer, will cache for that
                         amount of time. Unit of time is in seconds.
 
@@ -636,9 +655,20 @@ def default_make_cache_key(*args: Any, **kwargs: Any) -> str:
                     kwargs[arg_name] = arg
 
                 use_request = kwargs.pop("use_request", False)
-                return _make_cache_key(args, kwargs, use_request=use_request)
+                path = kwargs.pop("path", None)
+                query_args = kwargs.pop("query_args", None)
+                return _make_cache_key(
+                    args,
+                    kwargs,
+                    use_request=use_request,
+                    path=path,
+                    query_args=query_args,
+                )
 
-            def _make_cache_key_query_string() -> str:
+            def _make_cache_key_query_string(
+                path: str | None = None,
+                query_args: _QueryArgs | None = None,
+            ) -> str:
                 """Create consistent keys for query string arguments.
 
                 Produces the same cache key regardless of argument order, e.g.,
@@ -657,9 +687,12 @@ def _make_cache_key_query_string() -> str:
                 # are the same, regardless of the order in which they are
                 # provided.
 
-                args_as_sorted_tuple = tuple(
-                    sorted(pair for pair in request.args.items(multi=True))
-                )
+                if query_args is None:
+                    pairs: Iterable[tuple[str, str]] = request.args.items(multi=True)
+                else:
+                    pairs = query_args_as_pairs(query_args)
+
+                args_as_sorted_tuple = tuple(sorted(pair for pair in pairs))
                 # ... now hash the sorted (key, value) tuple so it can be
                 # used as a key for cache. Turn them into bytes so that the
                 # hash function will accept them
@@ -678,26 +711,37 @@ def _make_cache_key_query_string() -> str:
                 if callable(key_prefix):
                     cache_key = key_prefix()
                 elif "%s" in key_prefix:
-                    cache_key = key_prefix % request.path
+                    cache_key = key_prefix % (request.path if path is None else path)
                 else:
                     cache_key = key_prefix
 
                 return cache_key + cache_hash
 
             def _make_cache_key(
-                args: tuple[Any, ...], kwargs: dict[str, Any], use_request: bool
+                args: tuple[Any, ...],
+                kwargs: dict[str, Any],
+                use_request: bool,
+                path: str | None = None,
+                query_args: _QueryArgs | None = None,
             ) -> str:
                 if query_string:
-                    return _make_cache_key_query_string()
+                    return _make_cache_key_query_string(path, query_args)
                 else:
                     cache_key: str
                     if callable(key_prefix):
                         cache_key = key_prefix()
                     elif "%s" in key_prefix:
-                        if use_request:
+                        if path is not None:
+                            cache_key = key_prefix % path
+                        elif use_request:
                             cache_key = key_prefix % request.path
                         else:
-                            cache_key = key_prefix % url_for(f.__name__, **kwargs)
+                            # Outside of a request context ``url_for``
+                            # defaults to an external URL, which would not
+                            # match the key the request stored.
+                            cache_key = key_prefix % url_for(
+                                f.__name__, _external=False, **kwargs
+                            )
                     else:
                         cache_key = key_prefix
 
@@ -720,6 +764,39 @@ def _make_cache_key(
 
         return decorator
 
+    def delete_cached(
+        self,
+        f: _AnyCachedFunction,
+        path: str | None = None,
+        query_args: _QueryArgs | None = None,
+        **kwargs: Any,
+    ) -> bool:
+        """Delete the cached value of a :meth:`cached` decorated function.
+
+        Example::
+
+            @app.route("/works")
+            @cache.cached(query_string=True)
+            def view_works():
+                return do_search(request.args)
+
+            cache.delete_cached(view_works, "/works", {"limit": 15})
+
+        If you are calling this outside of a request context pass ``path`` and
+        when the function was decorated with ``query_string=True`` you also
+        have to pass ``query_args``.
+
+        :param f: The decorated function whose cached value to delete.
+        :param path: The ``request.path`` the value was cached for.
+        :param query_args: The query string the value was cached for, as a
+                           query string, a mapping or an iterable of
+                           ``(key, value)`` pairs. Only used when the function
+                           was decorated with ``query_string=True``.
+        :param kwargs: The view arguments, passed to ``url_for()`` to build
+                       the path when ``path`` is not given.
+        """
+        return self.delete(f.make_cache_key(path=path, query_args=query_args, **kwargs))
+
     def _memvname(self, funcname: str) -> str:
         return funcname + "_memver"
 

src/flask_caching/signals.py

@@ -0,0 +1,34 @@
+"""
+flask_caching.signals
+~~~~~~~~~~~~~~~~~~~~~
+
+The signals for Flask-Caching.
+
+:copyright: (c) 2026 by Peter Justin
+:license: BSD, see LICENSE for more details.
+"""
+
+from blinker import Namespace
+
+_signals = Namespace()
+
+#: Sent when a view decorated with :meth:`~Cache.cached` is served from the
+#: cache. It is passed ``cache``, the :class:`Cache` instance, ``cache_key``,
+#: the key the response was found under, and ``args`` and ``kwargs``, the
+#: arguments the view was called with.
+cache_view_hit = _signals.signal("cache-view-hit")
+
+#: Sent when a view decorated with :meth:`~Cache.cached` is not found in the
+#: cache and has to be called. It is passed the same arguments as
+#: :data:`cache_view_hit`.
+cache_view_miss = _signals.signal("cache-view-miss")
+
+#: Sent when a function decorated with :meth:`~Cache.memoize` is served from
+#: the cache. In addition to the arguments passed to :data:`cache_view_hit`,
+#: it is passed ``f``, the undecorated function.
+cache_memoize_hit = _signals.signal("cache-memoize-hit")
+
+#: Sent when a function decorated with :meth:`~Cache.memoize` is not found in
+#: the cache and has to be called. It is passed the same arguments as
+#: :data:`cache_memoize_hit`.
+cache_memoize_miss = _signals.signal("cache-memoize-miss")