funkycache 1.0.4__tar.gz → 1.0.6__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.6
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,61 @@ 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
+ def close(self) -> None:
351
+ """
352
+ Close the underlying storage.
353
+ """
354
+ if self._underlying is None:
355
+ pass
356
+ if not hasattr(self._underlying, "close"):
357
+ return
358
+ self._underlying.close() # type: ignore
359
+
360
+
302
361
  def _encode_key_as_json(key: dict[str, Any]) -> str:
303
362
  """
304
363
  Encode a set of arguments to a Python function as a JSON string.
@@ -312,6 +371,8 @@ def _encode_key_as_json(key: dict[str, Any]) -> str:
312
371
 
313
372
  This function must not mutate its input.
314
373
  """
374
+ # TODO: How do we handle lazy generators/iterators as the input key?
375
+
315
376
  reduced_key = {k: _process_value(v) for k, v in key.items()}
316
377
 
317
378
  try:
@@ -366,7 +427,6 @@ def _process_value(val: Any) -> Any:
366
427
  # go directly into the dict() branch. This reduces isinstance and
367
428
  # is_dataclass calls.
368
429
  elif isinstance(val, BaseModel) or dataclasses.is_dataclass(val):
369
- # print(type(val))
370
430
  adapter = _get_type_adapter(type(val))
371
431
  dumped = adapter.dump_python(val, mode="json")
372
432
  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.6"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: funkycache
3
- Version: 1.0.4
3
+ Version: 1.0.6
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
@@ -709,6 +709,34 @@ class TestFunkyCache:
709
709
  assert greet("Alex") == "Bonjour Alex!"
710
710
  assert calls == {"Alex": 2}
711
711
 
712
+ def test_lazy_sqlite_cache(self, tmp_path: Path) -> None:
713
+ """
714
+ If you cache a function with SQLite but never call it, the underlying
715
+ database is never created.
716
+
717
+ This is a regression test for a bug in v1.0.5 where closing the
718
+ storage would create the database.
719
+ """
720
+ p = tmp_path / "example.py"
721
+
722
+ p.write_text(
723
+ textwrap.dedent("""
724
+ from funkycache import FunkyCache
725
+
726
+ GREETING = "hello world"
727
+
728
+ cache = FunkyCache(storage="sqlite", root=".cache")
729
+
730
+ @cache.register
731
+ def greet() -> str:
732
+ return GREETING
733
+ """)
734
+ )
735
+
736
+ subprocess.check_call(["python3", str(p)], cwd=tmp_path)
737
+
738
+ assert not (tmp_path / ".cache").exists()
739
+
712
740
 
713
741
  class TestMemoryFunkyCache(FunkyCacheTestSuite):
714
742
  """
@@ -778,11 +806,16 @@ class TestSQLiteFunkyCache(FunkyCacheTestSuite):
778
806
  root = tmp_path / ".cache"
779
807
  c = FunkyCache(storage="sqlite", root=root)
780
808
 
781
- @c.register(files=[tmp_path / "greeting.txt"])
782
- def double(n: int) -> int:
783
- return n * 2
809
+ p = tmp_path / "greeting.txt"
810
+ greeting1 = "bonjour monde"
811
+ greeting2 = "hello world"
784
812
 
785
- assert double(5) == 10
813
+ @c.register(files=[p])
814
+ def get_size() -> int:
815
+ return Path(p).stat().st_size
816
+
817
+ p.write_text(greeting1)
818
+ assert get_size() == len(greeting1)
786
819
 
787
820
  # After populating the cache, there's a single set of SQLite files
788
821
  # in the .cache directory
@@ -790,11 +823,12 @@ class TestSQLiteFunkyCache(FunkyCacheTestSuite):
790
823
  assert len(stem1) == 1
791
824
 
792
825
  # Invalidate the cache
793
- p = tmp_path / "greeting.txt"
794
- p.write_text("hello world")
826
+ p.write_text(greeting2)
795
827
  c.notify_path_change(p)
796
828
 
797
- # There should be a new set of SQLite files in the .cache directory
829
+ # After we call the function again, it creates a different SQLite db
830
+ # in the .cache directory
831
+ assert get_size() == len(greeting2)
798
832
  stem2 = {p.stem for p in root.iterdir()}
799
833
  assert len(stem2) == 1
800
834
  assert stem1 != stem2
@@ -926,6 +960,28 @@ class TestSQLiteFunkyCache(FunkyCacheTestSuite):
926
960
  def double(n: int) -> int: # pragma: no cover
927
961
  return n * 2
928
962
 
963
+ def test_db_is_lazy(self, tmp_path: Path) -> None:
964
+ """
965
+ The underlying SQLite database is only created when you interact
966
+ with it for the first time; empty caches are never created.
967
+ """
968
+ cache_root = tmp_path / ".funkycache/tests"
969
+
970
+ # Creating a FunkyCache instance doesn't create the db
971
+ cache = FunkyCache(storage="sqlite", root=cache_root)
972
+ assert not cache_root.exists()
973
+
974
+ # Registering a function doesn't create the db
975
+ @cache.register
976
+ def greet(name: str) -> str:
977
+ return f"Hello {name}!"
978
+
979
+ assert not cache_root.exists()
980
+
981
+ # Creating a cache entry creates the db
982
+ assert greet("Alex") == "Hello Alex!"
983
+ assert cache_root.exists()
984
+
929
985
 
930
986
  def test_canonical_name_varies_by_path(tmp_path: Path) -> None:
931
987
  """
@@ -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,102 @@ 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
+ for name in ("does_not_exist1", "does_not_exist2", "does_not_exist3"):
293
+ with pytest.raises(AttributeError):
294
+ getattr(storage, name)
295
+
296
+ assert storage._underlying is not None
297
+
298
+
299
+ class TestLazyMemoryCacheStorage(LazyCacheStorageTestSuite, TestMemoryCacheStorage):
300
+ """
301
+ Tests for MemoryCacheStorage wrapped in LazyCacheStorage.
302
+ """
303
+
304
+ @contextmanager
305
+ def create_storage[V](
306
+ self, tmp_path: Path, data_type: Any
307
+ ) -> Generator[CacheStorage[V]]:
308
+ """
309
+ Create a lazy cache storage backend.
310
+ """
311
+ yield LazyCacheStorage(create_underlying=lambda: MemoryCacheStorage())
312
+
313
+
314
+ class TestLazySQLiteCacheStorage(LazyCacheStorageTestSuite, TestSQLiteCacheStorage):
315
+ """
316
+ Tests for SQLiteCacheStorage wrapped in LazyCacheStorage.
317
+ """
318
+
319
+ @contextmanager
320
+ def create_storage[V](
321
+ self, tmp_path: Path, data_type: Any
322
+ ) -> Generator[CacheStorage[V]]:
323
+ """
324
+ Create a lazy cache storage backend.
325
+ """
326
+ storage = LazyCacheStorage(
327
+ create_underlying=lambda: SQLiteCacheStorage(
328
+ ":memory:", data_type=data_type
329
+ )
330
+ )
331
+ yield storage
332
+ storage.close()
333
+
334
+ def test_db_file_not_created_if_unused(self, tmp_path: Path) -> None:
335
+ """
336
+ If you never interact with the cache, neither the database
337
+ nor the enclosing folder are created.
338
+ """
339
+ db_path = tmp_path / "a/b/c/example.db"
340
+
341
+ with self.create_storage(db_path, data_type=str):
342
+ pass
343
+
344
+ assert not db_path.exists()
345
+ assert not db_path.parent.exists()
346
+
250
347
 
251
348
  class Shape(BaseModel):
252
349
  """A basic model that uses Pydantic."""
File without changes
File without changes
File without changes