funkycache 1.0.4__tar.gz → 1.0.5__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: funkycache
3
- Version: 1.0.4
3
+ Version: 1.0.5
4
4
  Summary: A SQLite-backed function cache that tracks file dependencies
5
5
  Author-email: Alex Chan <alex@alexwlchan.net>
6
6
  Maintainer-email: Alex Chan <alex@alexwlchan.net>
@@ -21,7 +21,8 @@ Dynamic: license-file
21
21
  funkycache is a disk-backed cache for Python functions that tracks file dependencies.
22
22
  I use it in my static site generator to cache the output of expensive functions.
23
23
 
24
- Example:
24
+ To cache the output of a function, create a `FunkyCache` instance, then apply the `cache.register` decorator.
25
+ For example:
25
26
 
26
27
  ```python
27
28
  from funkycache import FunkyCache
@@ -50,6 +51,22 @@ If those dependent values change, the function's cache is invalidated, and the n
50
51
  **Note:** funkycache does not watch the filesystem.
51
52
  It is your responsibility to notify it of changes to dependent files, or they will be noticed when the Python process restarts.
52
53
 
54
+ ## Caching requirements
55
+
56
+ To cache a function with funkycache, the function must:
57
+
58
+ * Have a type hint with a return annotation
59
+ * Always return an identical result when given identical inputs
60
+ * Not have any side effects (for example, creating a file)
61
+
62
+ ## Design
63
+
64
+ * Each function has an independent cache
65
+ * Cache keys are the function arguments, serialised as JSON and hashed using XXH64
66
+ * Cache values are the return value, serialised as JSON
67
+
68
+ For more information about how funkycache works, read [my design notes][me-funkycache-intro].
69
+
53
70
  ## Installation
54
71
 
55
72
  Install using pip:
@@ -61,3 +78,6 @@ $ pip install funkycache
61
78
  ## License
62
79
 
63
80
  This project is shared under the [MIT license](./LICENSE).
81
+
82
+ [me-funkycache-intro]: https://alexwlchan.net/2026/funkycache/
83
+ [wiki-pure]: https://en.wikipedia.org/wiki/Pure_function
@@ -3,7 +3,8 @@
3
3
  funkycache is a disk-backed cache for Python functions that tracks file dependencies.
4
4
  I use it in my static site generator to cache the output of expensive functions.
5
5
 
6
- Example:
6
+ To cache the output of a function, create a `FunkyCache` instance, then apply the `cache.register` decorator.
7
+ For example:
7
8
 
8
9
  ```python
9
10
  from funkycache import FunkyCache
@@ -32,6 +33,22 @@ If those dependent values change, the function's cache is invalidated, and the n
32
33
  **Note:** funkycache does not watch the filesystem.
33
34
  It is your responsibility to notify it of changes to dependent files, or they will be noticed when the Python process restarts.
34
35
 
36
+ ## Caching requirements
37
+
38
+ To cache a function with funkycache, the function must:
39
+
40
+ * Have a type hint with a return annotation
41
+ * Always return an identical result when given identical inputs
42
+ * Not have any side effects (for example, creating a file)
43
+
44
+ ## Design
45
+
46
+ * Each function has an independent cache
47
+ * Cache keys are the function arguments, serialised as JSON and hashed using XXH64
48
+ * Cache values are the return value, serialised as JSON
49
+
50
+ For more information about how funkycache works, read [my design notes][me-funkycache-intro].
51
+
35
52
  ## Installation
36
53
 
37
54
  Install using pip:
@@ -43,3 +60,6 @@ $ pip install funkycache
43
60
  ## License
44
61
 
45
62
  This project is shared under the [MIT license](./LICENSE).
63
+
64
+ [me-funkycache-intro]: https://alexwlchan.net/2026/funkycache/
65
+ [wiki-pure]: https://en.wikipedia.org/wiki/Pure_function
@@ -30,6 +30,7 @@ import xxhash
30
30
 
31
31
  from .storage import (
32
32
  CacheStorage,
33
+ LazyCacheStorage,
33
34
  MemoryCacheStorage,
34
35
  SQLiteCacheStorage,
35
36
  CannotOverwriteValueException,
@@ -322,13 +323,16 @@ class FunkyCache:
322
323
  # similar-looking caches which are presumably stale.
323
324
  # TODO: Check if the cache was accessed recently, which
324
325
  # might indicate another process still using it.
325
- self._root.mkdir(exist_ok=True, parents=True)
326
326
  db_path = self._root / f"{identifier}.{input_sig}.db"
327
- storage = SQLiteCacheStorage[R](db_path, data_type=data_type)
328
327
  for f in self._root.glob(f"{identifier}.*.db*"):
329
328
  if f != db_path:
330
329
  f.unlink()
331
- return storage
330
+
331
+ return LazyCacheStorage(
332
+ create_underlying=lambda: SQLiteCacheStorage[R](
333
+ db_path, data_type=data_type
334
+ )
335
+ )
332
336
  case _: # pragma: no cover
333
337
  raise TypeError(f"unrecognised storage: {self._storage!r}")
334
338
 
@@ -379,8 +383,10 @@ class FunkyCache:
379
383
  continue
380
384
 
381
385
  # This cache depends on a path that changed! Create a new cache.
382
- if isinstance(known_cache.storage, SQLiteCacheStorage):
383
- known_cache.storage.close()
386
+ try:
387
+ known_cache.storage.close() # type: ignore
388
+ except AttributeError:
389
+ pass
384
390
 
385
391
  known_cache.storage = self._create_storage(
386
392
  func_name=known_cache.func_name,
@@ -6,6 +6,7 @@ a collection of arguments to the return value.
6
6
  """
7
7
 
8
8
  from abc import ABC, abstractmethod
9
+ from collections.abc import Callable
9
10
  import dataclasses
10
11
  from datetime import datetime, timezone
11
12
  import functools
@@ -152,6 +153,9 @@ class SQLiteCacheStorage[V](TypedCacheStorage[V]):
152
153
  con: sqlite3.Connection
153
154
 
154
155
  def __init__(self, database: str | Path, *, data_type: Any):
156
+ if database != ":memory:":
157
+ Path(database).parent.mkdir(exist_ok=True, parents=True)
158
+
155
159
  self.con = sqlite3.connect(database)
156
160
  self.con.execute("PRAGMA journal_mode = WAL;")
157
161
  self.con.execute("PRAGMA synchronous = NORMAL;")
@@ -299,6 +303,51 @@ class SQLiteCacheStorage[V](TypedCacheStorage[V]):
299
303
  raise KeyError(key)
300
304
 
301
305
 
306
+ class LazyCacheStorage[V](CacheStorage[V]):
307
+ """
308
+ LazyCacheStorage is a lazy wrapper around an underlying CacheStorage
309
+ instance, and doesn't instantiate it until somebody interacts with
310
+ the cache.
311
+ """
312
+
313
+ _create_underlying: Callable[[], CacheStorage[V]]
314
+ _underlying: CacheStorage[V] | None
315
+
316
+ def __init__(self, create_underlying: Callable[[], CacheStorage[V]]):
317
+ self._create_underlying = create_underlying
318
+ self._underlying = None
319
+
320
+ def __getattr__(self, name: str) -> Any:
321
+ """
322
+ When looking up any property or method, forward to the underlying
323
+ cache storage, ensuring it exists first.
324
+ """
325
+ if self._underlying is None:
326
+ self._underlying = self._create_underlying()
327
+ return getattr(self._underlying, name)
328
+
329
+ def set(self, key: dict[str, Any], value: V) -> None:
330
+ """
331
+ Save a key-value pair in the cache.
332
+
333
+ Throws an exception if you overwrite an existing key with
334
+ a different value.
335
+ """
336
+ if self._underlying is None:
337
+ self._underlying = self._create_underlying()
338
+ return self._underlying.set(key, value)
339
+
340
+ def get(self, key: dict[str, Any]) -> V:
341
+ """
342
+ Look up the value of a key in the cache.
343
+
344
+ Throws a KeyError if you look up a key which isn't in the cache.
345
+ """
346
+ if self._underlying is None:
347
+ self._underlying = self._create_underlying()
348
+ return self._underlying.get(key)
349
+
350
+
302
351
  def _encode_key_as_json(key: dict[str, Any]) -> str:
303
352
  """
304
353
  Encode a set of arguments to a Python function as a JSON string.
@@ -312,6 +361,8 @@ def _encode_key_as_json(key: dict[str, Any]) -> str:
312
361
 
313
362
  This function must not mutate its input.
314
363
  """
364
+ # TODO: How do we handle lazy generators/iterators as the input key?
365
+
315
366
  reduced_key = {k: _process_value(v) for k, v in key.items()}
316
367
 
317
368
  try:
@@ -366,7 +417,6 @@ def _process_value(val: Any) -> Any:
366
417
  # go directly into the dict() branch. This reduces isinstance and
367
418
  # is_dataclass calls.
368
419
  elif isinstance(val, BaseModel) or dataclasses.is_dataclass(val):
369
- # print(type(val))
370
420
  adapter = _get_type_adapter(type(val))
371
421
  dumped = adapter.dump_python(val, mode="json")
372
422
  return _process_value(dumped)
@@ -2,4 +2,4 @@
2
2
  The FunkyCache version.
3
3
  """
4
4
 
5
- __version__ = "1.0.4"
5
+ __version__ = "1.0.5"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: funkycache
3
- Version: 1.0.4
3
+ Version: 1.0.5
4
4
  Summary: A SQLite-backed function cache that tracks file dependencies
5
5
  Author-email: Alex Chan <alex@alexwlchan.net>
6
6
  Maintainer-email: Alex Chan <alex@alexwlchan.net>
@@ -21,7 +21,8 @@ Dynamic: license-file
21
21
  funkycache is a disk-backed cache for Python functions that tracks file dependencies.
22
22
  I use it in my static site generator to cache the output of expensive functions.
23
23
 
24
- Example:
24
+ To cache the output of a function, create a `FunkyCache` instance, then apply the `cache.register` decorator.
25
+ For example:
25
26
 
26
27
  ```python
27
28
  from funkycache import FunkyCache
@@ -50,6 +51,22 @@ If those dependent values change, the function's cache is invalidated, and the n
50
51
  **Note:** funkycache does not watch the filesystem.
51
52
  It is your responsibility to notify it of changes to dependent files, or they will be noticed when the Python process restarts.
52
53
 
54
+ ## Caching requirements
55
+
56
+ To cache a function with funkycache, the function must:
57
+
58
+ * Have a type hint with a return annotation
59
+ * Always return an identical result when given identical inputs
60
+ * Not have any side effects (for example, creating a file)
61
+
62
+ ## Design
63
+
64
+ * Each function has an independent cache
65
+ * Cache keys are the function arguments, serialised as JSON and hashed using XXH64
66
+ * Cache values are the return value, serialised as JSON
67
+
68
+ For more information about how funkycache works, read [my design notes][me-funkycache-intro].
69
+
53
70
  ## Installation
54
71
 
55
72
  Install using pip:
@@ -61,3 +78,6 @@ $ pip install funkycache
61
78
  ## License
62
79
 
63
80
  This project is shared under the [MIT license](./LICENSE).
81
+
82
+ [me-funkycache-intro]: https://alexwlchan.net/2026/funkycache/
83
+ [wiki-pure]: https://en.wikipedia.org/wiki/Pure_function
@@ -778,11 +778,16 @@ class TestSQLiteFunkyCache(FunkyCacheTestSuite):
778
778
  root = tmp_path / ".cache"
779
779
  c = FunkyCache(storage="sqlite", root=root)
780
780
 
781
- @c.register(files=[tmp_path / "greeting.txt"])
782
- def double(n: int) -> int:
783
- return n * 2
781
+ p = tmp_path / "greeting.txt"
782
+ greeting1 = "bonjour monde"
783
+ greeting2 = "hello world"
784
784
 
785
- assert double(5) == 10
785
+ @c.register(files=[p])
786
+ def get_size() -> int:
787
+ return Path(p).stat().st_size
788
+
789
+ p.write_text(greeting1)
790
+ assert get_size() == len(greeting1)
786
791
 
787
792
  # After populating the cache, there's a single set of SQLite files
788
793
  # in the .cache directory
@@ -790,11 +795,12 @@ class TestSQLiteFunkyCache(FunkyCacheTestSuite):
790
795
  assert len(stem1) == 1
791
796
 
792
797
  # Invalidate the cache
793
- p = tmp_path / "greeting.txt"
794
- p.write_text("hello world")
798
+ p.write_text(greeting2)
795
799
  c.notify_path_change(p)
796
800
 
797
- # There should be a new set of SQLite files in the .cache directory
801
+ # After we call the function again, it creates a different SQLite db
802
+ # in the .cache directory
803
+ assert get_size() == len(greeting2)
798
804
  stem2 = {p.stem for p in root.iterdir()}
799
805
  assert len(stem2) == 1
800
806
  assert stem1 != stem2
@@ -926,6 +932,28 @@ class TestSQLiteFunkyCache(FunkyCacheTestSuite):
926
932
  def double(n: int) -> int: # pragma: no cover
927
933
  return n * 2
928
934
 
935
+ def test_db_is_lazy(self, tmp_path: Path) -> None:
936
+ """
937
+ The underlying SQLite database is only created when you interact
938
+ with it for the first time; empty caches are never created.
939
+ """
940
+ cache_root = tmp_path / ".funkycache/tests"
941
+
942
+ # Creating a FunkyCache instance doesn't create the db
943
+ cache = FunkyCache(storage="sqlite", root=cache_root)
944
+ assert not cache_root.exists()
945
+
946
+ # Registering a function doesn't create the db
947
+ @cache.register
948
+ def greet(name: str) -> str:
949
+ return f"Hello {name}!"
950
+
951
+ assert not cache_root.exists()
952
+
953
+ # Creating a cache entry creates the db
954
+ assert greet("Alex") == "Hello Alex!"
955
+ assert cache_root.exists()
956
+
929
957
 
930
958
  def test_canonical_name_varies_by_path(tmp_path: Path) -> None:
931
959
  """
@@ -19,6 +19,7 @@ from _pytest.mark.structures import ParameterSet
19
19
  from funkycache.storage import (
20
20
  CacheStorage,
21
21
  MemoryCacheStorage,
22
+ LazyCacheStorage,
22
23
  SQLiteCacheStorage,
23
24
  CannotOverwriteValueException,
24
25
  _encode_key_as_json,
@@ -247,6 +248,101 @@ class TestSQLiteCacheStorage(CacheStorageTestSuite):
247
248
  with pytest.raises(sqlite3.OperationalError, match="no such column: key"):
248
249
  SQLiteCacheStorage[int](db_path, data_type="int")
249
250
 
251
+ def test_creates_parent_dir(self, tmp_path: Path) -> None:
252
+ """
253
+ Creating the storage creates the parent directory for the
254
+ database file.
255
+ """
256
+ db_path = tmp_path / "a/b/c/cache.db"
257
+
258
+ with SQLiteCacheStorage[int](db_path, data_type=int):
259
+ pass
260
+
261
+ assert db_path.exists()
262
+
263
+
264
+ class LazyCacheStorageTestSuite(CacheStorageTestSuite):
265
+ """
266
+ Tests for LazyCacheStorage.
267
+ """
268
+
269
+ def test_storage_is_lazy(self, tmp_path: Path) -> None:
270
+ """
271
+ The underlying storage isn't created until you interact with
272
+ the storage.
273
+ """
274
+ with self.create_storage(tmp_path, data_type=str) as storage:
275
+ assert isinstance(storage, LazyCacheStorage)
276
+ assert storage._underlying is None
277
+
278
+ with pytest.raises(KeyError):
279
+ storage.get({"one": 1})
280
+
281
+ assert storage._underlying is not None
282
+
283
+ def test_unknown_getattr_is_forwarded_to_underlying(self, tmp_path: Path) -> None:
284
+ """
285
+ Looking up an unknown attribute with __getattr__ is forwarded
286
+ to the underlying storage.
287
+ """
288
+ with self.create_storage(tmp_path, data_type=str) as storage:
289
+ assert isinstance(storage, LazyCacheStorage)
290
+ assert storage._underlying is None
291
+
292
+ with pytest.raises(AttributeError):
293
+ getattr(storage, "does_not_exist")
294
+
295
+ assert storage._underlying is not None
296
+
297
+
298
+ class TestLazyMemoryCacheStorage(LazyCacheStorageTestSuite, TestMemoryCacheStorage):
299
+ """
300
+ Tests for MemoryCacheStorage wrapped in LazyCacheStorage.
301
+ """
302
+
303
+ @contextmanager
304
+ def create_storage[V](
305
+ self, tmp_path: Path, data_type: Any
306
+ ) -> Generator[CacheStorage[V]]:
307
+ """
308
+ Create a lazy cache storage backend.
309
+ """
310
+ yield LazyCacheStorage(create_underlying=lambda: MemoryCacheStorage())
311
+
312
+
313
+ class TestLazySQLiteCacheStorage(LazyCacheStorageTestSuite, TestSQLiteCacheStorage):
314
+ """
315
+ Tests for SQLiteCacheStorage wrapped in LazyCacheStorage.
316
+ """
317
+
318
+ @contextmanager
319
+ def create_storage[V](
320
+ self, tmp_path: Path, data_type: Any
321
+ ) -> Generator[CacheStorage[V]]:
322
+ """
323
+ Create a lazy cache storage backend.
324
+ """
325
+ storage = LazyCacheStorage(
326
+ create_underlying=lambda: SQLiteCacheStorage(
327
+ ":memory:", data_type=data_type
328
+ )
329
+ )
330
+ yield storage
331
+ storage.close()
332
+
333
+ def test_db_file_not_created_if_unused(self, tmp_path: Path) -> None:
334
+ """
335
+ If you never interact with the cache, neither the database
336
+ nor the enclosing folder are created.
337
+ """
338
+ db_path = tmp_path / "a/b/c/example.db"
339
+
340
+ with self.create_storage(db_path, data_type=str):
341
+ pass
342
+
343
+ assert not db_path.exists()
344
+ assert not db_path.parent.exists()
345
+
250
346
 
251
347
  class Shape(BaseModel):
252
348
  """A basic model that uses Pydantic."""
File without changes
File without changes
File without changes