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.10+.

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

Per-Argument Cache Files

Pass a callable path to vary the cache file by argument. A str/Path path is used verbatim regardless of arguments.

→ Per-Argument Cache Files

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()       # delete the resolved cache file unconditionally
await cache.ainvalidate()

→ Cache Invalidation

Clearing the Cache

cache.clear()            # sweep dead entries (past duration + stale_duration)
cache.clear(force=True)  # remove the whole path, folder and all
await cache.aclear()

→ Clearing the Cache

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:
    ...

# Subfolder for auto-hashed entries
sub = cache / 'llm-calls'

# Callable for custom layouts (resolved at call time)
custom = cache / (lambda kind, ident: f'{kind}/{ident}.pkl')

→ 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

Methods work as-is; the receiver (self/cls) is not part of the cache key.

class DataService:
    @Cachetta(path=lambda user_id: f'./cache/{user_id}.json')
    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

→ Configuration Reference