checkpointer 2.8.1__py3-none-any.whl → 2.9.1__py3-none-any.whl

checkpointer/checkpoint.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 import inspect
 import re
+from contextlib import suppress
 from datetime import datetime
-from functools import update_wrapper
+from functools import cached_property, update_wrapper
 from pathlib import Path
-from typing import Any, Awaitable, Callable, Generic, Iterable, Literal, ParamSpec, Type, TypedDict, TypeVar, Unpack, cast, overload
+from typing import Awaitable, Callable, Generic, Iterable, Literal, ParamSpec, Type, TypedDict, TypeVar, Unpack, cast, overload
 from .fn_ident import get_fn_ident
 from .object_hash import ObjectHash
 from .print_checkpoint import print_checkpoint
@@ -54,84 +55,83 @@ class Checkpointer:
 
 class CheckpointFn(Generic[Fn]):
   def __init__(self, checkpointer: Checkpointer, fn: Fn):
-    self.checkpointer = checkpointer
-    self.fn = fn
-
-  def _set_ident(self, force=False):
-    if not hasattr(self, "fn_hash_raw") or force:
-      self.fn_hash_raw, self.depends = get_fn_ident(unwrap_fn(self.fn), self.checkpointer.capture)
-    return self
-
-  def _lazyinit(self):
-    params = self.checkpointer
-    wrapped = unwrap_fn(self.fn)
+    wrapped = unwrap_fn(fn)
     fn_file = Path(wrapped.__code__.co_filename).name
     fn_name = re.sub(r"[^\w.]", "", wrapped.__qualname__)
+    Storage = STORAGE_MAP[checkpointer.format] if isinstance(checkpointer.format, str) else checkpointer.format
     update_wrapper(cast(Callable, self), wrapped)
-    Storage = STORAGE_MAP[params.format] if isinstance(params.format, str) else params.format
-    deep_hashes = [child._set_ident().fn_hash_raw for child in iterate_checkpoint_fns(self)]
-    self.fn_hash = str(params.fn_hash or ObjectHash(digest_size=16).write_text(self.fn_hash_raw, *deep_hashes))
-    self.fn_subdir = f"{fn_file}/{fn_name}/{self.fn_hash[:32]}"
+    self.checkpointer = checkpointer
+    self.fn = fn
+    self.fn_dir = f"{fn_file}/{fn_name}"
     self.storage = Storage(self)
     self.cleanup = self.storage.cleanup
 
-  def __getattribute__(self, name: str) -> Any:
-    return object.__getattribute__(self, "_getattribute")(name)
+  @cached_property
+  def ident_tuple(self) -> tuple[str, list[Callable]]:
+    return get_fn_ident(unwrap_fn(self.fn), self.checkpointer.capture)
+
+  @property
+  def fn_hash_raw(self) -> str:
+    return self.ident_tuple[0]
+
+  @property
+  def depends(self) -> list[Callable]:
+    return self.ident_tuple[1]
 
-  def _getattribute(self, name: str) -> Any:
-    setattr(self, "_getattribute", super().__getattribute__)
-    self._lazyinit()
-    return self._getattribute(name)
+  @cached_property
+  def fn_hash(self) -> str:
+    fn_hash = self.checkpointer.fn_hash
+    deep_hashes = [depend.fn_hash_raw for depend in self.deep_depends()]
+    return str(fn_hash or ObjectHash(digest_size=16).write_text(self.fn_hash_raw, *deep_hashes))[:32]
 
   def reinit(self, recursive=False) -> CheckpointFn[Fn]:
-    pointfns = list(iterate_checkpoint_fns(self)) if recursive else [self]
-    for pointfn in pointfns:
-      pointfn._set_ident(True)
-    for pointfn in pointfns:
-      pointfn._lazyinit()
+    depends = list(self.deep_depends()) if recursive else [self]
+    for depend in depends:
+      with suppress(AttributeError):
+        del depend.ident_tuple, depend.fn_hash
+    for depend in depends:
+      depend.fn_hash
     return self
 
-  def get_checkpoint_id(self, args: tuple, kw: dict) -> str:
+  def get_call_id(self, args: tuple, kw: dict) -> str:
     hash_by = self.checkpointer.hash_by
     hash_params = hash_by(*args, **kw) if hash_by else (args, kw)
-    call_hash = ObjectHash(hash_params, digest_size=16)
-    return f"{self.fn_subdir}/{call_hash}"
+    return str(ObjectHash(hash_params, digest_size=16))
 
-  async def _resolve_awaitable(self, checkpoint_path: Path, awaitable: Awaitable):
+  async def _resolve_awaitable(self, checkpoint_id: str, awaitable: Awaitable):
     data = await awaitable
-    self.storage.store(checkpoint_path, AwaitableValue(data))
+    self.storage.store(checkpoint_id, AwaitableValue(data))
     return data
 
-  def _store_on_demand(self, args: tuple, kw: dict, rerun: bool):
+  def _call(self, args: tuple, kw: dict, rerun=False):
     params = self.checkpointer
-    checkpoint_id = self.get_checkpoint_id(args, kw)
-    checkpoint_path = params.root_path / checkpoint_id
+    if not params.when:
+      return self.fn(*args, **kw)
+
+    call_id = self.get_call_id(args, kw)
+    call_id_long = f"{self.fn_dir}/{self.fn_hash}/{call_id}"
+
     refresh = rerun \
-      or not self.storage.exists(checkpoint_path) \
-      or (params.should_expire and params.should_expire(self.storage.checkpoint_date(checkpoint_path)))
+      or not self.storage.exists(call_id) \
+      or (params.should_expire and params.should_expire(self.storage.checkpoint_date(call_id)))
 
     if refresh:
-      print_checkpoint(params.verbosity >= 1, "MEMORIZING", checkpoint_id, "blue")
+      print_checkpoint(params.verbosity >= 1, "MEMORIZING", call_id_long, "blue")
       data = self.fn(*args, **kw)
       if inspect.isawaitable(data):
-        return self._resolve_awaitable(checkpoint_path, data)
+        return self._resolve_awaitable(call_id, data)
       else:
-        self.storage.store(checkpoint_path, data)
+        self.storage.store(call_id, data)
         return data
 
     try:
-      data = self.storage.load(checkpoint_path)
-      print_checkpoint(params.verbosity >= 2, "REMEMBERED", checkpoint_id, "green")
+      data = self.storage.load(call_id)
+      print_checkpoint(params.verbosity >= 2, "REMEMBERED", call_id_long, "green")
       return data
     except (EOFError, FileNotFoundError):
       pass
-    print_checkpoint(params.verbosity >= 1, "CORRUPTED", checkpoint_id, "yellow")
-    return self._store_on_demand(args, kw, True)
-
-  def _call(self, args: tuple, kw: dict, rerun=False):
-    if not self.checkpointer.when:
-      return self.fn(*args, **kw)
-    return self._store_on_demand(args, kw, rerun)
+    print_checkpoint(params.verbosity >= 1, "CORRUPTED", call_id_long, "yellow")
+    return self._call(args, kw, True)
 
   __call__: Fn = cast(Fn, lambda self, *args, **kw: self._call(args, kw))
   rerun: Fn = cast(Fn, lambda self, *args, **kw: self._call(args, kw, True))
@@ -142,25 +142,29 @@ class CheckpointFn(Generic[Fn]):
   def get(self: Callable[P, R], *args: P.args, **kw: P.kwargs) -> R: ...
 
   def get(self, *args, **kw):
-    checkpoint_path = self.checkpointer.root_path / self.get_checkpoint_id(args, kw)
+    call_id = self.get_call_id(args, kw)
     try:
-      data = self.storage.load(checkpoint_path)
+      data = self.storage.load(call_id)
       return data.value if isinstance(data, AwaitableValue) else data
     except Exception as ex:
       raise CheckpointError("Could not load checkpoint") from ex
 
   def exists(self: Callable[P, R], *args: P.args, **kw: P.kwargs) -> bool: # type: ignore
     self = cast(CheckpointFn, self)
-    return self.storage.exists(self.checkpointer.root_path / self.get_checkpoint_id(args, kw))
+    return self.storage.exists(self.get_call_id(args, kw))
+
+  def delete(self: Callable[P, R], *args: P.args, **kw: P.kwargs): # type: ignore
+    self = cast(CheckpointFn, self)
+    self.storage.delete(self.get_call_id(args, kw))
 
   def __repr__(self) -> str:
     return f"<CheckpointFn {self.fn.__name__} {self.fn_hash[:6]}>"
 
-def iterate_checkpoint_fns(pointfn: CheckpointFn, visited: set[CheckpointFn] = set()) -> Iterable[CheckpointFn]:
-  visited = visited or set()
-  if pointfn not in visited:
-    yield pointfn
-    visited.add(pointfn)
-    for depend in pointfn.depends:
-      if isinstance(depend, CheckpointFn):
-        yield from iterate_checkpoint_fns(depend, visited)
+  def deep_depends(self, visited: set[CheckpointFn] = set()) -> Iterable[CheckpointFn]:
+    if self not in visited:
+      yield self
+      visited = visited or set()
+      visited.add(self)
+      for depend in self.depends:
+        if isinstance(depend, CheckpointFn):
+          yield from depend.deep_depends(visited)

checkpointer/storages/memory_storage.py

@@ -5,35 +5,32 @@ from .storage import Storage
 
 item_map: dict[Path, dict[str, tuple[datetime, Any]]] = {}
 
-def get_short_path(path: Path):
-  return path.parts[-1]
-
 class MemoryStorage(Storage):
   def get_dict(self):
-    return item_map.setdefault(self.checkpointer.root_path / self.checkpoint_fn.fn_subdir, {})
+    return item_map.setdefault(self.fn_dir(), {})
 
-  def store(self, path, data):
-    self.get_dict()[get_short_path(path)] = (datetime.now(), data)
+  def store(self, call_id, data):
+    self.get_dict()[call_id] = (datetime.now(), data)
 
-  def exists(self, path):
-    return get_short_path(path) in self.get_dict()
+  def exists(self, call_id):
+    return call_id in self.get_dict()
 
-  def checkpoint_date(self, path):
-    return self.get_dict()[get_short_path(path)][0]
+  def checkpoint_date(self, call_id):
+    return self.get_dict()[call_id][0]
 
-  def load(self, path):
-    return self.get_dict()[get_short_path(path)][1]
+  def load(self, call_id):
+    return self.get_dict()[call_id][1]
 
-  def delete(self, path):
-    del self.get_dict()[get_short_path(path)]
+  def delete(self, call_id):
+    self.get_dict().pop(call_id, None)
 
   def cleanup(self, invalidated=True, expired=True):
-    curr_key = self.checkpointer.root_path / self.checkpoint_fn.fn_subdir
+    curr_key = self.fn_dir()
     for key, calldict in list(item_map.items()):
       if key.parent == curr_key.parent:
         if invalidated and key != curr_key:
           del item_map[key]
         elif expired and self.checkpointer.should_expire:
-          for callid, (date, _) in list(calldict.items()):
+          for call_id, (date, _) in list(calldict.items()):
             if self.checkpointer.should_expire(date):
-              del calldict[callid]
+              del calldict[call_id]

checkpointer/storages/pickle_storage.py

@@ -1,35 +1,34 @@
 import pickle
 import shutil
-from pathlib import Path
 from datetime import datetime
 from .storage import Storage
 
-def get_path(path: Path):
-  return path.with_name(f"{path.name}.pkl")
-
 class PickleStorage(Storage):
-  def store(self, path, data):
-    full_path = get_path(path)
-    full_path.parent.mkdir(parents=True, exist_ok=True)
-    with full_path.open("wb") as file:
+  def get_path(self, call_id: str):
+    return self.fn_dir() / f"{call_id}.pkl"
+
+  def store(self, call_id, data):
+    path = self.get_path(call_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("wb") as file:
       pickle.dump(data, file, -1)
 
-  def exists(self, path):
-    return get_path(path).exists()
+  def exists(self, call_id):
+    return self.get_path(call_id).exists()
 
-  def checkpoint_date(self, path):
+  def checkpoint_date(self, call_id):
     # Should use st_atime/access time?
-    return datetime.fromtimestamp(get_path(path).stat().st_mtime)
+    return datetime.fromtimestamp(self.get_path(call_id).stat().st_mtime)
 
-  def load(self, path):
-    with get_path(path).open("rb") as file:
+  def load(self, call_id):
+    with self.get_path(call_id).open("rb") as file:
       return pickle.load(file)
 
-  def delete(self, path):
-    get_path(path).unlink(missing_ok=True)
+  def delete(self, call_id):
+    self.get_path(call_id).unlink(missing_ok=True)
 
   def cleanup(self, invalidated=True, expired=True):
-    version_path = self.checkpointer.root_path.resolve() / self.checkpoint_fn.fn_subdir
+    version_path = self.fn_dir()
     fn_path = version_path.parent
     if invalidated:
       old_dirs = [path for path in fn_path.iterdir() if path.is_dir() and path != version_path]
@@ -39,8 +38,7 @@ class PickleStorage(Storage):
     if expired and self.checkpointer.should_expire:
       count = 0
       for pkl_path in fn_path.rglob("*.pkl"):
-        path = pkl_path.with_suffix("")
-        if self.checkpointer.should_expire(self.checkpoint_date(path)):
+        if self.checkpointer.should_expire(self.checkpoint_date(pkl_path.stem)):
           count += 1
-          self.delete(path)
+          self.delete(pkl_path.stem)
       print(f"Removed {count} expired checkpoints for {self.checkpoint_fn.__qualname__}")

checkpointer/storages/storage.py

@@ -14,14 +14,20 @@ class Storage:
     self.checkpointer = checkpoint_fn.checkpointer
     self.checkpoint_fn = checkpoint_fn
 
-  def store(self, path: Path, data: Any) -> None: ...
+  def fn_id(self) -> str:
+    return f"{self.checkpoint_fn.fn_dir}/{self.checkpoint_fn.fn_hash}"
 
-  def exists(self, path: Path) -> bool: ...
+  def fn_dir(self) -> Path:
+    return self.checkpointer.root_path / self.fn_id()
 
-  def checkpoint_date(self, path: Path) -> datetime: ...
+  def store(self, call_id: str, data: Any) -> None: ...
 
-  def load(self, path: Path) -> Any: ...
+  def exists(self, call_id: str) -> bool: ...
 
-  def delete(self, path: Path) -> None: ...
+  def checkpoint_date(self, call_id: str) -> datetime: ...
+
+  def load(self, call_id: str) -> Any: ...
+
+  def delete(self, call_id: str) -> None: ...
 
   def cleanup(self, invalidated=True, expired=True): ...

checkpointer/test_checkpointer.py

@@ -142,7 +142,7 @@ def test_depends():
   assert set(test_a.depends) == {test_a.fn, helper, multiply_wrapper, global_multiply}
   assert set(test_b.depends) == {test_b.fn, test_a, multiply_wrapper, global_multiply}
 
-def test_lazy_init():
+def test_lazy_init_1():
   @checkpoint
   def fn1(x: object) -> object:
     return fn2(x)
@@ -151,10 +151,21 @@ def test_lazy_init():
   def fn2(x: object) -> object:
     return fn1(x)
 
-  assert type(object.__getattribute__(fn1, "_getattribute")) is MethodType
-  with pytest.raises(AttributeError):
-    object.__getattribute__(fn1, "fn_hash")
-  assert fn1.fn_hash == object.__getattribute__(fn1, "fn_hash")
-  assert type(object.__getattribute__(fn1, "_getattribute")) is MethodWrapperType
+  assert set(fn1.depends) == {fn1.fn, fn2}
+  assert set(fn2.depends) == {fn1, fn2.fn}
+
+def test_lazy_init_2():
+  @checkpoint
+  def fn1(x: object) -> object:
+    return fn2(x)
+
+  assert set(fn1.depends) == {fn1.fn}
+
+  @checkpoint
+  def fn2(x: object) -> object:
+    return fn1(x)
+
+  assert set(fn1.depends) == {fn1.fn}
+  fn1.reinit()
   assert set(fn1.depends) == {fn1.fn, fn2}
   assert set(fn2.depends) == {fn1, fn2.fn}

checkpointer-2.9.1.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: checkpointer
+Version: 2.9.1
+Summary: A Python library for memoizing function results with support for multiple storage backends, async runtimes, and automatic cache invalidation
+Project-URL: Repository, https://github.com/Reddan/checkpointer.git
+Author: Hampus Hallman
+License: Copyright 2018-2025 Hampus Hallman
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# checkpointer · [![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Reddan/checkpointer/blob/master/LICENSE) [![pypi](https://img.shields.io/pypi/v/checkpointer)](https://pypi.org/project/checkpointer/) [![pypi](https://img.shields.io/pypi/pyversions/checkpointer)](https://pypi.org/project/checkpointer/)
+
+`checkpointer` is a Python library providing a decorator-based API for memoizing (caching) function results. It helps you skip redundant, computationally expensive operations, saving execution time and streamlining your workflows.
+
+It works with synchronous and asynchronous functions, supports multiple storage backends, and automatically invalidates caches when function code, dependencies, or captured variables change.
+
+## 📦 Installation
+
+```bash
+pip install checkpointer
+```
+
+## 🚀 Quick Start
+
+Apply the `@checkpoint` decorator to any function:
+
+```python
+from checkpointer import checkpoint
+
+@checkpoint
+def expensive_function(x: int) -> int:
+    print("Computing...")
+    return x ** 2
+
+result = expensive_function(4)  # Computes and stores the result
+result = expensive_function(4)  # Loads from the cache
+```
+
+## 🧠 How It Works
+
+When a function decorated with `@checkpoint` is called:
+
+1.  `checkpointer` computes a unique identifier (hash) for the function call based on its source code, its dependencies, and the arguments passed.
+2.  It attempts to retrieve a cached result using this identifier.
+3.  If a cached result is found, it's returned immediately.
+4.  If no cached result exists or the cache has expired, the original function is executed, its result is stored, and then returned.
+
+### ♻️ Automatic Cache Invalidation
+
+`checkpointer` ensures caches are invalidated automatically when the underlying computation changes. A function's hash, which determines cache validity, updates if:
+
+* **Function Code Changes**: The source code of the decorated function itself is modified.
+* **Dependencies Change**: Any user-defined function in its dependency tree (direct or indirect, even across modules or not decorated with `@checkpoint`) is modified.
+* **Captured Variables Change** (with `capture=True`): Global or closure-based variables used within the function are altered.
+
+**Example: Dependency Invalidation**
+
+```python
+def multiply(a, b):
+    return a * b
+
+@checkpoint
+def helper(x):
+    # Depends on `multiply`
+    return multiply(x + 1, 2)
+
+@checkpoint
+def compute(a, b):
+    # Depends on `helper`
+    return helper(a) + helper(b)
+```
+
+If `multiply` is modified, caches for both `helper` and `compute` will automatically be invalidated and recomputed upon their next call.
+
+## 💡 Usage
+
+Once a function is decorated with `@checkpoint`, you can interact with its caching behavior using the following methods:
+
+* **`expensive_function(...)`**:
+    Call the function normally. This will either compute and cache the result or load it from the cache if available.
+
+* **`expensive_function.rerun(...)`**:
+    Forces the original function to execute, compute a new result, and overwrite any existing cached value for the given arguments.
+
+* **`expensive_function.fn(...)`**:
+    Calls the original, undecorated function directly, bypassing the cache entirely. This is particularly useful within recursive functions to prevent caching intermediate steps.
+
+* **`expensive_function.get(...)`**:
+    Attempts to retrieve the cached result for the given arguments without executing the original function. Raises `CheckpointError` if no valid cached result exists.
+
+* **`expensive_function.exists(...)`**:
+    Checks if a cached result exists for the given arguments without attempting to compute or load it. Returns `True` if a valid checkpoint exists, `False` otherwise.
+
+* **`expensive_function.delete(...)`**:
+    Removes the cached entry for the specified arguments.
+
+* **`expensive_function.reinit()`**:
+    Recalculates the function's internal hash. This is primarily used when `capture=True` and you need to update the cache based on changes to external variables within the same Python session.
+
+## ⚙️ Configuration & Customization
+
+The `@checkpoint` decorator accepts the following parameters to customize its behavior:
+
+* **`format`** (Type: `str` or `checkpointer.Storage`, Default: `"pickle"`)
+    Defines the storage backend to use. Built-in options are `"pickle"` (disk-based, persistent) and `"memory"` (in-memory, non-persistent). You can also provide a custom `Storage` class.
+
+* **`root_path`** (Type: `str` or `pathlib.Path` or `None`, Default: `~/.cache/checkpoints`)
+    The base directory for storing disk-based checkpoints. This parameter is only relevant when `format` is set to `"pickle"`.
+
+* **`when`** (Type: `bool`, Default: `True`)
+    A boolean flag to enable or disable checkpointing for the decorated function. This is particularly useful for toggling caching based on environment variables (e.g., `when=os.environ.get("ENABLE_CACHING", "false").lower() == "true"`).
+
+* **`capture`** (Type: `bool`, Default: `False`)
+    If set to `True`, `checkpointer` includes global or closure-based variables used by the function in its hash calculation. This ensures that changes to these external variables also trigger cache invalidation and recomputation.
+
+* **`should_expire`** (Type: `Callable[[datetime.datetime], bool]`, Default: `None`)
+    A custom callable that receives the `datetime` timestamp of a cached result. It should return `True` if the cached result is considered expired and needs recomputation, or `False` otherwise.
+
+* **`hash_by`** (Type: `Callable[..., Any]`, Default: `None`)
+    A custom callable that takes the function's arguments (`*args`, `**kwargs`) and returns a hashable object (or tuple of objects). This allows for custom argument normalization (e.g., sorting lists before hashing) or optimized hashing for complex input types, which can improve cache hit rates or speed up the hashing process.
+
+* **`fn_hash`** (Type: `checkpointer.ObjectHash`, Default: `None`)
+    An optional parameter that takes an instance of `checkpointer.ObjectHash`. This allows you to override the automatically computed function hash, giving you explicit control over when the function's cache should be invalidated. You can pass any values relevant to your invalidation logic to `ObjectHash` (e.g., `ObjectHash(version_string, config_id, ...)`, as it can consistently hash most Python values.
+
+* **`verbosity`** (Type: `int` (`0`, `1`, or `2`), Default: `1`)
+    Controls the level of logging output from `checkpointer`.
+    * `0`: No output.
+    * `1`: Shows when functions are computed and cached.
+    * `2`: Also shows when cached results are remembered (loaded from cache).
+
+### 🗄️ Custom Storage Backends
+
+For integration with databases, cloud storage, or custom serialization, implement your own storage backend by inheriting from `checkpointer.Storage` and implementing its abstract methods.
+
+Within custom storage methods, `call_id` identifies calls by arguments. Use `self.fn_id()` to get the function's unique identity (name + hash/version), crucial for organizing stored checkpoints (e.g., by function version). Access global `Checkpointer` config via `self.checkpointer`.
+
+#### Example: Custom Storage Backend
+
+```python
+from checkpointer import checkpoint, Storage
+from datetime import datetime
+
+class MyCustomStorage(Storage):
+    def exists(self, call_id):
+        # Example: Constructing a path based on function ID and call ID
+        fn_dir = self.checkpointer.root_path / self.fn_id()
+        return (fn_dir / call_id).exists()
+
+    def checkpoint_date(self, call_id): ...
+    def store(self, call_id, data): ...
+    def load(self, call_id): ...
+    def delete(self, call_id): ...
+
+@checkpoint(format=MyCustomStorage)
+def custom_cached_function(x: int):
+    return x ** 2
+```
+
+## 🧱 Layered Caching
+
+You can apply multiple `@checkpoint` decorators to a single function to create layered caching strategies. `checkpointer` processes these decorators from bottom to top, meaning the decorator closest to the function definition is evaluated first.
+
+This is useful for scenarios like combining a fast, ephemeral cache (e.g., in-memory) with a persistent, slower cache (e.g., disk-based).
+
+**Example: Memory Cache over Disk Cache**
+
+```python
+from checkpointer import checkpoint
+
+@checkpoint(format="memory") # Layer 2: Fast, ephemeral in-memory cache
+@checkpoint(format="pickle") # Layer 1: Persistent disk cache
+def some_expensive_operation():
+    print("Performing a time-consuming operation...")
+    return sum(i for i in range(10**7))
+```
+
+## ⚡ Async Support
+
+`checkpointer` works seamlessly with Python's `asyncio` and other async runtimes.
+
+```python
+import asyncio
+from checkpointer import checkpoint
+
+@checkpoint
+async def async_compute_sum(a: int, b: int) -> int:
+    print(f"Asynchronously computing {a} + {b}...")
+    await asyncio.sleep(1)
+    return a + b
+
+async def main():
+    # First call computes and caches
+    result1 = await async_compute_sum(3, 7)
+    print(f"Result 1: {result1}")
+
+    # Second call loads from cache
+    result2 = await async_compute_sum(3, 7)
+    print(f"Result 2: {result2}")
+
+    # Retrieve from cache without re-running the async function
+    result3 = async_compute_sum.get(3, 7)
+    print(f"Result 3 (from cache): {result3}")
+
+asyncio.run(main())
+```

checkpointer-2.9.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+checkpointer/__init__.py,sha256=HRLsQ24ZhxgmDcHchZ-hX6wA0NMCSedGA0NmCnUdS_c,832
+checkpointer/checkpoint.py,sha256=pbg62Q8gKhx21XEn5kPW95C7ERdQifAg-GAPQN6aWDk,6245
+checkpointer/fn_ident.py,sha256=SWaksNCTlskMom0ztqjECSRjZYPWXUA1p1ZCb-9tWo0,4297
+checkpointer/object_hash.py,sha256=cxuWRDrg4F9wC18aC12zOZYOPv3bk2Qf6tZ0_WgAb6Y,7484
+checkpointer/print_checkpoint.py,sha256=aJCeWMRJiIR3KpyPk_UOKTaD906kArGrmLGQ3LqcVgo,1369
+checkpointer/test_checkpointer.py,sha256=6gLFggsTDNdG2V9ruFlIM8weixd7ES66e5UQYdFX7Dw,3839
+checkpointer/utils.py,sha256=2yk1ksKszXofwnSqBrNCFRSR4C3YLPEAdHUFf-cviRU,2755
+checkpointer/storages/__init__.py,sha256=Kl4Og5jhYxn6m3tB_kTMsabf4_eWVLmFVAoC-pikNQE,301
+checkpointer/storages/bcolz_storage.py,sha256=3QkSUSeG5s2kFuVV_LZpzMn1A5E7kqC7jk7w35c0NyQ,2314
+checkpointer/storages/memory_storage.py,sha256=zfN2B_BgPmI1IcYQPo4ICr2AO6ne_UsEc_tvhbDtXBA,1093
+checkpointer/storages/pickle_storage.py,sha256=WwNg7kmE2on68-6uSPh1JAZLO6gi-P-3VmeBdklKnL0,1541
+checkpointer/storages/storage.py,sha256=hXzHf1i4Vb_JCeUhY2sVIZlpS049YkM1ya1SAW_x7Ls,912
+checkpointer-2.9.1.dist-info/METADATA,sha256=cbv49N5LRSbc-7ejHNEHJn_fSZWaA_1nFNJUuR-IH8E,10977
+checkpointer-2.9.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+checkpointer-2.9.1.dist-info/licenses/LICENSE,sha256=9xVsdtv_-uSyY9Xl9yujwAPm4-mjcCLeVy-ljwXEWbo,1059
+checkpointer-2.9.1.dist-info/RECORD,,

checkpointer-2.8.1.dist-info/METADATA

@@ -1,262 +0,0 @@
-Metadata-Version: 2.4
-Name: checkpointer
-Version: 2.8.1
-Summary: A Python library for memoizing function results with support for multiple storage backends, async runtimes, and automatic cache invalidation
-Project-URL: Repository, https://github.com/Reddan/checkpointer.git
-Author: Hampus Hallman
-License: Copyright 2018-2025 Hampus Hallman
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-License-File: LICENSE
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# checkpointer · [![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Reddan/checkpointer/blob/master/LICENSE) [![pypi](https://img.shields.io/pypi/v/checkpointer)](https://pypi.org/project/checkpointer/) [![pypi](https://img.shields.io/pypi/pyversions/checkpointer)](https://pypi.org/project/checkpointer/)
-
-`checkpointer` is a Python library for memoizing function results. It provides a decorator-based API with support for multiple storage backends. Use it for computationally expensive operations where caching can save time, or during development to avoid waiting for redundant computations.
-
-Adding or removing `@checkpoint` doesn't change how your code works. You can apply it to any function, including ones you've already written, without altering their behavior or introducing side effects. The original function remains unchanged and can still be called directly when needed.
-
-### Key Features:
-- 🗂️ **Multiple Storage Backends**: Built-in support for in-memory and pickle-based storage, or create your own.
-- 🎯 **Simple Decorator API**: Apply `@checkpoint` to functions without boilerplate.
-- 🔄 **Async and Sync Compatibility**: Works with synchronous functions and any Python async runtime (e.g., `asyncio`, `Trio`, `Curio`).
-- ⏲️ **Custom Expiration Logic**: Automatically invalidate old checkpoints.
-- 📂 **Flexible Path Configuration**: Control where checkpoints are stored.
-- 📦 **Captured Variables Handling**: Optionally include captured variables in cache invalidation.
-- ⚡ **Custom Argument Hashing**: Override argument hashing for speed or specialized hashing logic.
-
----
-
-## Installation
-
-```bash
-pip install checkpointer
-```
-
----
-
-## Quick Start 🚀
-
-```python
-from checkpointer import checkpoint
-
-@checkpoint
-def expensive_function(x: int) -> int:
-    print("Computing...")
-    return x ** 2
-
-result = expensive_function(4)  # Computes and stores the result
-result = expensive_function(4)  # Loads from the cache
-```
-
----
-
-## How It Works
-
-When you use `@checkpoint`, the function's **arguments** (`args`, `kwargs`) are hashed to create a unique identifier for each call. This identifier is used to store and retrieve cached results. If the same arguments are passed again, `checkpointer` loads the cached result instead of recomputing.
-
-Additionally, `checkpointer` ensures that caches are invalidated when a function's implementation or any of its dependencies change. Each function is assigned a hash based on:
-
-1. **Function Code**: The hash updates when the function’s own source code changes.
-2. **Dependencies**: If the function calls other user-defined functions, changes in those dependencies also update the hash.
-3. **External Variables** *(with `capture=True`)*: Any global or closure-based variables used by the function are included in its hash, so changes to those variables also trigger cache invalidation.
-
-### Example: Cache Invalidation
-
-```python
-def multiply(a, b):
-    return a * b
-
-@checkpoint
-def helper(x):
-    return multiply(x + 1, 2)
-
-@checkpoint
-def compute(a, b):
-    return helper(a) + helper(b)
-```
-
-If you modify `multiply`, caches for both `helper` and `compute` are invalidated and recomputed.
-
----
-
-## Parameterization
-
-### Custom Configuration
-
-Set up a `Checkpointer` instance with custom settings, and extend it by calling itself with overrides:
-
-```python
-from checkpointer import checkpoint
-
-IS_DEVELOPMENT = True  # Toggle based on your environment
-
-tmp_checkpoint = checkpoint(root_path="/tmp/checkpoints")
-dev_checkpoint = tmp_checkpoint(when=IS_DEVELOPMENT)  # Adds development-specific behavior
-```
-
-### Per-Function Customization & Layered Caching
-
-Layer caches by stacking checkpoints:
-
-```python
-@checkpoint(format="memory")  # Always use memory storage
-@dev_checkpoint  # Adds caching during development
-def some_expensive_function():
-    print("Performing a time-consuming operation...")
-    return sum(i * i for i in range(10**8))
-```
-
-- **In development**: Both `dev_checkpoint` and `memory` caches are active.
-- **In production**: Only the `memory` cache is active.
-
----
-
-## Usage
-
-### Basic Invocation and Caching
-
-Call the decorated function as usual. On the first call, the result is computed and stored in the cache. Subsequent calls with the same arguments load the result from the cache:
-
-```python
-result = expensive_function(4)  # Computes and stores the result
-result = expensive_function(4)  # Loads the result from the cache
-```
-
-### Force Recalculation
-
-Force a recalculation and overwrite the stored checkpoint:
-
-```python
-result = expensive_function.rerun(4)
-```
-
-### Call the Original Function
-
-Use `fn` to directly call the original, undecorated function:
-
-```python
-result = expensive_function.fn(4)
-```
-
-This is especially useful **inside recursive functions** to avoid redundant caching of intermediate steps while still caching the final result.
-
-### Retrieve Stored Checkpoints
-
-Access cached results without recalculating:
-
-```python
-stored_result = expensive_function.get(4)
-```
-
-### Refresh Function Hash
-
-If `capture=True`, you might need to re-hash a function during the same Python session. For that, call `reinit`:
-
-```python
-expensive_function.reinit()
-```
-
-This tells `checkpointer` to recalculate the function hash, reflecting changes in captured variables.
-
----
-
-## Storage Backends
-
-`checkpointer` works with built-in and custom storage backends, so you can use what's provided or roll your own as needed.
-
-### Built-In Backends
-
-1. **PickleStorage**: Stores checkpoints on disk using Python's `pickle`.
-2. **MemoryStorage**: Keeps checkpoints in memory for non-persistent, fast caching.
-
-You can specify a storage backend using either its name (`"pickle"` or `"memory"`) or its corresponding class (`PickleStorage` or `MemoryStorage`) in the `format` parameter:
-
-```python
-from checkpointer import checkpoint, PickleStorage, MemoryStorage
-
-@checkpoint(format="pickle")  # Short for format=PickleStorage
-def disk_cached(x: int) -> int:
-    return x ** 2
-
-@checkpoint(format="memory")  # Short for format=MemoryStorage
-def memory_cached(x: int) -> int:
-    return x * 10
-```
-
-### Custom Storage Backends
-
-Create a custom storage backend by inheriting from the `Storage` class and implementing its methods. Access configuration options through the `self.checkpointer` attribute, an instance of `Checkpointer`.
-
-#### Example: Custom Storage Backend
-
-```python
-from checkpointer import checkpoint, Storage
-from datetime import datetime
-
-class CustomStorage(Storage):
-    def exists(self, path) -> bool: ...  # Check if a checkpoint exists
-    def checkpoint_date(self, path) -> datetime: ...  # Get the checkpoint's timestamp
-    def store(self, path, data): ...  # Save data to the checkpoint
-    def load(self, path): ...  # Load data from the checkpoint
-    def delete(self, path): ...  # Delete the checkpoint
-
-@checkpoint(format=CustomStorage)
-def custom_cached(x: int):
-    return x ** 2
-```
-
-Use a custom backend to integrate with databases, cloud storage, or specialized file formats.
-
----
-
-## Configuration Options ⚙️
-
-| Option          | Type                                | Default              | Description                                               |
-|-----------------|-------------------------------------|----------------------|-----------------------------------------------------------|
-| `capture`       | `bool`                              | `False`              | Include captured variables in function hashes.            |
-| `format`        | `"pickle"`, `"memory"`, `Storage`   | `"pickle"`           | Storage backend format.                                   |
-| `root_path`     | `Path`, `str`, or `None`            | ~/.cache/checkpoints | Root directory for storing checkpoints.                   |
-| `when`          | `bool`                              | `True`               | Enable or disable checkpointing.                          |
-| `verbosity`     | `0`, `1` or `2`                     | `1`                  | Logging verbosity.                                        |
-| `should_expire` | `Callable[[datetime], bool]`        | `None`               | Custom expiration logic.                                  |
-| `hash_by`       | `Callable[..., Any]`                | `None`               | Custom function that transforms arguments before hashing. |
-
----
-
-## Full Example 🛠️
-
-```python
-import asyncio
-from checkpointer import checkpoint
-
-@checkpoint
-def compute_square(n: int) -> int:
-    print(f"Computing {n}^2...")
-    return n ** 2
-
-@checkpoint(format="memory")
-async def async_compute_sum(a: int, b: int) -> int:
-    await asyncio.sleep(1)
-    return a + b
-
-async def main():
-    result1 = compute_square(5)
-    print(result1)  # Outputs 25
-
-    result2 = await async_compute_sum(3, 7)
-    print(result2)  # Outputs 10
-
-    result3 = async_compute_sum.get(3, 7)
-    print(result3)  # Outputs 10
-
-asyncio.run(main())
-```

checkpointer-2.8.1.dist-info/RECORD

@@ -1,16 +0,0 @@
-checkpointer/__init__.py,sha256=HRLsQ24ZhxgmDcHchZ-hX6wA0NMCSedGA0NmCnUdS_c,832
-checkpointer/checkpoint.py,sha256=FZSKQVIXj_Enja0253WDUauO8siUHwlzcr4frHMJzB0,6538
-checkpointer/fn_ident.py,sha256=SWaksNCTlskMom0ztqjECSRjZYPWXUA1p1ZCb-9tWo0,4297
-checkpointer/object_hash.py,sha256=cxuWRDrg4F9wC18aC12zOZYOPv3bk2Qf6tZ0_WgAb6Y,7484
-checkpointer/print_checkpoint.py,sha256=aJCeWMRJiIR3KpyPk_UOKTaD906kArGrmLGQ3LqcVgo,1369
-checkpointer/test_checkpointer.py,sha256=DM5f1Ci4z7MhDnxK-2Z-V3a3ntzBJqORQvCFROAf2SI,3807
-checkpointer/utils.py,sha256=2yk1ksKszXofwnSqBrNCFRSR4C3YLPEAdHUFf-cviRU,2755
-checkpointer/storages/__init__.py,sha256=Kl4Og5jhYxn6m3tB_kTMsabf4_eWVLmFVAoC-pikNQE,301
-checkpointer/storages/bcolz_storage.py,sha256=3QkSUSeG5s2kFuVV_LZpzMn1A5E7kqC7jk7w35c0NyQ,2314
-checkpointer/storages/memory_storage.py,sha256=S5ayOZE_CyaFQJ-vSgObTanldPzG3gh3NksjNAc7vsk,1282
-checkpointer/storages/pickle_storage.py,sha256=idh9sBMdWuyvS220oa_7bAUpc9Xo9v6Ud9aYKGWasUs,1593
-checkpointer/storages/storage.py,sha256=_m18Z8TKrdAbi6YYYQmuNOnhna4RB2sJDn1v3liaU3U,721
-checkpointer-2.8.1.dist-info/METADATA,sha256=z0SbrcyKvHTOgJ6oq0dshV25fBAsqGjMCl_uWmxSFRM,10600
-checkpointer-2.8.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-checkpointer-2.8.1.dist-info/licenses/LICENSE,sha256=9xVsdtv_-uSyY9Xl9yujwAPm4-mjcCLeVy-ljwXEWbo,1059
-checkpointer-2.8.1.dist-info/RECORD,,