yokedcache

Async-first caching with the same API across backends: in-process memory (works out of the box), Redis, Memcached, disk, and SQLite. Tag and pattern invalidation, optional HTTP middleware, and production metrics built in.

Use await in FastAPI, Django async views, workers, or plain asyncio. Sync code is welcome too—get_sync / set_sync / @cached on a normal def run the same async implementation, no separate client needed.

Documentation · Changelog · PyPI · Issues

What's included

• Multiple backends — Memory (zero deps), Redis, Memcached, disk, SQLite; per-prefix routing to mix them
• Invalidation — Tag-based, pattern-based, and auto-invalidation on DB writes
• Sync + async — Full async API; sync helpers for scripts and blocking code
• HTTP middleware — ETag / Cache-Control via Starlette (yokedcache[web])
• Resilience — Circuit breaker, retries, stale-if-error
• Observability — Prometheus, StatsD, OpenTelemetry (optional extras)
• CLI — Inspect keys, stats, and run health checks from the shell

Installation

pip install yokedcache

The base install ships with an in-process memory backend—no Redis required to get started. Add extras when you need them:

To require a minimum patch line (for example after a security release): pip install "yokedcache>=1.0.2".

Individual extras: memcached, disk, sqlite, monitoring, tracing, vector, fuzzy, sqlalchemy.

Quick start

Async (memory backend, no Redis needed):

import asyncio
from yokedcache import YokedCache
from yokedcache.config import CacheConfig

async def main():
    cache = YokedCache(CacheConfig())
    await cache.connect()
    await cache.set("user:1", {"name": "Ada"}, ttl=60)
    print(await cache.get("user:1"))
    await cache.disconnect()

asyncio.run(main())

Sync (scripts and blocking code):

import asyncio
from yokedcache import YokedCache
from yokedcache.config import CacheConfig

cache = YokedCache(CacheConfig())
asyncio.run(cache.connect())
cache.set_sync("user:1", {"name": "Ada"}, ttl=60)
print(cache.get_sync("user:1"))
asyncio.run(cache.disconnect())

For Redis: pip install "yokedcache[redis]", then set redis_url="redis://..." on CacheConfig (or the env var YOKEDCACHE_REDIS_URL).

FastAPI example

from fastapi import FastAPI, Depends
from yokedcache import cached_dependency

app = FastAPI()

cached_get_db = cached_dependency(get_db, ttl=300)

@app.get("/users/{user_id}")
async def get_user(user_id: int, db=Depends(cached_get_db)):
    return db.query(User).filter(User.id == user_id).first()

Requirements

• Python 3.10+ (tested on 3.10–3.14)
• Redis is optional; install yokedcache[redis] and point to a Redis 6+ server when you want a shared remote cache

Python 3.9 is not supported on 1.x. Pin yokedcache==0.3.0 only as a temporary bridge—it does not receive security fixes. Upgrade when you can.

Security

Treat Redis and Memcached as trusted stores—anyone who can write arbitrary keys can affect what your app deserializes. From 1.1.0, allow_legacy_insecure_deserialization defaults to False on CacheConfig (and on each backend's own copy of the flag); only set it to True while migrating away from pre-1.0.0 legacy entries.

The optional disk extra pulls in diskcache. From 1.0.2, the disk backend stores JSON-safe wrappers around the same bytes envelope as other backends (no pickle for cached payloads). CVE-2025-69872 still applies to the upstream package metadata until a patched wheel ships—automated scanners may flag it. Skip the disk extra if you don't need it; keep the cache directory non-world-writable if you do. See SECURITY.md.

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Build the docs site locally:

pip install -e ".[docs]"
python scripts/build_docs_site.py
cp CHANGELOG.md site/changelog.md
python -m pdoc yokedcache -o site/api --template-directory site-src/pdoc-template
cd site && python -m http.server 8000

See CONTRIBUTING.md for the full workflow.

License

MIT. See LICENSE.

Maintained by Project Yoked LLC; technical lead Joshua Kac.