funkycache 1.0.2__tar.gz → 1.0.3__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.2
3
+ Version: 1.0.3
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>
@@ -5,15 +5,25 @@ Ensure each function has an independent cache.
5
5
  """
6
6
 
7
7
  import atexit
8
- from collections.abc import Callable, Sequence
8
+ from collections.abc import Callable, Generator, Sequence
9
9
  from dataclasses import dataclass
10
10
  from functools import wraps
11
11
  import inspect
12
12
  import itertools
13
13
  import json
14
14
  from pathlib import Path
15
+ import pickle
15
16
  import typing
16
- from typing import Any, cast, Literal, overload, ParamSpec, Protocol, TypeVar
17
+ from typing import (
18
+ Any,
19
+ cast,
20
+ Literal,
21
+ NamedTuple,
22
+ overload,
23
+ ParamSpec,
24
+ Protocol,
25
+ TypeVar,
26
+ )
17
27
  import warnings
18
28
 
19
29
  import xxhash
@@ -161,7 +171,11 @@ class FunkyCache:
161
171
 
162
172
  @overload
163
173
  def register[**P, R](
164
- self, *, files: list[Path | str] | None = None, values: list[Any] | None = None
174
+ self,
175
+ *,
176
+ files: list[Path | str] | None = None,
177
+ values: list[Any] | None = None,
178
+ max_memory: int | None = None,
165
179
  ) -> Callable[[F], F]: ...
166
180
 
167
181
  def register[**P, R](
@@ -170,6 +184,7 @@ class FunkyCache:
170
184
  *,
171
185
  files: list[Path | str] | None = None,
172
186
  values: list[Any] | None = None,
187
+ max_memory: int | None = None,
173
188
  ) -> F:
174
189
  """
175
190
  Cache the input/output of func.
@@ -181,6 +196,10 @@ class FunkyCache:
181
196
 
182
197
  The function's own source file is always a dependency, so editing
183
198
  the code that produced a value also invalidates it on the next run.
199
+
200
+ If the function is a simple generator, you can set a max_memory.
201
+ The memory budget is an approximate, best-effort limit in bytes.
202
+ It's a soft cap, and may be slightly exceeded.
184
203
  """
185
204
 
186
205
  def decorator(func: F) -> F:
@@ -196,6 +215,13 @@ class FunkyCache:
196
215
  "A function cannot depend on a file/folder inside the cache root"
197
216
  )
198
217
 
218
+ # The max_memory argument is only used for generator function;
219
+ # passing it for non-generator functions is an error.
220
+ is_generator = inspect.isgeneratorfunction(func)
221
+
222
+ if not is_generator and max_memory is not None:
223
+ raise TypeError("Do not set max_memory for a non-generator function")
224
+
199
225
  # Check if we already have a cache for this function.
200
226
  #
201
227
  # We must do this before creating the storage, or we could have
@@ -218,8 +244,6 @@ class FunkyCache:
218
244
  bound.apply_defaults()
219
245
  key = bound.arguments
220
246
 
221
- is_generator = inspect.isgeneratorfunction(func)
222
-
223
247
  # We need to look up the CacheStorage in self._known_caches
224
248
  # every time, in case it's changed since the last call.
225
249
  storage = self._known_caches[func_name].storage
@@ -234,25 +258,29 @@ class FunkyCache:
234
258
  except Exception as e:
235
259
  warnings.warn(f"unexpected error looking up key in cache: {e}")
236
260
 
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
261
+ # If the function is a generator, try to consume the entire
262
+ # generator and store that. If it returns too much data
239
263
  # (for example, if it's infinite), bypass the cache to avoid
240
264
  # storing an unbounded amount of info.
265
+ #
266
+ # TODO: decide how to handle generators that receive values.
241
267
  new_value = func(*args, **kwargs)
242
268
  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
269
+ gen_result = _materialise_generator(
270
+ new_value,
271
+ # Default max_memory to 5MB is unspecified by caller
272
+ max_memory=max_memory or 5 * 1024 * 1024,
273
+ )
274
+ if gen_result.is_exhausted:
275
+ new_value = gen_result.list_value
250
276
  else:
251
277
  warnings.warn(
252
- "iterator returned more than 10,000 items; "
278
+ "iterator returned too many items; "
253
279
  "output will not be cached"
254
280
  )
255
- return cast(R, itertools.chain(iter(list_value), new_value))
281
+ return cast(
282
+ R, itertools.chain(iter(gen_result.list_value), new_value)
283
+ )
256
284
 
257
285
  try:
258
286
  storage.set(key, new_value)
@@ -390,8 +418,21 @@ def _data_type(func: F, storage: StorageType) -> Any:
390
418
  if inspect.isgeneratorfunction(func):
391
419
  origin = typing.get_origin(ret_annotation)
392
420
  args = typing.get_args(ret_annotation)
421
+
422
+ # Iterator, Iterable, etc.
393
423
  if origin is not None and len(args) == 1:
394
424
  return list[args[0]] # type: ignore
425
+
426
+ # Generator[YieldType, SendType, ReceiveType]
427
+ elif origin is not None and len(args) == 3:
428
+ if args[1] is None and args[2] is None:
429
+ return list[args[0]] # type: ignore
430
+ else:
431
+ raise TypeError(
432
+ f"{func.__name__} is a generator that sends/receives values; "
433
+ "it cannot be cached."
434
+ )
435
+
395
436
  else:
396
437
  match storage:
397
438
  case "memory":
@@ -510,3 +551,79 @@ def _input_signature(dep_paths: set[Path], values: list[Any]) -> str:
510
551
 
511
552
  json_str = json.dumps(signature, sort_keys=True)
512
553
  return xxhash.xxh64_hexdigest(json_str.encode("utf8"))
554
+
555
+
556
+ class _GeneratorResult[R](NamedTuple):
557
+ """
558
+ _GeneratorResult is the materialised result of a generator function.
559
+ """
560
+
561
+ list_value: list[R]
562
+ is_exhausted: bool
563
+
564
+
565
+ def _materialise_generator[R](
566
+ gen: Generator[R, Any, Any], max_memory: int
567
+ ) -> _GeneratorResult:
568
+ """
569
+ Consume a generator, materialising items into a list until either
570
+ the generator is exhausted or the underlying buffer reaches the
571
+ memory budget.
572
+
573
+ The function returns the materialised list of items, and whether
574
+ the generator was exhausted.
575
+
576
+ The memory budget is an approximate, best-effort limit in bytes.
577
+ It's a soft cap, and may be slightly exceeded.
578
+ """
579
+ # As we go along, we want to measure the total memory used by the list,
580
+ # so we don't exceed our memory budget. Calculating memory usage is
581
+ # moderately expensive, so we do it in batches. We use pending_items
582
+ # to track items we haven't measured the size of yet.
583
+ items: list[R] = []
584
+ pending_items: list[R] = []
585
+ current_bytes = 0
586
+
587
+ # Start by measuring the size of every item, to get a sense of overall
588
+ # trends. We'll increase this later.
589
+ batch_size = 1
590
+ avg_item_size = 0.0
591
+
592
+ for item in gen:
593
+ items.append(item)
594
+ pending_items.append(item)
595
+
596
+ # When the pending batch reaches the threshold, measure all
597
+ # of them.
598
+ if len(pending_items) >= batch_size:
599
+ # Measure the current batch size
600
+ batch_bytes = len(pickle.dumps(pending_items))
601
+ current_bytes += batch_bytes
602
+
603
+ # Check if we've breached our soft cap.
604
+ #
605
+ # We exit slightly below the given cap, because we'll try
606
+ # to get one more item from the generator to determine if
607
+ # it was exhausted. If the generator isn't exhausted, we
608
+ # don't want that item to push us further beyond the cap.
609
+ if current_bytes >= max_memory - avg_item_size:
610
+ break
611
+
612
+ # Count the first ten items 1-by-1, so we get some sense
613
+ # of how large individual items are.
614
+ if len(items) < 10:
615
+ continue
616
+
617
+ # Calculate the average item size of items seen so far,
618
+ # then aim to spend ~10% of our remaining memory budget
619
+ # on the next batch.
620
+ avg_item_size = current_bytes / len(items)
621
+ remaining_memory = max_memory - current_bytes
622
+ batch_size = max(1, min(50, remaining_memory * 0.1 / avg_item_size))
623
+
624
+ try:
625
+ items.append(next(gen))
626
+ except StopIteration:
627
+ return _GeneratorResult(items, is_exhausted=True)
628
+ else:
629
+ return _GeneratorResult(items, is_exhausted=False)
@@ -2,4 +2,4 @@
2
2
  The FunkyCache version.
3
3
  """
4
4
 
5
- __version__ = "1.0.2"
5
+ __version__ = "1.0.3"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: funkycache
3
- Version: 1.0.2
3
+ Version: 1.0.3
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>
@@ -3,7 +3,7 @@ Tests for the FunkyCache cache manager.
3
3
  """
4
4
 
5
5
  from abc import ABC, abstractmethod
6
- from collections.abc import Callable, Iterator, Mapping, Sequence
6
+ from collections.abc import Callable, Generator, Iterator, Mapping, Sequence
7
7
  from collections import Counter
8
8
  import contextlib
9
9
  import inspect
@@ -114,6 +114,42 @@ class FunkyCacheTestSuite(ABC):
114
114
  assert next(n1) == 2
115
115
  assert next(n2) == 1
116
116
 
117
+ def test_cache_simple_generator(self, cache: FunkyCache) -> None:
118
+ """
119
+ You can cache a function which returns a simple generator
120
+ (doesn't receive values).
121
+ """
122
+ # Count how many times the underlying function was called
123
+ calls = Counter[str]()
124
+
125
+ @cache.register
126
+ def numbers(max: int) -> Generator[int, None, None]:
127
+ """
128
+ Numbers yields all the numbers between 1 and max.
129
+ """
130
+ calls[f"max={max}"] += 1
131
+ for i in itertools.count(start=1):
132
+ if i > max:
133
+ break
134
+ yield i
135
+ else: # pragma: no cover
136
+ pass
137
+
138
+ # The first call is a cache miss; goes to the real function
139
+ assert list(numbers(max=3)) == [1, 2, 3]
140
+ assert calls == {"max=3": 1}
141
+
142
+ # The second call is a cache hit; skips the real function
143
+ assert list(numbers(max=3)) == [1, 2, 3]
144
+ assert calls == {"max=3": 1}
145
+
146
+ # Check that every instance of the generator is independent
147
+ n1 = numbers(max=3)
148
+ n2 = numbers(max=3)
149
+ assert next(n1) == 1
150
+ assert next(n1) == 2
151
+ assert next(n2) == 1
152
+
117
153
  def test_infinite_iterator_isnt_cached(self, cache: FunkyCache) -> None:
118
154
  """
119
155
  You can register a cache on a function which returns an infinite
@@ -130,22 +166,95 @@ class FunkyCacheTestSuite(ABC):
130
166
  pass
131
167
 
132
168
  # The first call is a cache miss
133
- with pytest.warns(match="iterator returned more than 10,000 items"):
169
+ with pytest.warns(match="iterator returned too many items"):
134
170
  assert next(greet_forever("Alex")) == "Hello Alex! (0)"
135
171
  assert calls == {"Alex": 1}
136
172
 
137
173
  # The second call is also a cache miss, because the function was
138
174
  # never cached
139
- with pytest.warns(match="iterator returned more than 10,000 items"):
175
+ with pytest.warns(match="iterator returned too many items"):
140
176
  assert next(greet_forever("Alex")) == "Hello Alex! (0)"
141
177
  assert calls == {"Alex": 2}
142
178
 
143
179
  # The cached items are combined with the rest of the iterator
144
- with pytest.warns(match="iterator returned more than 10,000 items"):
180
+ with pytest.warns(match="iterator returned too many items"):
145
181
  assert list(itertools.islice(greet_forever("Alex"), 11000)) == [
146
182
  f"Hello Alex! ({i})" for i in range(11000)
147
183
  ]
148
184
 
185
+ def test_iterator_looks_at_max_memory(self, cache: FunkyCache) -> None:
186
+ """
187
+ If you register the cache on a function that returns more items
188
+ than the max_memory, you get a warning.
189
+ """
190
+ calls = Counter[str]()
191
+
192
+ @cache.register(max_memory=1)
193
+ def greet_forever(name: str) -> Iterator[str]:
194
+ calls[name] += 1
195
+ for i in range(10):
196
+ yield f"Hello {name}! ({i})"
197
+
198
+ # The first call is a cache miss
199
+ with pytest.warns(match="iterator returned too many items"):
200
+ assert next(greet_forever("Alex")) == "Hello Alex! (0)"
201
+ assert calls == {"Alex": 1}
202
+
203
+ # The second call is also a cache miss, because the function was
204
+ # never cached
205
+ with pytest.warns(match="iterator returned too many items"):
206
+ assert next(greet_forever("Alex")) == "Hello Alex! (0)"
207
+ assert calls == {"Alex": 2}
208
+
209
+ # The cached items are combined with the rest of the iterator
210
+ with pytest.warns(match="iterator returned too many items"):
211
+ assert list(greet_forever("Alex")) == [
212
+ f"Hello Alex! ({i})" for i in range(10)
213
+ ]
214
+
215
+ def test_cannot_cache_non_simple_generator(self, cache: FunkyCache) -> None:
216
+ """
217
+ You can't cache a function which returns a non-simple generator
218
+ (sends and receives values).
219
+ """
220
+ G = Generator[float | None, float, None]
221
+
222
+ def running_average() -> G: # pragma: no cover
223
+ """
224
+ Receive numbers via send and yield the current running average.
225
+ """
226
+ total = 0.0
227
+ count = 0
228
+ average = None
229
+
230
+ while True:
231
+ value = yield average
232
+
233
+ if value is None:
234
+ break
235
+
236
+ total += value
237
+ count += 1
238
+ average = total / count
239
+
240
+ with pytest.raises(
241
+ TypeError, match="running_average is a generator that sends/receives values"
242
+ ):
243
+ cache.register(running_average)
244
+
245
+ def test_cannot_use_max_memory_with_non_generator(self, cache: FunkyCache) -> None:
246
+ """
247
+ You can't pass the max_memory argument when caching a non-generator.
248
+ """
249
+ with pytest.raises(
250
+ TypeError, match="Do not set max_memory for a non-generator function"
251
+ ):
252
+
253
+ @cache.register(max_memory=128)
254
+ def greet(name: str) -> str: # pragma: no cover
255
+ """Return a friendly greeting."""
256
+ return f"Hello {name}!"
257
+
149
258
  def test_per_function_caches_are_independent(self, cache: FunkyCache) -> None:
150
259
  """
151
260
  Different functions have different caches.
File without changes
File without changes
File without changes
File without changes