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
```
