belljar 0.1.0__tar.gz

belljar-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.3
+Name: belljar
+Version: 0.1.0
+Summary: Extremely simple to use callable memoization decorator library.
+Keywords: cache,memoization,decorator,dill,persistence,hashing
+Author: Wannes Vantorre
+Author-email: Wannes Vantorre <vantorrewannes@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: dill>=0.4.1
+Requires-Dist: xxhash>=3.6.0
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/VantorreWannes/belljar/belljar
+Project-URL: Repository, https://github.com/VantorreWannes/belljar/belljar
+Project-URL: Issues, https://github.com/VantorreWannes/belljar/issues
+Description-Content-Type: text/markdown
+
+# belljar 🫙
+
+**Conditional memoization for complex runtime state.**
+
+Standard decorators check the cache *before* execution. `belljar` lets you check the cache *during* execution.
+
+By calling `includes()`, you update the hash with runtime state (like file handles or database cursors). If `belljar` detects that this specific state has been processed before, **execution stops immediately** and the cached result is returned.
+
+## Usage
+
+```python
+from belljar import jar, includes
+
+@jar
+def parse_log(file_handle):
+    # 1. State is initially just the function args.
+    
+    # 2. Add runtime state to the hash (e.g., file cursor position).
+    includes(file_handle)
+
+    # CHECKPOINT: 
+    # If this exact sequence (args + file state) exists in the cache,
+    # execution STOPS here and returns the stored value.
+    
+    print("Heavy processing...")
+    return file_handle.read()
+```
+
+## Features
+
+- **Mid-Execution Cache Hits:** Skip the heavy lifting if the intermediate state is recognized.
+- **Complex Serialization:** Uses `dill` instead of `pickle`, supporting lambdas, local classes, and closures.
+- **Zero Config:** caches to `.jar/` by default, or pass a path: `@jar(Path("/tmp/cache"))`.
+
+## Installation
+
+```bash
+uv add belljar
+# or
+pip install belljar
+```

belljar-0.1.0/README.md

@@ -0,0 +1,41 @@
+# belljar 🫙
+
+**Conditional memoization for complex runtime state.**
+
+Standard decorators check the cache *before* execution. `belljar` lets you check the cache *during* execution.
+
+By calling `includes()`, you update the hash with runtime state (like file handles or database cursors). If `belljar` detects that this specific state has been processed before, **execution stops immediately** and the cached result is returned.
+
+## Usage
+
+```python
+from belljar import jar, includes
+
+@jar
+def parse_log(file_handle):
+    # 1. State is initially just the function args.
+    
+    # 2. Add runtime state to the hash (e.g., file cursor position).
+    includes(file_handle)
+
+    # CHECKPOINT: 
+    # If this exact sequence (args + file state) exists in the cache,
+    # execution STOPS here and returns the stored value.
+    
+    print("Heavy processing...")
+    return file_handle.read()
+```
+
+## Features
+
+- **Mid-Execution Cache Hits:** Skip the heavy lifting if the intermediate state is recognized.
+- **Complex Serialization:** Uses `dill` instead of `pickle`, supporting lambdas, local classes, and closures.
+- **Zero Config:** caches to `.jar/` by default, or pass a path: `@jar(Path("/tmp/cache"))`.
+
+## Installation
+
+```bash
+uv add belljar
+# or
+pip install belljar
+```

belljar-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "belljar"
+version = "0.1.0"
+description = "Extremely simple to use callable memoization decorator library."
+readme = "README.md"
+authors = [
+    { name = "Wannes Vantorre", email = "vantorrewannes@gmail.com" }
+]
+
+requires-python = ">=3.14"
+license = { text = "MIT" }
+keywords = ["cache", "memoization", "decorator", "dill", "persistence", "hashing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "dill>=0.4.1",
+    "xxhash>=3.6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/VantorreWannes/belljar/belljar"
+Repository = "https://github.com/VantorreWannes/belljar/belljar"
+Issues = "https://github.com/VantorreWannes/belljar/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

belljar-0.1.0/src/belljar/__init__.py

@@ -0,0 +1,88 @@
+import functools
+import inspect
+import os
+import threading
+from pathlib import Path
+from typing import Any, Callable, Union, cast
+
+import dill
+import xxhash
+
+_context = threading.local()
+_CACHE_PROPERTY_NAME = "cache"
+CACHE_DIR = Path(".jar")
+
+
+class _CacheHit(Exception):
+    def __init__(self, fingerprint: xxhash.xxh64) -> None:
+        self.fingerprint = fingerprint
+
+
+class _CacheState:
+    def __init__(self, dir: Path) -> None:
+        os.makedirs(dir, exist_ok=True)
+        self.dir: Path = dir
+        self._fingerprint = xxhash.xxh64()
+
+    def fingerprint(self) -> xxhash.xxh64:
+        return self._fingerprint
+
+    def update(self, value: Any) -> None:
+        self._fingerprint.update(dill.dumps(value))
+
+    def path(self) -> Path:
+        digest = self._fingerprint.hexdigest()
+        filename = digest + ".dill"
+        return self.dir / filename
+
+    def exists(self) -> bool:
+        return os.path.exists(self.path())
+
+
+def includes(value: Any) -> None:
+    if hasattr(_context, _CACHE_PROPERTY_NAME):
+        cache = cast(_CacheState, getattr(_context, _CACHE_PROPERTY_NAME))
+        cache.update(value)
+        if cache.exists():
+            raise _CacheHit(cache.fingerprint())
+
+
+def jar(dir: Union[Path, Callable] = CACHE_DIR) -> Callable:
+    def factory(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            state = _CacheState(dir if not callable(dir) else CACHE_DIR)
+            state.update(func.__module__)
+            state.update(func.__name__)
+            state.update(inspect.getsource(func))
+            state.update(args)
+            state.update(kwargs)
+
+            setattr(_context, _CACHE_PROPERTY_NAME, state)
+
+            try:
+                if state.exists():
+                    with open(state.path(), "rb") as f:
+                        return dill.load(f)
+
+                output = func(*args, **kwargs)
+
+                with open(state.path(), "wb") as f:
+                    dill.dump(output, f)
+                    return output
+
+            except _CacheHit:
+                with open(state.path(), "rb") as f:
+                    return dill.load(f)
+            finally:
+                delattr(_context, _CACHE_PROPERTY_NAME)
+
+        return wrapper
+
+    if callable(dir):
+        return factory(dir)
+
+    return factory
+
+
+__all__ = ["jar", "includes"]