cachetta 0.6.3

File-based caching for Python

Cachetta for Python

File-based caching for Python. Part of the Cachetta project, which provides the same caching API in Python and TypeScript -- learn it once, use it in either language.

Three doc layers: this README (overview), the docs/ folder bundled with this package, and the hosted docs site. Each ## below mirrors a section in docs/python.md.

Requires Python 3.12+.

Install

uv add cachetta

Basic Usage

from datetime import timedelta
from cachetta import Cachetta, read_cache, write_cache

cache = Cachetta(path='./cache.json', duration=timedelta(days=1))

with read_cache(cache) as data:
    if data is None:
        data = fetch_data()
        write_cache(cache, data)

→ Basic Usage

Decorators

@Cachetta(path='/my-cache.json')
def get_data():
    return compute_expensive_value()

→ Decorators

Async Support

@Cachetta(path='./async-cache.json')
async def get_async_data():
    return await fetch_data()

I/O for decorated async functions runs via asyncio.to_thread(). Explicit primitives are async_read_cache / async_write_cache.

→ Async Support

Function Wrapper

cache = Cachetta(path='./my-cache.json')
cached_get_data = cache(get_data)
result = cached_get_data()

→ Function Wrapper

Auto Cache Keys

Decorated functions hash their arguments to generate unique paths automatically.

→ Auto Cache Keys

In-Memory LRU

cache = Cachetta(path='./cache.json', lru_size=100)

Thread-safe for concurrent async access.

→ In-Memory LRU

Conditional Caching

cache = Cachetta(path='./cache.json', condition=lambda r: r is not None)

→ Conditional Caching

Stale-While-Revalidate

cache = Cachetta(
    path='./cache.json',
    duration=timedelta(hours=1),
    stale_duration=timedelta(minutes=30),
)

→ Stale-While-Revalidate

Cache Invalidation

cache.invalidate()       # or cache.clear()
await cache.ainvalidate()

→ Cache Invalidation

Cache Inspection

cache.exists()  # bool
cache.age()     # timedelta | None
cache.info()    # dict

Async variants: aexists, aage, ainfo.

→ Cache Inspection

Path Operator

cache = Cachetta(path='./cache')
with read_cache(cache / 'my-data.json') as data:
    ...

→ Path Operator

Dynamic Cache Paths

@Cachetta(path=lambda n: f"./cache/{n}.json")
def foo(n: int):
    ...

→ Dynamic Cache Paths

Specifying Paths

new_cache = cache.copy(read=False, duration=timedelta(days=2))

→ Specifying Paths

Method Decorators

class DataService:
    @Cachetta(path='./cache.json', skip_self=True)
    def get_data(self, user_id):
        ...

→ Method Decorators

Pickle Security

A restricted unpickler blocks arbitrary code execution from tampered cache files. Add custom types to allowed_pickle_types to whitelist them.

cache = Cachetta(path='./cache.dat', allowed_pickle_types={UserProfile})

→ Pickle Security

Error Handling

read_cache yields None for missing or corrupt files.

→ Error Handling

Logging

import logging
logging.getLogger("cachetta").setLevel(logging.DEBUG)

→ Logging

Configuration Reference

Option	Type	Default
path	str | Callable	required
read / write	bool	True
duration	timedelta	7 days
lru_size	int	None
condition	Callable	None
stale_duration	timedelta	None
skip_self	bool	False
allowed_pickle_types	set[type]	None

→ Configuration Reference