| 1 |
"""alt_key_builder.py |
| 2 |
|
| 3 |
``key_builder`` is used in two contexts within ``aiocache``, |
| 4 |
with different meanings. |
| 5 |
1. Custom ``key_builder`` for a cache -- Prepends a namespace to the key |
| 6 |
2. Custom ``key_builder`` for a cache decorator -- Creates a cache key from |
| 7 |
the decorated callable and the callable's arguments |
| 8 |
|
| 9 |
-------------------------------------------------------------------------- |
| 10 |
1. A custom ``key_builder`` for a cache can manipulate the name of a |
| 11 |
cache key; for example to meet naming requirements of the backend. |
| 12 |
|
| 13 |
``key_builder`` can also optionally mark the key as belonging to a |
| 14 |
namespace group. This enables commonly used key names to be disambiguated |
| 15 |
by their ``namespace`` value. It also enables bulk operation on cache keys, |
| 16 |
such as expiring all keys in the same namespace. |
| 17 |
|
| 18 |
``key_builder`` is expected (but not required) to prefix the passed key |
| 19 |
argument with the namespace argument. After initializing the cache object, |
| 20 |
the key builder can be accessed via the cache's ``build_key`` member. |
| 21 |
|
| 22 |
Args: |
| 23 |
key (str): undecorated key name |
| 24 |
namespace (str, optional): Prefix to add to the key. Defaults to None. |
| 25 |
|
| 26 |
Returns: |
| 27 |
By default, ``cache.build_key()`` returns ``f'{namespace}{sep}{key}'``, |
| 28 |
where some backends might include an optional separator, ``sep``. |
| 29 |
Some backends might strip or replace illegal characters, and encode |
| 30 |
the result before returning it. Typically str or bytes. |
| 31 |
|
| 32 |
-------------------------------------------------------------------------- |
| 33 |
2. Custom ``key_builder`` for a cache decorator automatically generates a |
| 34 |
cache key from the call signature of the decorated callable. It does |
| 35 |
not accept a ``namespace`` parameter, and it should not add a |
| 36 |
naemspace to the key that it outputs. |
| 37 |
|
| 38 |
Args: |
| 39 |
func (callable): name of the decorated callable |
| 40 |
*args: Positional arguments when ``func`` was called. |
| 41 |
**kwargs: Keyword arguments when ``func`` was called. |
| 42 |
|
| 43 |
Returns (str): |
| 44 |
By default, the output key is a concatenation of the module and name |
| 45 |
of ``func`` + the positional arguments + the sorted keyword arguments. |
| 46 |
""" |
| 47 |
import asyncio |
| 48 |
from typing import List, Dict |
| 49 |
|
| 50 |
from aiocache import Cache, cached |
| 51 |
|
| 52 |
|
| 53 |
async def demo_key_builders(): |
| 54 |
await demo_cache_key_builders() |
| 55 |
await demo_cache_key_builders(namespace="demo") |
| 56 |
await demo_decorator_key_builders() |
| 57 |
|
| 58 |
|
| 59 |
# 1. Custom ``key_builder`` for a cache |
| 60 |
# ------------------------------------- |
| 61 |
|
| 62 |
def ensure_no_spaces(key, namespace=None, replace='_'): |
| 63 |
"""Prefix key with namespace; replace each space with ``replace``""" |
| 64 |
aggregate_key = f"{namespace or ''}{key}" |
| 65 |
custom_key = aggregate_key.replace(' ', replace) |
| 66 |
return custom_key |
| 67 |
|
| 68 |
|
| 69 |
def bytes_key(key, namespace=None): |
| 70 |
"""Prefix key with namespace; convert output to bytes""" |
| 71 |
aggregate_key = f"{namespace or ''}{key}" |
| 72 |
custom_key = aggregate_key.encode() |
| 73 |
return custom_key |
| 74 |
|
| 75 |
|
| 76 |
def fixed_key(key, namespace=None): |
| 77 |
"""Ignore input, generate a fixed key""" |
| 78 |
unchanging_key = "universal key" |
| 79 |
return unchanging_key |
| 80 |
|
| 81 |
|
| 82 |
async def demo_cache_key_builders(namespace=None): |
| 83 |
"""Demonstrate usage and behavior of the custom key_builder functions""" |
| 84 |
cache_ns = "cache_namespace" |
| 85 |
async with Cache(Cache.MEMORY, key_builder=ensure_no_spaces, namespace=cache_ns) as cache: |
| 86 |
raw_key = "Key With Unwanted Spaces" |
| 87 |
return_value = 42 |
| 88 |
await cache.add(raw_key, return_value, namespace=namespace) |
| 89 |
exists = await cache.exists(raw_key, namespace=namespace) |
| 90 |
assert exists is True |
| 91 |
custom_key = cache.build_key(raw_key, namespace=namespace) |
| 92 |
assert ' ' not in custom_key |
| 93 |
if namespace is not None: |
| 94 |
assert custom_key.startswith(namespace) |
| 95 |
else: |
| 96 |
# Using cache.namespace instead |
| 97 |
exists = await cache.exists(raw_key, namespace=cache_ns) |
| 98 |
assert exists is True |
| 99 |
custom_key = cache.build_key(raw_key, namespace=cache_ns) |
| 100 |
assert custom_key.startswith(cache_ns) |
| 101 |
cached_value = await cache.get(raw_key, namespace=namespace) |
| 102 |
assert cached_value == return_value |
| 103 |
await cache.delete(raw_key, namespace=namespace) |
| 104 |
|
| 105 |
async with Cache(Cache.MEMORY, key_builder=bytes_key) as cache: |
| 106 |
raw_key = "string-key" |
| 107 |
return_value = 42 |
| 108 |
await cache.add(raw_key, return_value, namespace=namespace) |
| 109 |
exists = await cache.exists(raw_key, namespace=namespace) |
| 110 |
assert exists is True |
| 111 |
custom_key = cache.build_key(raw_key, namespace=namespace) |
| 112 |
assert isinstance(custom_key, bytes) |
| 113 |
cached_value = await cache.get(raw_key, namespace=namespace) |
| 114 |
assert cached_value == return_value |
| 115 |
await cache.delete(raw_key, namespace=namespace) |
| 116 |
|
| 117 |
async with Cache(Cache.MEMORY, key_builder=fixed_key) as cache: |
| 118 |
unchanging_key = "universal key" |
| 119 |
|
| 120 |
for raw_key, return_value in zip( |
| 121 |
("key_1", "key_2", "key_3"), |
| 122 |
("val_1", "val_2", "val_3")): |
| 123 |
await cache.set(raw_key, return_value, namespace=namespace) |
| 124 |
exists = await cache.exists(raw_key, namespace=namespace) |
| 125 |
assert exists is True |
| 126 |
custom_key = cache.build_key(raw_key, namespace=namespace) |
| 127 |
assert custom_key == unchanging_key |
| 128 |
cached_value = await cache.get(raw_key, namespace=namespace) |
| 129 |
assert cached_value == return_value |
| 130 |
|
| 131 |
# Cache key exists regardless of raw_key name |
| 132 |
for raw_key in ("key_1", "key_2", "key_3"): |
| 133 |
exists = await cache.exists(raw_key, namespace=namespace) |
| 134 |
assert exists is True |
| 135 |
|
| 136 |
cached_value = await cache.get(raw_key, namespace=namespace) |
| 137 |
assert cached_value == "val_3" # The last value that was set |
| 138 |
await cache.delete(raw_key, namespace=namespace) |
| 139 |
|
| 140 |
# Deleting one cache key deletes them all |
| 141 |
for raw_key in ("key_1", "key_2", "key_3"): |
| 142 |
exists = await cache.exists(raw_key, namespace=namespace) |
| 143 |
assert exists is False |
| 144 |
|
| 145 |
|
| 146 |
# 2. Custom ``key_builder`` for a cache decorator |
| 147 |
# ----------------------------------------------- |
| 148 |
|
| 149 |
def ignore_kwargs(func, *args, **kwargs): |
| 150 |
"""Do not use keyword arguments in the cache key's name""" |
| 151 |
return ( |
| 152 |
(func.__module__ or "") |
| 153 |
+ func.__name__ |
| 154 |
+ str(args) |
| 155 |
) |
| 156 |
|
| 157 |
|
| 158 |
def module_override(func, *args, **kwargs): |
| 159 |
"""Override the module-name prefix for the cache key""" |
| 160 |
ordered_kwargs = sorted(kwargs.items()) |
| 161 |
return ( |
| 162 |
"my_module_alias" |
| 163 |
+ func.__name__ |
| 164 |
+ str(args) |
| 165 |
+ str(ordered_kwargs) |
| 166 |
) |
| 167 |
|
| 168 |
|
| 169 |
def hashed_args(*args, **kwargs): |
| 170 |
"""Return a hashable key from a callable's parameters""" |
| 171 |
key = tuple() |
| 172 |
for arg in args: |
| 173 |
if isinstance(arg, List): |
| 174 |
key += tuple(hashed_args(_arg) for _arg in arg) |
| 175 |
elif isinstance(arg, Dict): |
| 176 |
key += tuple(sorted( |
| 177 |
(_key, hashed_args(_value)) for (_key, _value) in arg.items() |
| 178 |
)) |
| 179 |
else: |
| 180 |
key += (arg, ) |
| 181 |
key += tuple(sorted( |
| 182 |
(_key, hashed_args(_value)) for (_key, _value) in kwargs.items() |
| 183 |
)) |
| 184 |
return key |
| 185 |
|
| 186 |
|
| 187 |
def structured_key(func, *args, **kwargs): |
| 188 |
"""String representation of a structured call signature""" |
| 189 |
key = tuple() |
| 190 |
key += (func.__module__ or '', ) |
| 191 |
key += (func.__qualname__ or func.__name__, ) |
| 192 |
key += hashed_args(*args, **kwargs) |
| 193 |
return str(key) |
| 194 |
|
| 195 |
|
| 196 |
async def demo_decorator_key_builders(): |
| 197 |
"""Demonstrate usage and behavior of the custom key_builder functions""" |
| 198 |
await demo_ignore_kwargs_decorator() |
| 199 |
await demo_module_override_decorator() |
| 200 |
await demo_structured_key_decorator() |
| 201 |
|
| 202 |
|
| 203 |
async def demo_ignore_kwargs_decorator(): |
| 204 |
"""Cache key from positional arguments in call to decorated function""" |
| 205 |
@cached(key_builder=ignore_kwargs) |
| 206 |
async def fn(a, b=2, c=3): |
| 207 |
return (a, b) |
| 208 |
|
| 209 |
(a, b) = (5, 1) |
| 210 |
demo_params = ( |
| 211 |
dict(args=(a, b), kwargs=dict(c=3), ret=(a, b)), |
| 212 |
dict(args=(a, ), kwargs=dict(b=b, c=3), ret=(a, b)), |
| 213 |
dict(args=(a, ), kwargs=dict(c=3), ret=(a, b)), # b from previous call |
| 214 |
dict(args=(a, b, 6), kwargs={}, ret=(a, b)), |
| 215 |
) |
| 216 |
demo_keys = list() |
| 217 |
|
| 218 |
for params in demo_params: |
| 219 |
args = params["args"] |
| 220 |
kwargs = params["kwargs"] |
| 221 |
|
| 222 |
await fn(*args, **kwargs) |
| 223 |
cache = fn.cache |
| 224 |
decorator = cached(key_builder=ignore_kwargs) |
| 225 |
key = decorator.get_cache_key(fn, args=args, kwargs=kwargs) |
| 226 |
exists = await cache.exists(key) |
| 227 |
assert exists is True |
| 228 |
assert key.endswith(str(args)) |
| 229 |
cached_value = await cache.get(key) |
| 230 |
assert cached_value == params["ret"] |
| 231 |
demo_keys.append(key) |
| 232 |
|
| 233 |
assert demo_keys[1] == demo_keys[2] |
| 234 |
assert demo_keys[0] != demo_keys[1] |
| 235 |
assert demo_keys[0] != demo_keys[3] |
| 236 |
assert demo_keys[1] != demo_keys[3] |
| 237 |
|
| 238 |
for key in set(demo_keys): |
| 239 |
await cache.delete(key) |
| 240 |
|
| 241 |
|
| 242 |
async def demo_module_override_decorator(): |
| 243 |
"""Cache key uses custom module name for decorated function""" |
| 244 |
@cached(key_builder=module_override) |
| 245 |
async def fn(a, b=2, c=3): |
| 246 |
return (a, b) |
| 247 |
|
| 248 |
(a, b) = (5, 1) |
| 249 |
args = (a, b) |
| 250 |
kwargs = dict(c=3) |
| 251 |
return_value = (a, b) |
| 252 |
|
| 253 |
await fn(*args, **kwargs) |
| 254 |
cache = fn.cache |
| 255 |
decorator = cached(key_builder=module_override) |
| 256 |
key = decorator.get_cache_key(fn, args=args, kwargs=kwargs) |
| 257 |
exists = await cache.exists(key) |
| 258 |
assert exists is True |
| 259 |
assert key.startswith("my_module_alias") |
| 260 |
cached_value = await cache.get(key) |
| 261 |
assert cached_value == return_value |
| 262 |
await cache.delete(key) |
| 263 |
|
| 264 |
|
| 265 |
async def demo_structured_key_decorator(): |
| 266 |
"""Cache key expresses structure of decorated function call""" |
| 267 |
@cached(key_builder=structured_key) |
| 268 |
async def fn(a, b=2, c=3): |
| 269 |
return (a, b) |
| 270 |
|
| 271 |
(a, b) = (5, 1) |
| 272 |
args = (a, b) |
| 273 |
kwargs = dict(c=3) |
| 274 |
return_value = (a, b) |
| 275 |
fn_module = fn.__module__ or '' |
| 276 |
fn_name = fn.__qualname__ or fn.__name__ |
| 277 |
key_name = str((fn_module, fn_name) + hashed_args(*args, **kwargs)) |
| 278 |
|
| 279 |
await fn(*args, **kwargs) |
| 280 |
cache = fn.cache |
| 281 |
decorator = cached(key_builder=structured_key) |
| 282 |
key = decorator.get_cache_key(fn, args=args, kwargs=kwargs) |
| 283 |
exists = await cache.exists(key) |
| 284 |
assert exists is True |
| 285 |
assert key == key_name |
| 286 |
cached_value = await cache.get(key) |
| 287 |
assert cached_value == return_value |
| 288 |
await cache.delete(key) |
| 289 |
|
| 290 |
# --------------------------------------------------------------------------- |
| 291 |
|
| 292 |
if __name__ == "__main__": |
| 293 |
asyncio.run(demo_key_builders()) |