funkycache 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
funkycache/__init__.py ADDED
@@ -0,0 +1,9 @@
1
+ """
2
+ funkycache is a function cache that tracks file dependencies.
3
+ """
4
+
5
+ from .manager import FunkyCache
6
+ from .storage import CannotOverwriteValueException
7
+ from .version import __version__
8
+
9
+ __all__ = ["CannotOverwriteValueException", "FunkyCache", "__version__"]
funkycache/manager.py ADDED
@@ -0,0 +1,512 @@
1
+ """
2
+ Manage the caching of all the functions in a codebase.
3
+
4
+ Ensure each function has an independent cache.
5
+ """
6
+
7
+ import atexit
8
+ from collections.abc import Callable, Sequence
9
+ from dataclasses import dataclass
10
+ from functools import wraps
11
+ import inspect
12
+ import itertools
13
+ import json
14
+ from pathlib import Path
15
+ import typing
16
+ from typing import Any, cast, Literal, overload, ParamSpec, Protocol, TypeVar
17
+ import warnings
18
+
19
+ import xxhash
20
+
21
+ from .storage import (
22
+ CacheStorage,
23
+ MemoryCacheStorage,
24
+ SQLiteCacheStorage,
25
+ CannotOverwriteValueException,
26
+ )
27
+
28
+
29
+ P = ParamSpec("P")
30
+ R = TypeVar("R")
31
+
32
+
33
+ class F[**P, R](Protocol):
34
+ """
35
+ A function: that is, a callable that also exposes a __name__ attribute.
36
+
37
+ This is the type accepted by register(). It's deliberately narrower
38
+ than Callable, because the identifier for a cache is derived from
39
+ a function's __name__, __module__, and __qualname__.
40
+ """
41
+
42
+ def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R: ... # noqa: D102
43
+
44
+ @property
45
+ def __name__(self) -> str: ... # noqa: D105
46
+
47
+
48
+ StorageType = Literal["memory", "sqlite"]
49
+
50
+
51
+ @dataclass
52
+ class KnownCache[R]:
53
+ """
54
+ Tracks the underlying storage for a single function.
55
+
56
+ There's one KnownCache for each registered function for the lifetime
57
+ of the FunkyCache. When a function's dependencies change, the storage
58
+ is updated and input_sig is updated, and this record is updated in-place.
59
+ """
60
+
61
+ storage: CacheStorage
62
+ data_type: R
63
+
64
+ # func_name is the canonical name of the function, including
65
+ # module path and function name.
66
+ func_name: str
67
+
68
+ # input_sig is a hash of everything the function depends on:
69
+ # the path/content of each dependent file, and each dependent value.
70
+ input_sig: str
71
+
72
+ # dep_paths is the set of files and folders the function declared
73
+ # as dependencies, plus the file the function itself is defined in.
74
+ dep_paths: set[Path]
75
+
76
+ # dep_values is the list of static values the function declared as
77
+ # dependencies, in the order they were given.
78
+ dep_values: list[Any]
79
+
80
+ def is_affected_by(self, changed_paths: list[Path]) -> bool:
81
+ """
82
+ Whether the cached function depends on any of these paths.
83
+
84
+ A function declares on a path if it was declared explicitly,
85
+ or if the path sits underneath a directory that was declared.
86
+ """
87
+ for dp in self.dep_paths:
88
+ if dp in changed_paths:
89
+ return True
90
+ elif dp.is_dir() and any(p.is_relative_to(dp) for p in changed_paths):
91
+ return True
92
+ return False
93
+
94
+
95
+ class FunkyCache:
96
+ """
97
+ FunkyCache manages all the cached functions in a codebase.
98
+
99
+ It tracks all of the functions being cached and the files/values
100
+ they depend on. When FunkyCache is notified that a file changes (or it
101
+ detects a change when the Python process is restarted), it invalidates
102
+ the cache.
103
+
104
+ Typical usage looks like this:
105
+
106
+ cache = FunkyCache(storage="sqlite", root=".cache")
107
+
108
+ @cache.register(files=["content/index.md"])
109
+ def render_page() -> str:
110
+ ...
111
+
112
+ cache.notify_path_change("content/index.md")
113
+
114
+ Functions are cached based on their arguments, so calls must be
115
+ deterministic for the cache to behave correctly.
116
+ """
117
+
118
+ _storage: StorageType
119
+ _root: Path
120
+ _known_caches: dict[str, KnownCache]
121
+
122
+ @overload
123
+ def __init__(self, *, storage: Literal["memory"] = "memory"): ...
124
+
125
+ @overload
126
+ def __init__(
127
+ self, *, storage: Literal["sqlite"], root: Path | str | None = None
128
+ ) -> None: ...
129
+
130
+ def __init__(
131
+ self, *, storage: StorageType = "memory", root: Path | str | None = None
132
+ ):
133
+ """
134
+ Create a new cache manager.
135
+
136
+ Arguments:
137
+ storage: How to store the cached values.
138
+ "memory" keeps them in-memory for the life of this object.
139
+ "sqlite" writes them to disk, so they survive process restarts.
140
+ root: The directory holding persistent artefacts. Only valid
141
+ SQLite storage.
142
+
143
+ """
144
+ if storage == "memory" and root is not None:
145
+ raise TypeError("Do not specify a root path with memory storage")
146
+
147
+ if storage not in typing.get_args(StorageType):
148
+ raise TypeError(f"Unrecognised storage: {storage!r}")
149
+
150
+ if root is None:
151
+ root = Path(".funkycache")
152
+
153
+ self._storage = storage
154
+ self._root = Path(root).resolve()
155
+ self._known_caches = {}
156
+
157
+ atexit.register(self._close)
158
+
159
+ @overload
160
+ def register[**P, R](self, func: F) -> F: ...
161
+
162
+ @overload
163
+ def register[**P, R](
164
+ self, *, files: list[Path | str] | None = None, values: list[Any] | None = None
165
+ ) -> Callable[[F], F]: ...
166
+
167
+ def register[**P, R](
168
+ self,
169
+ func: F | None = None,
170
+ *,
171
+ files: list[Path | str] | None = None,
172
+ values: list[Any] | None = None,
173
+ ) -> F:
174
+ """
175
+ Cache the input/output of func.
176
+
177
+ The function can optionally declare a dependency on input files or
178
+ static values. If the files change, use notify_path_change to
179
+ invalidate functions that relied on that file. Static values are
180
+ presumed to be unchanged for the life of the Python process.
181
+
182
+ The function's own source file is always a dependency, so editing
183
+ the code that produced a value also invalidates it on the next run.
184
+ """
185
+
186
+ def decorator(func: F) -> F:
187
+ data_type = _data_type(func, self._storage)
188
+ dep_paths = _dep_paths(func, files=[Path(p) for p in (files or [])])
189
+ dep_values = values or []
190
+
191
+ if any(
192
+ dp.is_relative_to(self._root) or self._root.is_relative_to(dp)
193
+ for dp in dep_paths
194
+ ):
195
+ raise ValueError(
196
+ "A function cannot depend on a file/folder inside the cache root"
197
+ )
198
+
199
+ # Check if we already have a cache for this function.
200
+ #
201
+ # We must do this before creating the storage, or we could have
202
+ # a dangling, unclosed storage hanging around.
203
+ func_name = _canonical_name(func)
204
+ if func_name in self._known_caches:
205
+ raise TypeError(f"Duplicate cache for {func_name}")
206
+
207
+ input_sig = _input_signature(dep_paths, dep_values)
208
+ storage = self._create_storage(func_name, data_type, input_sig)
209
+
210
+ self._known_caches[func_name] = KnownCache(
211
+ storage, data_type, func_name, input_sig, dep_paths, dep_values
212
+ )
213
+
214
+ @wraps(func)
215
+ def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
216
+ sig = inspect.signature(func)
217
+ bound = sig.bind(*args, **kwargs)
218
+ bound.apply_defaults()
219
+ key = bound.arguments
220
+
221
+ is_generator = inspect.isgeneratorfunction(func)
222
+
223
+ # We need to look up the CacheStorage in self._known_caches
224
+ # every time, in case it's changed since the last call.
225
+ storage = self._known_caches[func_name].storage
226
+
227
+ try:
228
+ cached_val = storage.get(key)
229
+ if is_generator:
230
+ return cast(R, iter(cached_val))
231
+ return cached_val
232
+ except KeyError:
233
+ pass
234
+ except Exception as e:
235
+ warnings.warn(f"unexpected error looking up key in cache: {e}")
236
+
237
+ # If the function is a generator, capture up to 10,000 items
238
+ # in a list and store that. If it returns >10,000 values
239
+ # (for example, if it's infinite), bypass the cache to avoid
240
+ # storing an unbounded amount of info.
241
+ new_value = func(*args, **kwargs)
242
+ if is_generator:
243
+ list_value = []
244
+ for item in itertools.islice(new_value, 10000):
245
+ list_value.append(item)
246
+ try:
247
+ list_value.append(next(new_value))
248
+ except StopIteration:
249
+ new_value = list_value
250
+ else:
251
+ warnings.warn(
252
+ "iterator returned more than 10,000 items; "
253
+ "output will not be cached"
254
+ )
255
+ return cast(R, itertools.chain(iter(list_value), new_value))
256
+
257
+ try:
258
+ storage.set(key, new_value)
259
+ except CannotOverwriteValueException:
260
+ raise
261
+ except Exception as e:
262
+ warnings.warn(f"unexpected error inserting value into cache: {e}")
263
+ pass
264
+
265
+ if is_generator:
266
+ return cast(R, iter(new_value))
267
+
268
+ return cast(R, new_value)
269
+
270
+ return wrapper
271
+
272
+ if func is not None:
273
+ return decorator(func)
274
+ return decorator
275
+
276
+ def _create_storage(
277
+ self,
278
+ func_name: str,
279
+ data_type: R,
280
+ input_sig: str,
281
+ ) -> CacheStorage[R]:
282
+ """
283
+ Create a new instance of CacheStorage.
284
+ """
285
+ match self._storage:
286
+ case "memory":
287
+ return MemoryCacheStorage[R]()
288
+ case "sqlite":
289
+ # Remove path-unsafe names from the function name,
290
+ # and use this as the on-disk identifier.
291
+ identifier = func_name.replace(":", "-")
292
+
293
+ # When we create a new SQLite cache, clear out any
294
+ # similar-looking caches which are presumably stale.
295
+ # TODO: Check if the cache was accessed recently, which
296
+ # might indicate another process still using it.
297
+ self._root.mkdir(exist_ok=True, parents=True)
298
+ db_path = self._root / f"{identifier}.{input_sig}.db"
299
+ storage = SQLiteCacheStorage[R](db_path, data_type=data_type)
300
+ for f in self._root.glob(f"{identifier}.*.db*"):
301
+ if f != db_path:
302
+ f.unlink()
303
+ return storage
304
+ case _: # pragma: no cover
305
+ raise TypeError(f"unrecognised storage: {self._storage!r}")
306
+
307
+ def _close(self) -> None: # pragma: no cover
308
+ """
309
+ Close any open files or underlying caches.
310
+ """
311
+ match self._storage:
312
+ case "sqlite":
313
+ for kc in self._known_caches.values():
314
+ cast(SQLiteCacheStorage, kc.storage).close()
315
+ case _:
316
+ pass
317
+
318
+ def notify_path_change(
319
+ self, changed_paths: Path | str | Sequence[Path | str]
320
+ ) -> None:
321
+ """
322
+ Invalidate cache that depend on this path and/or paths.
323
+
324
+ Call this after modifying files that a cached function depends on.
325
+ The function's cache will be invalidated, and the next call will
326
+ recompute the value.
327
+
328
+ Notification is advisory: it is a hint that something may have
329
+ changed, but caches are only invalidated when the files they depend
330
+ on actually change, so notifying about an unrelated or unchanged
331
+ path is cheap and safe.
332
+ """
333
+ # Convert input values to a list of absolute paths.
334
+ if isinstance(changed_paths, (Path, str)):
335
+ changed_paths = [changed_paths]
336
+ changed_paths: list[Path] = [Path(p).resolve() for p in changed_paths]
337
+
338
+ for name, known_cache in self._known_caches.items():
339
+ # If this cache isn't affected by any of the paths that
340
+ # changed, we can leave it as-is.
341
+ if not known_cache.is_affected_by(changed_paths):
342
+ continue
343
+
344
+ # Compute the new input signature. If it's the same, we can
345
+ # keep the cache as-is.
346
+ new_input_sig = _input_signature(
347
+ known_cache.dep_paths, known_cache.dep_values
348
+ )
349
+
350
+ if known_cache.input_sig == new_input_sig:
351
+ continue
352
+
353
+ # This cache depends on a path that changed! Create a new cache.
354
+ if isinstance(known_cache.storage, SQLiteCacheStorage):
355
+ known_cache.storage.close()
356
+
357
+ known_cache.storage = self._create_storage(
358
+ func_name=known_cache.func_name,
359
+ data_type=known_cache.data_type,
360
+ input_sig=new_input_sig,
361
+ )
362
+ known_cache.input_sig = new_input_sig
363
+
364
+
365
+ def _data_type(func: F, storage: StorageType) -> Any:
366
+ """
367
+ Based on a function's return annotation, look up the type of the
368
+ data we're going to cache.
369
+ """
370
+ sig = inspect.signature(func)
371
+ ret_annotation = sig.return_annotation
372
+
373
+ if ret_annotation == inspect.Signature.empty:
374
+ match storage:
375
+ case "memory":
376
+ warnings.warn(
377
+ f"{func.__name__} has no return annotation, "
378
+ "which is required for non-memory storage"
379
+ )
380
+ case "sqlite":
381
+ raise TypeError(
382
+ f"{func.__name__} has no return annotation; "
383
+ "annotate it to use SQLite storage"
384
+ )
385
+ case _: # pragma: no cover
386
+ raise TypeError(f"unrecognised storage: {storage!r}")
387
+
388
+ # If it's a generator function, we'll cache the materialised list
389
+ # rather than the generator.
390
+ if inspect.isgeneratorfunction(func):
391
+ origin = typing.get_origin(ret_annotation)
392
+ args = typing.get_args(ret_annotation)
393
+ if origin is not None and len(args) == 1:
394
+ return list[args[0]] # type: ignore
395
+ else:
396
+ match storage:
397
+ case "memory":
398
+ warnings.warn(
399
+ f"{func.__name__} is a generator with an incomplete "
400
+ "return annotation; "
401
+ "a complete annotation is required for non-memory storage"
402
+ )
403
+ case "sqlite":
404
+ raise TypeError(
405
+ f"{func.__name__} is a generator with an incomplete return "
406
+ "annotation; annotate it to use SQLite storage"
407
+ )
408
+ case _: # pragma: no cover
409
+ raise TypeError(f"unrecognised storage: {storage!r}")
410
+
411
+ return ret_annotation
412
+
413
+
414
+ def _canonical_name(func: F) -> str:
415
+ """
416
+ Return a canonical identifier for this function.
417
+
418
+ This should uniquely identify a function within a codebase,
419
+ and functions with the same name but in different files/classes
420
+ should get a different identifier.
421
+
422
+ This is used as the key in _known_caches and to identify SQLite caches
423
+ on disk.
424
+ """
425
+ parts = []
426
+
427
+ # Get the name of the module where this function is defined.
428
+ # For example, _canonical_name.__module__ is `funkycache.manager`.
429
+ #
430
+ # If this is unavailable, __module__ is None.
431
+ module = getattr(func, "__module__", "__main__")
432
+ parts.append(module or "<unknown>")
433
+
434
+ # If the function is in a script, __module__ is `__main__`, so
435
+ # include the XXH64 of the path to prevent collisions between
436
+ # identically-named functions in different script files.
437
+ #
438
+ # This code is tested, but coverage can't see it.
439
+ if module == "__main__": # pragma: no cover
440
+ parts.append(
441
+ xxhash.xxh64_hexdigest(
442
+ (inspect.getsourcefile(func) or "<unknown>").encode("utf8")
443
+ )
444
+ )
445
+
446
+ # Get the qualified name of the function.
447
+ #
448
+ # This is the "path" from a module's global scope to the function
449
+ # or method, which includes classes.
450
+ parts.append(getattr(func, "__qualname__", func.__name__))
451
+
452
+ return "::".join(parts)
453
+
454
+
455
+ def _dep_paths(func: F, files: list[Path]) -> set[Path]:
456
+ """
457
+ Get a list of all the absolute paths this function depends on.
458
+ """
459
+ dep_paths: list[Path] = []
460
+
461
+ # 1. Include the source file of the function.
462
+ if func_file := inspect.getsourcefile(func):
463
+ dep_paths.append(Path(func_file).resolve())
464
+ else:
465
+ warnings.warn(
466
+ f"unable to determine source file for {func}; "
467
+ "caches may not be invalidated correctly"
468
+ )
469
+
470
+ # 2. Include any explicitly declared files.
471
+ if files:
472
+ dep_paths.extend([p.resolve() for p in files])
473
+
474
+ return set(dep_paths)
475
+
476
+
477
+ def _input_signature(dep_paths: set[Path], values: list[Any]) -> str:
478
+ """
479
+ Create a "signature" for all the inputs this cache depends on.
480
+
481
+ We get a list of all the files this function depends on, their hashes
482
+ (or "<missing>" if they don't exist yet), and the values. These get
483
+ saved in a JSON object to avoid collisions, and then we use the xxh64.
484
+ """
485
+ signature = {
486
+ "paths": {},
487
+ "values": values,
488
+ }
489
+
490
+ # For each dependent path, include both the path itself
491
+ # and a hash of the contents.
492
+ all_paths = []
493
+ for p in dep_paths:
494
+ if p.is_file() or not p.exists():
495
+ all_paths.append(p)
496
+ elif p.is_dir():
497
+ all_paths.extend(gp for gp in p.rglob("*") if gp.is_file())
498
+ else: # pragma: no cover
499
+ raise TypeError(f"Invalid path: {p}")
500
+
501
+ for p in sorted(all_paths):
502
+ try:
503
+ h = xxhash.xxh64()
504
+ with open(p, "rb") as infile:
505
+ while chunk := infile.read(8192):
506
+ h.update(chunk)
507
+ signature["paths"][str(p)] = h.hexdigest()
508
+ except FileNotFoundError:
509
+ signature["paths"][str(p)] = "<missing>"
510
+
511
+ json_str = json.dumps(signature, sort_keys=True)
512
+ return xxhash.xxh64_hexdigest(json_str.encode("utf8"))
funkycache/py.typed ADDED
File without changes
funkycache/storage.py ADDED
@@ -0,0 +1,331 @@
1
+ """
2
+ Backing storage for cache, which records the input/output of Python functions.
3
+
4
+ This module doesn't know which function a cache belongs to; it only maps
5
+ a collection of arguments to the return value.
6
+ """
7
+
8
+ from abc import ABC, abstractmethod
9
+ from collections.abc import Mapping
10
+ from datetime import datetime, timezone
11
+ from functools import cache
12
+ import json
13
+ from pathlib import Path
14
+ import sqlite3
15
+ from types import TracebackType
16
+ from typing import Any, cast, Self
17
+
18
+ from pydantic import TypeAdapter
19
+ import xxhash
20
+
21
+ from .version import __version__
22
+
23
+
24
+ class CannotOverwriteValueException(ValueError):
25
+ """
26
+ Thrown when you try to overwrite an existing cache key with
27
+ a different value.
28
+
29
+ A key which already exists with the same value can be written again
30
+ harmlessly, but a different value is an error.
31
+
32
+ This exception means the cached function is non-deterministic: the
33
+ same input returned two different outputs. This is a bug in the
34
+ cached function, and cannot be fixed by retrying.
35
+ """
36
+
37
+ def __init__(self, key: Mapping[str, Any]) -> None:
38
+ super().__init__(f"Key already exists: {key!r}")
39
+
40
+
41
+ class CacheStorage[V](ABC):
42
+ """
43
+ The interface for the backing storage of a cache which records
44
+ the input/output of a single Python function.
45
+ """
46
+
47
+ @abstractmethod
48
+ def set(self, key: Mapping[str, Any], value: V) -> None:
49
+ """
50
+ Save a key-value pair in the cache.
51
+
52
+ Throws an exception if you overwrite an existing key with
53
+ a different value.
54
+ """
55
+
56
+ @abstractmethod
57
+ def get(self, key: Mapping[str, Any]) -> V:
58
+ """
59
+ Look up the value of a key in the cache.
60
+
61
+ Throws a KeyError if you look up a key which isn't in the cache.
62
+ """
63
+
64
+
65
+ class MemoryCacheStorage[V](CacheStorage[V]):
66
+ """
67
+ In-memory storage for a cache of the input/output of
68
+ a single Python function.
69
+
70
+ Values only survive until the end of the Python process.
71
+ """
72
+
73
+ def __init__(self):
74
+ self._underlying: dict[str, V] = {}
75
+
76
+ def set(self, key: Mapping[str, Any], value: V) -> None:
77
+ """
78
+ Save a key-value pair in the cache.
79
+ """
80
+ enc_key = _encode_key_as_json(key)
81
+
82
+ try:
83
+ if self._underlying[enc_key] != value:
84
+ raise CannotOverwriteValueException(key)
85
+ except KeyError:
86
+ self._underlying[enc_key] = value
87
+
88
+ def get(self, key: Mapping[str, Any]) -> V:
89
+ """
90
+ Look up the value of a key in the cache.
91
+ """
92
+ enc_key = _encode_key_as_json(key)
93
+ return self._underlying[enc_key]
94
+
95
+
96
+ class TypedCacheStorage[V](CacheStorage[V]):
97
+ """
98
+ Cache storage that allows storing arbitrary Python types in backing
99
+ storage that only supports strings.
100
+ """
101
+
102
+ adapter: TypeAdapter[Any]
103
+
104
+ def __init__(self, *, data_type: Any) -> None:
105
+ self.adapter = TypeAdapter(data_type)
106
+
107
+ @abstractmethod
108
+ def _set_str(self, key: Mapping[str, Any], value: str) -> None:
109
+ """
110
+ Save a key-value pair in the cache, where the value is a string.
111
+
112
+ Throws an exception if you overwrite an existing key with
113
+ a different value.
114
+ """
115
+
116
+ def set(self, key: Mapping[str, Any], value: V) -> None:
117
+ """
118
+ Save a key-value pair in the cache.
119
+
120
+ Throws an exception if you overwrite an existing key with
121
+ a different value.
122
+ """
123
+ json_str = self.adapter.dump_json(value).decode("utf8")
124
+ self._set_str(key, json_str)
125
+
126
+ @abstractmethod
127
+ def _get_str(self, key: Mapping[str, Any]) -> str:
128
+ """
129
+ Look up the string value of a key in the cache.
130
+
131
+ Throws a KeyError if you look up a key which isn't in the cache.
132
+ """
133
+
134
+ def get(self, key: Mapping[str, Any]) -> V:
135
+ """
136
+ Look up the value of a key in the cache.
137
+
138
+ Throws a KeyError if you look up a key which isn't in the cache.
139
+ """
140
+ str_value = self._get_str(key)
141
+ return self.adapter.validate_json(str_value)
142
+
143
+
144
+ class SQLiteCacheStorage[V](TypedCacheStorage[V]):
145
+ """
146
+ SQLite-backed storage for a cache of the input/output of
147
+ a single Python function.
148
+
149
+ Values are persisted to disk, and survive the end of the Python process.
150
+ """
151
+
152
+ con: sqlite3.Connection
153
+
154
+ def __init__(self, database: str | Path, *, data_type: Any):
155
+ self.con = sqlite3.connect(database)
156
+ self.con.execute("PRAGMA journal_mode = WAL;")
157
+ self.con.execute("PRAGMA synchronous = NORMAL;")
158
+
159
+ try:
160
+ self._create_tables()
161
+ self.con.commit()
162
+ except Exception:
163
+ self.close()
164
+ raise
165
+
166
+ super().__init__(data_type=data_type)
167
+
168
+ def _create_tables(self) -> None:
169
+ """
170
+ Create or update the database tables.
171
+ """
172
+ cursor = self.con.cursor()
173
+ table_definitions = {
174
+ #
175
+ # The funkycache_meta table contains the fingerprint and
176
+ # some other metadata that might be useful for debugging.
177
+ "funkycache_meta": "CREATE TABLE funkycache_meta(key PRIMARY KEY, value)",
178
+ #
179
+ # Each row in funkycache contains three columns:
180
+ # - enc_key is the JSON-serialised, hashed key
181
+ # - raw_key is the JSON-serialised key (for debugging)
182
+ # - value is the JSON-serialised value
183
+ "funkycache_entries": "CREATE TABLE funkycache_entries(enc_key PRIMARY KEY, value)", # noqa: E501
184
+ }
185
+
186
+ # Get a fingerprint for the current table definitions
187
+ cur_fingerprint = _hash(json.dumps(table_definitions, sort_keys=True))
188
+
189
+ # Check if the fingerprint in the database exists and matches
190
+ # the current file.
191
+ try:
192
+ cursor.execute(
193
+ "SELECT value FROM funkycache_meta WHERE key = 'fingerprint'"
194
+ )
195
+ except sqlite3.OperationalError as err:
196
+ if err.args == ("no such table: funkycache_meta",):
197
+ pass
198
+ else:
199
+ raise
200
+ else:
201
+ # If the stored fingerprint matches, the database is already
202
+ # using the correct data.
203
+ if result := cursor.fetchone():
204
+ if result[0] == cur_fingerprint:
205
+ return
206
+
207
+ # If the fingerprint is missing/wrong, drop and recreate the tables.
208
+ for tbl, definition in table_definitions.items():
209
+ cursor.execute(f"DROP TABLE IF EXISTS {tbl}")
210
+ cursor.execute(definition)
211
+
212
+ # Add some metadata to the funkycache_meta table
213
+ cursor.execute(
214
+ "INSERT INTO funkycache_meta VALUES (?,?)", ("fingerprint", cur_fingerprint)
215
+ )
216
+ cursor.execute(
217
+ "INSERT INTO funkycache_meta VALUES (?,?)",
218
+ ("funkycache_version", __version__),
219
+ )
220
+ cursor.execute(
221
+ "INSERT INTO funkycache_meta VALUES (?,?)",
222
+ ("date_created", datetime.now(tz=timezone.utc).isoformat()),
223
+ )
224
+
225
+ def close(self) -> None:
226
+ """
227
+ Close the underlying SQLite connection.
228
+ """
229
+ self.con.close()
230
+
231
+ def __enter__(self) -> Self:
232
+ """
233
+ Allow using SQLiteCacheStorage as a context manager.
234
+ """
235
+ return self
236
+
237
+ def __exit__(
238
+ self,
239
+ exc_type: type[BaseException] | None,
240
+ exc_val: BaseException | None,
241
+ exc_tb: TracebackType | None,
242
+ ) -> None:
243
+ """
244
+ Automatically close the connection upon exiting the context.
245
+ """
246
+ self.close()
247
+
248
+ def _encode_key(self, key: Mapping[str, Any]) -> str:
249
+ """
250
+ Encode a mapping as a string key.
251
+
252
+ The function arguments (which may be arbitrary Python objects)
253
+ are serialised as JSON, then hashed to reduce it to a fixed size.
254
+ Using fixed-size keys improves SQLite performance.
255
+ """
256
+ json_key = _encode_key_as_json(key)
257
+ return _hash(json_key)
258
+
259
+ def _set_str(self, key: Mapping[str, Any], value: str) -> None:
260
+ """
261
+ Save a key-value pair in the cache, where the value is a string.
262
+
263
+ Throws an exception if you overwrite an existing key with
264
+ a different value.
265
+ """
266
+ enc_key = self._encode_key(key)
267
+
268
+ try:
269
+ self.con.execute(
270
+ "INSERT INTO funkycache_entries VALUES (?,?)",
271
+ (enc_key, value),
272
+ )
273
+ self.con.commit()
274
+ except sqlite3.IntegrityError as err:
275
+ if err.sqlite_errorname == "SQLITE_CONSTRAINT_PRIMARYKEY":
276
+ if self._get_str(key) == value:
277
+ return
278
+ else:
279
+ raise CannotOverwriteValueException(key)
280
+ else:
281
+ raise
282
+
283
+ def _get_str(self, key: Mapping[str, Any]) -> str:
284
+ """
285
+ Look up the string value of a key in the cache.
286
+
287
+ Throws a KeyError if you look up a key which isn't in the cache.
288
+ """
289
+ enc_key = self._encode_key(key)
290
+
291
+ res = self.con.execute(
292
+ "SELECT value FROM funkycache_entries WHERE enc_key=?", (enc_key,)
293
+ )
294
+
295
+ try:
296
+ (value,) = res.fetchone()
297
+ return cast(str, value)
298
+ except TypeError:
299
+ raise KeyError(key)
300
+
301
+
302
+ def _make_json_compatible(value: Any) -> Any:
303
+ """
304
+ Recursively walk an arbitrary structure and prepare it for JSON encoding.
305
+ """
306
+ if isinstance(value, dict):
307
+ return {str(k): _make_json_compatible(v) for k, v in value.items()}
308
+ elif isinstance(value, (list, tuple, set)):
309
+ return [_make_json_compatible(item) for item in value]
310
+ else:
311
+ return value
312
+
313
+
314
+ def _encode_key_as_json(key: Mapping[str, Any]) -> str:
315
+ """
316
+ Encode a set of arguments to a Python function as a JSON string.
317
+
318
+ This is a lossy transformation that is designed to get a reasonable
319
+ serialisation as JSON. It is possible for values of different types
320
+ to collide.
321
+ """
322
+ clean_key = _make_json_compatible(key)
323
+ return json.dumps(clean_key, sort_keys=True, default=str)
324
+
325
+
326
+ @cache
327
+ def _hash(s: str) -> str:
328
+ """
329
+ Hash a string to reduce it to a fixed size.
330
+ """
331
+ return "xxh64:" + xxhash.xxh64_hexdigest(s.encode("utf8"))
funkycache/version.py ADDED
@@ -0,0 +1,5 @@
1
+ """
2
+ The FunkyCache version.
3
+ """
4
+
5
+ __version__ = "1.0.0"
@@ -0,0 +1,63 @@
1
+ Metadata-Version: 2.4
2
+ Name: funkycache
3
+ Version: 1.0.0
4
+ Summary: A SQLite-backed function cache that tracks file dependencies
5
+ Author-email: Alex Chan <alex@alexwlchan.net>
6
+ Maintainer-email: Alex Chan <alex@alexwlchan.net>
7
+ License-Expression: MIT
8
+ Project-URL: Homepage, https://alexwlchan.net/projects/funkycache/
9
+ Project-URL: Changelog, https://alexwlchan.net/projects/funkycache/releases/
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Programming Language :: Python :: 3.14
12
+ Requires-Python: >=3.14
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: pydantic
16
+ Requires-Dist: xxhash
17
+ Dynamic: license-file
18
+
19
+ # funkycache
20
+
21
+ funkycache is a disk-backed cache for Python functions that tracks file dependencies.
22
+ I use it in my static site generator to cache the output of expensive functions.
23
+
24
+ Example:
25
+
26
+ ```python
27
+ from funkycache import FunkyCache
28
+
29
+ cache = FunkyCache(storage="sqlite")
30
+
31
+
32
+ @cache.register(files=["content/index.md", "templates/base.html"])
33
+ def render_index() -> str:
34
+ page = Path("content/index.md").read_text()
35
+ template = Path("templates/base.html").read_text()
36
+ return template.replace("{{ content }}", page)
37
+
38
+
39
+ print(render_index()) # runs the function
40
+ print(render_index()) # cache hit, even in a new process
41
+
42
+ cache.notify_path_change("content/index.md")
43
+
44
+ print(render_index()) # runs the function again
45
+ ```
46
+
47
+ When you register a function with funkycache, you can declare path or static values the function depends on.
48
+ If those dependent values change, the function's cache is invalidated, and the next call will rerun the function fresh.
49
+
50
+ **Note:** funkycache does not watch the filesystem.
51
+ It is your responsibility to notify it of changes to dependent files, or they will be noticed when the Python process restarts.
52
+
53
+ ## Installation
54
+
55
+ Install using pip:
56
+
57
+ ```console
58
+ $ pip install funkycache
59
+ ```
60
+
61
+ ## License
62
+
63
+ This project is shared under the [MIT license](./LICENSE).
@@ -0,0 +1,10 @@
1
+ funkycache/__init__.py,sha256=kqjYjqTMwtJOsArCc9jvPWlDHTiv-AhOOK5J2VyWwCI,261
2
+ funkycache/manager.py,sha256=ppzBQQ71yekT5i6xQXPkr8m43EhoySwsmceRqwGGIug,17871
3
+ funkycache/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
4
+ funkycache/storage.py,sha256=9EH5LLoWtGZrCn3dYbzEnQqQHW8qOn26QEBCqadnB6E,10262
5
+ funkycache/version.py,sha256=KMM7uDfDIp0lRGQMvPx2BKPyy_znP-RO1CqOy6BFD74,55
6
+ funkycache-1.0.0.dist-info/licenses/LICENSE,sha256=7affMWxdkMVpRWlA56Eg03Je_zsSs3YIBEXYZAEfZak,1053
7
+ funkycache-1.0.0.dist-info/METADATA,sha256=M0nhFdg8b2-yDgYCEBtRluZ9kKj_sWMcAiZpclpiLXc,1938
8
+ funkycache-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
9
+ funkycache-1.0.0.dist-info/top_level.txt,sha256=2tfpEyErgXmQr6Ssgy7goLUC3qHB5tCY-usPR4Z3CXE,11
10
+ funkycache-1.0.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,19 @@
1
+ Copyright (c) 2026 Alex Chan
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a
4
+ copy of this software and associated documentation files (the "Software"),
5
+ to deal in the Software without restriction, including without limitation
6
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
7
+ and/or sell copies of the Software, and to permit persons to whom the Software
8
+ is furnished to do so, subject to the following conditions:
9
+
10
+ The above copyright notice and this permission notice shall be included in
11
+ all copies or substantial portions of the Software.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
16
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
17
+ OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
18
+ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
19
+ OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1 @@
1
+ funkycache