Debian Codegraph @

examples/alt_key_builder.py

raw
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())