Simplify cache namespace and key encoding logic for v1

CHANGES.rst

@@ -15,6 +15,10 @@ There are a number of backwards-incompatible changes. These points should help w
 * The ``key`` parameter has been removed from the ``cached`` decorator. The behaviour can be easily reimplemented with ``key_builder=lambda *a, **kw: "foo"``
 * When using the ``key_builder`` parameter in ``@multicached``, the function will now return the original, unmodified keys, only using the transformed keys in the cache (this has always been the documented behaviour, but not the implemented behaviour).
 * ``BaseSerializer`` is now an ``ABC``, so cannot be instantiated directly.
+* The logic for encoding a cache key and selecting the key's namespace is now encapsulated in
+the ``build_key(key, namespace)`` member of BaseCache (and its backend subclasses). Now
+creating a cache with a custom ``key_builder`` argument simply requires that function to
+return any string mapping from the ``key`` and optional ``namespace`` parameters.
 
 
 0.12.0 (2023-01-13)

aiocache/backends/memcached.py

@@ -1,4 +1,5 @@
 import asyncio
+from typing import Optional
 
 import aiomcache
 
@@ -130,7 +131,7 @@ class MemcachedCache(MemcachedBackend):
     :param serializer: obj derived from :class:`aiocache.serializers.BaseSerializer`.
     :param plugins: list of :class:`aiocache.plugins.BasePlugin` derived classes.
     :param namespace: string to use as default prefix for the key used in all operations of
-        the backend. Default is None
+        the backend. Default is an empty string, "".
     :param timeout: int or float in seconds specifying maximum timeout for the operations to last.
         By default its 5.
     :param endpoint: str with the endpoint to connect to. Default is 127.0.0.1.
@@ -147,8 +148,8 @@ def __init__(self, serializer=None, **kwargs):
     def parse_uri_path(cls, path):
         return {}
 
-    def _build_key(self, key, namespace=None):
-        ns_key = super()._build_key(key, namespace=namespace).replace(" ", "_")
+    def build_key(self, key: str, namespace: Optional[str] = None) -> str:
+        ns_key = super().build_key(key, namespace=namespace).replace(" ", "_")
         return str.encode(ns_key)
 
     def __repr__(self):  # pragma: no cover

aiocache/backends/memory.py

@@ -118,7 +118,7 @@ class SimpleMemoryCache(SimpleMemoryBackend):
     :param serializer: obj derived from :class:`aiocache.serializers.BaseSerializer`.
     :param plugins: list of :class:`aiocache.plugins.BasePlugin` derived classes.
     :param namespace: string to use as default prefix for the key used in all operations of
-        the backend. Default is None.
+        the backend. Default is an empty string, "".
     :param timeout: int or float in seconds specifying maximum timeout for the operations to last.
         By default its 5.
     """

aiocache/backends/redis.py

@@ -1,11 +1,12 @@
 import itertools
 import warnings
+from typing import Callable, Optional
 
 import redis.asyncio as redis
 from redis.exceptions import ResponseError as IncrbyException
 
-from aiocache.base import BaseCache, _ensure_key
-from aiocache.serializers import JsonSerializer
+from aiocache.base import BaseCache
+from aiocache.serializers import BaseSerializer, JsonSerializer
 
 
 _NOT_SET = object()
@@ -186,7 +187,7 @@ class RedisCache(RedisBackend):
     :param serializer: obj derived from :class:`aiocache.serializers.BaseSerializer`.
     :param plugins: list of :class:`aiocache.plugins.BasePlugin` derived classes.
     :param namespace: string to use as default prefix for the key used in all operations of
-        the backend. Default is None.
+        the backend. Default is an empty string, "".
     :param timeout: int or float in seconds specifying maximum timeout for the operations to last.
         By default its 5.
     :param endpoint: str with the endpoint to connect to. Default is "127.0.0.1".
@@ -199,8 +200,19 @@ class RedisCache(RedisBackend):
 
     NAME = "redis"
 
-    def __init__(self, serializer=None, **kwargs):
-        super().__init__(serializer=serializer or JsonSerializer(), **kwargs)
+    def __init__(
+        self,
+        serializer: Optional[BaseSerializer] = None,
+        namespace: str = "",
+        key_builder: Optional[Callable[[str, str], str]] = None,
+        **kwargs,
+    ):
+        super().__init__(
+            serializer=serializer or JsonSerializer(),
+            namespace=namespace,
+            key_builder=key_builder or (
+                lambda key, namespace="": f"{namespace}:{key}" if namespace else key),
+            **kwargs)
 
     @classmethod
     def parse_uri_path(cls, path):
@@ -218,14 +230,8 @@ def parse_uri_path(cls, path):
             options["db"] = db
         return options
 
-    def _build_key(self, key, namespace=None):
-        if namespace is not None:
-            return "{}{}{}".format(
-                namespace, ":" if namespace else "", _ensure_key(key))
-        if self.namespace is not None:
-            return "{}{}{}".format(
-                self.namespace, ":" if self.namespace else "", _ensure_key(key))
-        return key
+    def _build_key_default(self, key: str, namespace: str = "") -> str:
+        return f"{namespace}:{key}" if namespace else key
 
     def __repr__(self):  # pragma: no cover
         return "RedisCache ({}:{})".format(self.endpoint, self.port)

aiocache/base.py

@@ -5,9 +5,10 @@
 import time
 from enum import Enum
 from types import TracebackType
-from typing import Callable, Optional, Set, Type
+from typing import Any, Callable, List, Optional, Set, Type
 
-from aiocache import serializers
+# from aiocache.plugins import BasePlugin
+from aiocache.serializers import BaseSerializer, StringSerializer
 
 
 logger = logging.getLogger(__name__)
@@ -97,9 +98,9 @@ class BaseCache:
     :param plugins: list of :class:`aiocache.plugins.BasePlugin` derived classes. Default is empty
         list.
     :param namespace: string to use as default prefix for the key used in all operations of
-        the backend. Default is None
+        the backend. Default is an empty string, "".
     :param key_builder: alternative callable to build the key. Receives the key and the namespace
-        as params and should return something that can be used as key by the underlying backend.
+        as params and should return a string that can be used as a key by the underlying backend.
     :param timeout: int or float in seconds specifying maximum timeout for the operations to last.
         By default its 5. Use 0 or None if you want to disable it.
     :param ttl: int the expiration time in seconds to use as a default in all operations of
@@ -109,18 +110,26 @@ class BaseCache:
     NAME: str
 
     def __init__(
-        self, serializer=None, plugins=None, namespace=None, key_builder=None, timeout=5, ttl=None
+        self,
+        serializer: Optional[BaseSerializer] = None,
+        plugins: Optional[List[Any]] = None,  # aiocache.plugins depends on aiocache.base
+        namespace: str = "",
+        key_builder: Optional[Callable[[str, str], str]] = None,
+        timeout: Optional[float] = 5,
+        ttl: Optional[float] = None,
     ):
-        self.timeout = float(timeout) if timeout is not None else timeout
-        self.namespace = namespace
-        self.ttl = float(ttl) if ttl is not None else ttl
-        self.build_key = key_builder or self._build_key
+        self.timeout: Optional[float] = float(timeout) if timeout is not None else None
+        self.ttl: Optional[float] = float(ttl) if ttl is not None else None
 
-        self._serializer = None
-        self.serializer = serializer or serializers.StringSerializer()
+        self.namespace: str = namespace
+        self._build_key: Callable[[str, str], str] = key_builder or (
+            lambda key, namespace="": f"{namespace}{key}")
 
-        self._plugins = None
-        self.plugins = plugins or []
+        self._serializer: Optional[BaseSerializer] = None
+        self.serializer: BaseSerializer = serializer or StringSerializer()
+
+        self._plugins: List[Any] = None
+        self.plugins: List[Any] = plugins or []
 
     @property
     def serializer(self):
@@ -163,8 +172,7 @@ async def add(self, key, value, ttl=SENTINEL, dumps_fn=None, namespace=None, _co
         """
         start = time.monotonic()
         dumps = dumps_fn or self._serializer.dumps
-        ns = namespace if namespace is not None else self.namespace
-        ns_key = self.build_key(key, namespace=ns)
+        ns_key = self.build_key(key, namespace=namespace)
 
         await self._add(ns_key, dumps(value), ttl=self._get_ttl(ttl), _conn=_conn)
 
@@ -193,8 +201,7 @@ async def get(self, key, default=None, loads_fn=None, namespace=None, _conn=None
         """
         start = time.monotonic()
         loads = loads_fn or self._serializer.loads
-        ns = namespace if namespace is not None else self.namespace
-        ns_key = self.build_key(key, namespace=ns)
+        ns_key = self.build_key(key, namespace=namespace)
 
         value = loads(await self._get(ns_key, encoding=self.serializer.encoding, _conn=_conn))
 
@@ -225,9 +232,8 @@ async def multi_get(self, keys, loads_fn=None, namespace=None, _conn=None):
         """
         start = time.monotonic()
         loads = loads_fn or self._serializer.loads
-        ns = namespace if namespace is not None else self.namespace
 
-        ns_keys = [self.build_key(key, namespace=ns) for key in keys]
+        ns_keys = [self.build_key(key, namespace=namespace) for key in keys]
         values = [
             loads(value)
             for value in await self._multi_get(
@@ -270,8 +276,7 @@ async def set(
         """
         start = time.monotonic()
         dumps = dumps_fn or self._serializer.dumps
-        ns = namespace if namespace is not None else self.namespace
-        ns_key = self.build_key(key, namespace=ns)
+        ns_key = self.build_key(key, namespace=namespace)
 
         res = await self._set(
             ns_key, dumps(value), ttl=self._get_ttl(ttl), _cas_token=_cas_token, _conn=_conn
@@ -304,11 +309,10 @@ async def multi_set(self, pairs, ttl=SENTINEL, dumps_fn=None, namespace=None, _c
         """
         start = time.monotonic()
         dumps = dumps_fn or self._serializer.dumps
-        ns = namespace if namespace is not None else self.namespace
 
         tmp_pairs = []
         for key, value in pairs:
-            tmp_pairs.append((self.build_key(key, namespace=ns), dumps(value)))
+            tmp_pairs.append((self.build_key(key, namespace=namespace), dumps(value)))
 
         await self._multi_set(tmp_pairs, ttl=self._get_ttl(ttl), _conn=_conn)
 
@@ -339,8 +343,7 @@ async def delete(self, key, namespace=None, _conn=None):
         :raises: :class:`asyncio.TimeoutError` if it lasts more than self.timeout
         """
         start = time.monotonic()
-        ns = namespace if namespace is not None else self.namespace
-        ns_key = self.build_key(key, namespace=ns)
+        ns_key = self.build_key(key, namespace=namespace)
         ret = await self._delete(ns_key, _conn=_conn)
         logger.debug("DELETE %s %d (%.4f)s", ns_key, ret, time.monotonic() - start)
         return ret
@@ -364,8 +367,7 @@ async def exists(self, key, namespace=None, _conn=None):
         :raises: :class:`asyncio.TimeoutError` if it lasts more than self.timeout
         """
         start = time.monotonic()
-        ns = namespace if namespace is not None else self.namespace
-        ns_key = self.build_key(key, namespace=ns)
+        ns_key = self.build_key(key, namespace=namespace)
         ret = await self._exists(ns_key, _conn=_conn)
         logger.debug("EXISTS %s %d (%.4f)s", ns_key, ret, time.monotonic() - start)
         return ret
@@ -392,8 +394,7 @@ async def increment(self, key, delta=1, namespace=None, _conn=None):
         :raises: :class:`TypeError` if value is not incrementable
         """
         start = time.monotonic()
-        ns = namespace if namespace is not None else self.namespace
-        ns_key = self.build_key(key, namespace=ns)
+        ns_key = self.build_key(key, namespace=namespace)
         ret = await self._increment(ns_key, delta, _conn=_conn)
         logger.debug("INCREMENT %s %d (%.4f)s", ns_key, ret, time.monotonic() - start)
         return ret
@@ -418,8 +419,7 @@ async def expire(self, key, ttl, namespace=None, _conn=None):
         :raises: :class:`asyncio.TimeoutError` if it lasts more than self.timeout
         """
         start = time.monotonic()
-        ns = namespace if namespace is not None else self.namespace
-        ns_key = self.build_key(key, namespace=ns)
+        ns_key = self.build_key(key, namespace=namespace)
         ret = await self._expire(ns_key, ttl, _conn=_conn)
         logger.debug("EXPIRE %s %d (%.4f)s", ns_key, ret, time.monotonic() - start)
         return ret
@@ -498,12 +498,13 @@ async def close(self, *args, _conn=None, **kwargs):
     async def _close(self, *args, **kwargs):
         pass
 
-    def _build_key(self, key, namespace=None):
-        if namespace is not None:
-            return "{}{}".format(namespace, _ensure_key(key))
-        if self.namespace is not None:
-            return "{}{}".format(self.namespace, _ensure_key(key))
-        return key
+    def build_key(self, key: str, namespace: Optional[str] = None) -> str:
+        key_name = key.value if isinstance(key, Enum) else key
+        ns = namespace if namespace is not None else self.namespace
+        return self._build_key(key_name, namespace=ns)
+
+    def _build_key_default(self, key: str, namespace: str = "") -> str:
+        return f"{namespace}{key}"
 
     def _get_ttl(self, ttl):
         return ttl if ttl is not SENTINEL else self.ttl
@@ -550,12 +551,5 @@ async def _do_inject_conn(self, *args, **kwargs):
         return _do_inject_conn
 
 
-def _ensure_key(key):
-    if isinstance(key, Enum):
-        return key.value
-    else:
-        return key
-
-
 for cmd in API.CMDS:
     setattr(_Conn, cmd.__name__, _Conn._inject_conn(cmd.__name__))

aiocache/decorators.py

@@ -35,7 +35,7 @@ class cached:
 
     :param ttl: int seconds to store the function call. Default is None which means no expiration.
     :param namespace: string to use as default prefix for the key used in all operations of
-        the backend. Default is None
+        the backend. Default is an empty string, "".
     :param key_builder: Callable that allows to build the function dynamically. It receives
         the function plus same args and kwargs passed to the function.
         This behavior is necessarily different than ``BaseCache.build_key()``
@@ -176,7 +176,7 @@ class cached_stampede(cached):
     :param ttl: int seconds to store the function call. Default is None which means no expiration.
     :param key_from_attr: str arg or kwarg name from the function to use as a key.
     :param namespace: string to use as default prefix for the key used in all operations of
-        the backend. Default is None
+        the backend. Default is an empty string, "".
     :param key_builder: Callable that allows to build the function dynamically. It receives
         the function plus same args and kwargs passed to the function.
         This behavior is necessarily different than ``BaseCache.build_key()``
@@ -278,7 +278,7 @@ class multi_cached:
     :param keys_from_attr: name of the arg or kwarg in the decorated callable that contains
         an iterable that yields the keys returned by the decorated callable.
     :param namespace: string to use as default prefix for the key used in all operations of
-        the backend. Default is None
+        the backend. Default is an empty string, "".
     :param key_builder: Callable that enables mapping the decorated function's keys to the keys
         used by the cache. Receives a key from the iterable corresponding to
         ``keys_from_attr``, the decorated callable, and the positional and keyword arguments

tests/acceptance/test_decorators.py

@@ -5,8 +5,7 @@
 import pytest
 
 from aiocache import cached, cached_stampede, multi_cached
-from aiocache.base import _ensure_key
-from ..utils import Keys
+from ..utils import Keys, ensure_key
 
 
 async def return_dict(keys=None):
@@ -164,15 +163,15 @@ async def fn(keys):
 
     async def test_multi_cached_key_builder(self, cache):
         def build_key(key, f, self, keys, market="ES"):
-            return "{}_{}_{}".format(f.__name__, _ensure_key(key), market)
+            return "{}_{}_{}".format(f.__name__, ensure_key(key), market)
 
         @multi_cached(keys_from_attr="keys", key_builder=build_key)
         async def fn(self, keys, market="ES"):
             return {Keys.KEY: 1, Keys.KEY_1: 2}
 
         await fn("self", keys=[Keys.KEY, Keys.KEY_1])
-        assert await cache.exists("fn_" + _ensure_key(Keys.KEY) + "_ES") is True
-        assert await cache.exists("fn_" + _ensure_key(Keys.KEY_1) + "_ES") is True
+        assert await cache.exists("fn_" + ensure_key(Keys.KEY) + "_ES") is True
+        assert await cache.exists("fn_" + ensure_key(Keys.KEY_1) + "_ES") is True
 
     async def test_multi_cached_skip_keys(self, cache):
         @multi_cached(keys_from_attr="keys", skip_cache_func=lambda _, v: v is None)

tests/acceptance/test_lock.py

@@ -200,7 +200,7 @@ def lock(self, cache):
     async def test_acquire(self, cache, lock):
         await cache.set(Keys.KEY, "value")
         async with lock:
-            assert lock._token == await cache._gets(cache._build_key(Keys.KEY))
+            assert lock._token == await cache._gets(cache.build_key(Keys.KEY))
 
     async def test_release_does_nothing(self, lock):
         assert await lock.__aexit__("exc_type", "exc_value", "traceback") is None

tests/ut/backends/test_memcached.py

@@ -4,9 +4,9 @@
 import pytest
 
 from aiocache.backends.memcached import MemcachedBackend, MemcachedCache
-from aiocache.base import BaseCache, _ensure_key
+from aiocache.base import BaseCache
 from aiocache.serializers import JsonSerializer
-from ...utils import Keys
+from ...utils import Keys, ensure_key
 
 
 @pytest.fixture
@@ -249,7 +249,7 @@ def test_parse_uri_path(self):
 
     @pytest.mark.parametrize(
         "namespace, expected",
-        ([None, "test" + _ensure_key(Keys.KEY)], ["", _ensure_key(Keys.KEY)], ["my_ns", "my_ns" + _ensure_key(Keys.KEY)]),  # type: ignore[attr-defined]  # noqa: B950
+        ([None, "test" + ensure_key(Keys.KEY)], ["", ensure_key(Keys.KEY)], ["my_ns", "my_ns" + ensure_key(Keys.KEY)]),  # type: ignore[attr-defined]  # noqa: B950
     )
     def test_build_key_bytes(self, set_test_namespace, memcached_cache, namespace, expected):
         assert memcached_cache.build_key(Keys.KEY, namespace=namespace) == expected.encode()